Agent Skills are folders of instructions, scripts and reference files that AI coding agents load when a task needs them. Instead of pasting the same release checklist or deployment steps into every prompt, you write them once in a SKILL.md file, commit it to the repository, and any agent that supports the open format can pick it up. This guide covers the format end to end: the frontmatter rules, how to write a description that actually triggers, a complete example skill with a script and a reference file, where agents look for skills, how to validate them in CI, and how to review skills you did not write.

Agent Skills loading flow: the agent reads skill names and descriptions at startup, activates a matching SKILL.md, then loads scripts and references only when needed
Agent Skills load in stages: names and descriptions first, the body on activation, and bundled files only when a step needs them.

From my own work: The first skills I wrote were too long and too vague. A 600-line SKILL.md with a description like helps with WordPress either never activated or filled the context with steps the task did not need. Splitting it into one short skill per job, with the detail moved into reference files, made the agent follow the steps far more reliably.

What Agent Skills are and how agents load them

A skill is a directory that contains, at minimum, a SKILL.md file: YAML frontmatter followed by Markdown instructions. It can also bundle scripts/, references/ and assets/ folders (Agent Skills specification). The key design idea is progressive disclosure: the agent does not read every skill up front. It loads detail in three stages.

Stage What the agent loads Guidance from the spec
Discovery name and description of every installed skill About 100 tokens per skill
Activation The full SKILL.md body of the matching skill Under 5,000 tokens recommended; keep the file under 500 lines
Execution Files in scripts/, references/ or assets/ Only when a step asks for them

That has two practical consequences. You can install many skills without paying a large context cost, and the description is the only thing the agent sees when it decides whether to use a skill. A skill with a weak description is a skill that never runs.

Skills, instruction files, MCP tools or plain scripts?

Skills overlap with other ways of steering coding agents, so pick the one that matches the job:

Mechanism Best for Loaded
Repository instruction file (such as AGENTS.md) Always-true facts: build commands, code style, folder layout Every session
Agent Skill A repeatable procedure: release a plugin, review an Nginx config, write a migration Only when the task matches
MCP server Live access to an external system or API Tools are listed; calls happen at runtime
Script or Makefile target Deterministic steps that need no judgement When someone runs it

The best skills often combine the last two: the skill explains when and why, and calls a script for the parts that must be exact. If you are building agents yourself rather than configuring existing ones, the guide to building autonomous agents with local LLMs covers the runtime side.

Where agents look for skills

The format is shared, but each agent documents its own search folders. GitHub Copilot, for example, reads project skills from .github/skills/ and personal skills from ~/.copilot/skills/ (GitHub Docs: agent skills), and VS Code lists the project and personal folders each supported agent reads, including .agents/skills/ (VS Code: Agent Skills). Check the documentation of the agents your team uses, commit project skills to the repository so everyone gets the same version, and keep personal skills for habits that are yours alone.

Step 1: create the skill folder

The example in this guide is a skill that prepares a WordPress plugin release: it checks that version numbers agree, runs the coding standards, and builds a zip. Create the folder in the location your agent reads:

mkdir -p .github/skills/wp-plugin-release/{scripts,references}
cd .github/skills/wp-plugin-release

# final layout
# wp-plugin-release/
#   SKILL.md                    required: frontmatter + instructions
#   scripts/check-versions.sh   exact checks the agent runs
#   references/readme-rules.md  detail loaded only when needed

Step 2: frontmatter rules

Only two fields are required. The spec sets these constraints (Agent Skills: frontmatter):

Field Required Rules
name Yes 1 to 64 characters; lowercase letters, numbers and hyphens; no leading, trailing or double hyphens; must match the folder name
description Yes 1 to 1,024 characters; what the skill does and when to use it
license No A license name or a bundled license file
compatibility No Up to 500 characters on environment needs, such as required tools or network access
metadata No String keys to string values, such as author and version
allowed-tools No Space-separated pre-approved tools; experimental and not supported everywhere

Step 3: write a description that triggers

Write the description for the moment of choice: the agent has a user request and a list of short descriptions, and must pick one. A good description names the task, the inputs, and the words a user would actually type.

  • Weak: Helps with plugins.
  • Better: Prepares a WordPress plugin release.
  • Good: Prepares a WordPress plugin release: checks that the plugin header Version, readme.txt Stable tag and changelog agree, runs PHPCS and builds an installable zip. Use when the user asks to release, tag, bump the version of, or package a WordPress plugin.

Two habits help: say what the skill does in the first sentence and when to use it in the second, and avoid overlapping descriptions between skills, because two skills that both claim deployment make activation unpredictable.

Step 4: the complete SKILL.md

The body has no required structure. Numbered steps, explicit commands and a clear definition of done work best, because the agent follows them literally.

---
name: wp-plugin-release
description: Prepares a WordPress plugin release. Checks that the plugin header Version, readme.txt Stable tag and changelog agree, runs PHPCS and builds an installable zip. Use when the user asks to release, tag, bump the version of, or package a WordPress plugin.
license: MIT
compatibility: Requires bash, git, php, composer and zip.
metadata:
  author: example-team
  version: "1.2"
---

# WordPress plugin release

## Before you start
- Work on a clean branch. Run `git status --porcelain`; stop and ask if it is not empty.
- Ask for the new version number if the user did not give one. Use SemVer (1.4.0).

## Steps
1. Update the version in three places:
   - the `Version:` line in the main plugin file
   - `Stable tag:` in `readme.txt`
   - a new `= 1.4.0 =` entry at the top of `== Changelog ==` in `readme.txt`
2. Run `bash .github/skills/wp-plugin-release/scripts/check-versions.sh`.
   Fix every mismatch it reports before continuing.
3. Run `composer run phpcs`. Fix errors; do not add ignore comments.
4. Build the zip:
   `git archive --format=zip --prefix=my-plugin/ -o my-plugin.zip HEAD`
5. Show the user the diff and the zip size. Do not push or tag unless asked.

## Rules
- If readme.txt fields are unclear, read `references/readme-rules.md`.
- Never edit files in `vendor/` or `node_modules/`.

## Done when
- check-versions.sh exits 0, PHPCS passes, and my-plugin.zip exists.

Step 5: bundle a script for the exact parts

Anything that must be exact belongs in a script, not in prose. The spec asks that scripts be self-contained or document their dependencies, print helpful errors and handle edge cases (Agent Skills: scripts).

#!/usr/bin/env bash
# scripts/check-versions.sh: compare plugin header, readme Stable tag and changelog
set -euo pipefail

main=$(grep -l -m1 '^[[:space:]]**?[[:space:]]*Plugin Name:' ./*.php | head -n1 || true)
[ -n "$main" ] || { echo "ERROR: no main plugin file with a Plugin Name header"; exit 2; }
[ -f readme.txt ] || { echo "ERROR: readme.txt not found"; exit 2; }

header=$(grep -m1 -i '^[[:space:]]**?[[:space:]]*Version:' "$main" | sed -E 's/.*[Vv]ersion:[[:space:]]*//' | tr -d 'r ')
stable=$(grep -m1 -i '^Stable tag:' readme.txt | sed -E 's/^[Ss]table [Tt]ag:[[:space:]]*//' | tr -d 'r ')
changelog=$(awk '/^== Changelog ==/{f=1;next} f && /^= /{gsub(/[= r]/,"");print;exit}' readme.txt)

echo "header=$header stable=$stable changelog=$changelog"
fail=0
[ "$header" = "$stable" ]    || { echo "MISMATCH: $main Version ($header) != Stable tag ($stable)"; fail=1; }
[ "$header" = "$changelog" ] || { echo "MISMATCH: newest changelog entry ($changelog) != $header"; fail=1; }
[ "$fail" -eq 0 ] && echo "OK: versions agree"
exit $fail

Step 6: move detail into references

Detail the agent needs only sometimes goes in references/, linked from SKILL.md with a relative path. The spec recommends keeping references one level deep from SKILL.md and keeping each file focused, since agents load them on demand (Agent Skills: file references). A good reference is a short list of rules, not a copy of a handbook.

# references/readme-rules.md

- Stable tag must equal the Version header in the main plugin file. Never use "trunk".
- Tested up to: major.minor of the newest WordPress tested, numbers only (7.1).
- Short description: one line under the header block, 150 characters or fewer, no markup.
- Tags: at most 5, comma separated, no competitor names.
- Keep only recent changelog entries in readme.txt; move older ones to changelog.txt.

The rules in that file come from the WordPress.org readme standard, checked again at release time in the WordPress.org plugin deploy guide.

Step 7: validate Agent Skills locally and in CI

The reference library skills-ref checks frontmatter and naming rules. Its README describes it as a demonstration library, so treat it as a linter, not a gate on its own (agentskills/agentskills on GitHub).

python3 -m venv .venv && . .venv/bin/activate
pip install "git+https://github.com/agentskills/agentskills.git#subdirectory=skills-ref"
skills-ref validate .github/skills/wp-plugin-release

For CI, a small dependency-light check catches the mistakes that break discovery: a name that does not match its folder, a missing or oversized description, or a body that has grown too long.

# scripts/lint_skills.py  -  usage: python3 scripts/lint_skills.py .github/skills
import pathlib, re, sys
import yaml  # pip install pyyaml

NAME = re.compile(r'^[a-z0-9]+(-[a-z0-9]+)*$')
errors = 0
for skill in sorted(pathlib.Path(sys.argv[1]).glob('*/SKILL.md')):
    text = skill.read_text(encoding='utf-8')
    m = re.match(r'^---n(.*?)n---n(.*)$', text, re.S)
    if not m:
        print(f'{skill}: missing YAML frontmatter'); errors += 1; continue
    meta, body = yaml.safe_load(m.group(1)) or {}, m.group(2)
    name, desc = str(meta.get('name', '')), str(meta.get('description', '')).strip()
    checks = [
        (NAME.match(name) and len(name) <= 64, 'name must be lowercase, digits and single hyphens, max 64'),
        (name == skill.parent.name, f'name "{name}" must match folder "{skill.parent.name}"'),
        (0 < len(desc) <= 1024, 'description must be 1-1024 characters'),
        (len(body.splitlines()) <= 500, 'body over 500 lines: move detail to references/'),
    ]
    for ok, msg in checks:
        if not ok:
            print(f'{skill}: {msg}'); errors += 1
sys.exit(1 if errors else 0)
# .github/workflows/skills.yml
name: Lint agent skills
on:
  pull_request:
    paths: ['.github/skills/**']
permissions:
  contents: read
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-python@v7
        with:
          python-version: '3.13'
      - run: pip install pyyaml
      - run: python3 scripts/lint_skills.py .github/skills
      - run: shellcheck .github/skills/*/scripts/*.sh

Step 8: test that the skill triggers and finishes

Validation proves the file is well formed, not that it works. Keep a short list of prompts next to each skill and try them after every change to the description or steps:

  • Should trigger: release version 1.4.0 of this plugin, bump the plugin version and build a zip.
  • Should not trigger: fix this PHP warning, deploy the theme to staging.

Watch whether the agent activated the skill, followed the steps in order, ran the script and stopped at the Done when line. If it skips a step, make the step a command. If it activates for unrelated work, narrow the description.

Review third-party skills like code

A skill can tell an agent to run its scripts, so installing someone else’s skill is closer to adding a dependency than to reading a blog post. Before you add one:

  • Read every file, including scripts and references, and look for network calls, curl | sh patterns and writes outside the project.
  • Pin it: vendor a reviewed copy into the repository rather than pulling a moving branch.
  • Never put secrets in a skill. Read them from the environment or a secret manager at runtime.
  • Treat allowed-tools as a convenience, not a security boundary; support varies between agents, and your agent’s own permission settings still decide what runs.

Skills shared with outside contributors deserve the same review rules as the rest of the repository, as described in the contributor-friendly open source guide, and generated docs such as a skill index can be kept current the same way as a Markdown table of contents.

Agent Skills checklist

  • One skill per job, with a folder name that equals the name field.
  • A description that says what it does and when to use it, with the words users type.
  • Numbered steps, explicit commands and a Done when line.
  • Exact checks in scripts/ with clear exit codes and messages.
  • Detail in references/, one level deep; SKILL.md under 500 lines.
  • Linted in CI and tested with prompts that should and should not trigger it.
  • Third-party skills read, pinned and free of secrets.

Want this done on your own server or site?

I am Saizul Amin, a web developer and technical SEO consultant. I set up and harden VPS servers, migrate WordPress sites, fix indexing problems and build automations. See my portfolio or get in touch.

FAQ

What is a SKILL.md file?

It is the required file of an Agent Skill: YAML frontmatter with at least a name and a description, followed by Markdown instructions. The folder around it can also hold scripts, reference documents and assets that the agent loads when a step needs them.

Which fields are required in Agent Skills frontmatter?

Only name and description. The name must be lowercase letters, numbers and single hyphens, at most 64 characters and equal to the folder name. The description can be up to 1,024 characters.

Why does my skill never activate?

Usually the description is too vague or overlaps with another skill. Agents only see names and descriptions when choosing, so describe the task, the trigger phrases and the inputs specifically, and test with real prompts.

How long should a SKILL.md be?

The specification recommends keeping the body under about 5,000 tokens and under 500 lines. Move detailed rules, examples and schemas into files in a references folder and link to them.

Are Agent Skills safe to install from the internet?

Only after review. A skill can instruct an agent to run its bundled scripts, so read every file, pin a reviewed copy in your repository and keep secrets out of it, just as you would with any code dependency.

Sources

NEW BLOGS. REAL STRATEGIES. REAL RESULTS.

Join our community and receive powerful SEO tips, web optimization guides, and growth strategies as soon as they’re published.

Don’t just read blogs — stay ahead of the competition.

We don’t spam! Read our privacy policy for more info.

Share.
Leave A Reply