Agent Skills (SKILL.md) Explained: Formats, Folders and Safety

Published 2026-10-17 · 4 min read · by AgentKit Co

A skill is a folder with one required file, SKILL.md. The file starts with a little YAML (a name and a description) and then plain instructions. The agent reads only the name and description at startup, and loads the rest when your request matches. That is the whole idea, and it is why skills are a good home for procedures that would bloat AGENTS.md or CLAUDE.md.

This guide covers the format, where each tool looks for skills, how skills differ from instruction files, and how to write and vet one. It was checked against the Agent Skills specification, the Claude Code skills docs and the skills CLI documentation on 2026-10-17. These tools change quickly, so re-check the docs for anything you rely on. We also publish 12 free skills you can read or download.

The format

The specification describes skills as an open format, originally developed by Anthropic and now used by many tools. Its client showcase lists Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI and dozens more.

review-my-diff/
├── SKILL.md          # required: frontmatter + instructions
├── scripts/          # optional: code the agent can run
├── references/       # optional: extra docs, loaded on demand
└── assets/           # optional: templates and data

The spec defines six frontmatter fields:

The spec recommends keeping SKILL.md under 500 lines and the body under about 5,000 tokens, and moving detail into references/. Skills load in three stages: name and description at startup, the full file when a task matches, and supporting files only when needed.

Where each tool looks

The .agents/skills/ row comes from the skills CLI documentation, not from each vendor, so check your tool's page before relying on it. Claude Code's docs also describe skills inside plugins, managed enterprise settings and skills synced from your claude.ai account.

One trap: Claude Code accepts extra frontmatter fields, such as disable-model-invocation, context and argument-hint. Claude's docs say uploads to claude.ai and the Skills API accept only the spec's fields, and an unknown key makes the upload fail. If you want one skill to work everywhere, stay with the six fields above.

Skills, AGENTS.md and CLAUDE.md

Use the instruction file for facts that apply to every task: how to run the tests, what never to touch. Use a skill for a procedure you only need sometimes. Claude's docs put it this way: create a skill when you keep pasting the same checklist into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact. A skill's body loads only when used, so it costs almost nothing until then.

If you are unsure which instruction file you need, start with AGENTS.md vs CLAUDE.md vs Cursor rules. The free AGENTS.md generator builds a starting file.

Writing a skill that triggers

• Put the trigger in the description. "Reviews a diff before a PR. Use when asked to review my changes" beats "helps with code". Agents choose skills mostly from this line.
• Keep it short. Claude's docs note that once loaded, a skill's text stays in the conversation, so every line is a recurring cost.
• Demand evidence. Tell the agent to run the command and show the output, to cite file and line, and to list what it did not verify.
• Name the stop conditions. "Stop and ask if the tests cannot run" prevents the worst improvisation.
• Test it. Run a few realistic prompts with the skill on and off in fresh sessions and compare. Claude's docs describe this baseline comparison and a skill-creator plugin that automates it.

Vetting a skill you did not write

A skill is instructions plus, sometimes, scripts, and it can pre-approve tools. Claude's docs warn that a skill can grant itself broad tool access, so review the allowed-tools of skills checked into a repository before you run the agent there. Before installing a skill from a directory or a repo:

1. Read the whole SKILL.md and every file in scripts/.
2. Look for allowed-tools, shell commands, network calls and anything that reads .env files or credentials.
3. Check that the description matches what the body does.
4. Install it in a throwaway project first.

Third-party directories such as skills.sh, Skill Store and Claude Market list community skills, and some run automated scans. A scan is a signal, not a guarantee, so the steps above still apply.

Try some

Our free skills pack has twelve MIT-licensed skills for review, debugging, PR descriptions, refactors, upgrades and auditing your own AGENTS.md. Read them first, edit them, and keep what helps.

Keep reading