Skip to content
Agentic Coding Guide

SKILL.md

SKILL.md is a documented file format for agent skills, not a universal single-file repo convention like AGENTS.md. It matters because skills are one of the clearest ways to package specialized instructions, examples, and supporting files for tasks an agent should perform repeatedly.

This pattern is strongest in Claude Code and GitHub Copilot. Cursor and Gemini currently emphasize rules, custom commands, and project context instead of the same SKILL.md workflow, so treat “skills” as a portable concept with tool-specific implementations.

Best practices

Section titled “Best practices”
  • Use a separate skill directory for each reusable task
  • Name the directory and skill for a concrete outcome
  • Add a clear description of what the skill does and when to use it
  • Keep each skill narrowly scoped
  • Include examples, scripts, or templates only when they materially help
  • Distinguish between reference skills and task-execution skills
  • Put reusable background knowledge in skills, not only in chat prompts
  • Keep repo-specific skills in version control

What not to do

Section titled “What not to do”
  • Do not create one giant “everything” skill
  • Do not treat SKILL.md as a universal top-level repo file
  • Do not assume every agent tool supports the same skill format
  • Do not use vague names like coding or misc
  • Do not duplicate all of AGENTS.md into every skill
  • Do not create a skill when a short rule or checklist would do

Examples

Section titled “Examples”

This is a good skill because it follows the documented skill pattern: one directory per skill, a SKILL.md entrypoint, a clear description, and task-specific instructions. It is easy for an agent to discover, load, and apply.

Repo paths:

  • /.claude/skills/bug-fix/SKILL.md
  • /.github/skills/bug-fix/SKILL.md
---
name: bug-fix
description: Fixes regressions and broken behavior. Use when debugging a failing feature, test, or production issue.
---


When using this skill:


1. Reproduce the issue first.
2. Identify the smallest safe fix.
3. Preserve existing interfaces unless the task requires a change.
4. Add or update a regression check when possible.
5. Run the relevant verification commands before finishing.
6. Summarize root cause, fix, and residual risk.

This is a bad skill because it uses the right file shape but bad content. It is too broad, duplicates repo-level rules, and gives the agent no concrete trigger or verification contract.

Repo path:

  • /.claude/skills/coding/SKILL.md
  • /.github/skills/coding/SKILL.md
---
name: coding
description: General coding guidance for this repository.
---


When using this skill:


- Follow existing patterns.
- Write clean and maintainable code.
- Use best practices.
- Follow best practices.
- Consider performance and readability.
- Review related files as needed.
- Test as appropriate.

Agent Prompt

Section titled “Agent Prompt”

Use this prompt to have an agent create a real skill in the documented format.

Create a reusable agent skill for this repository.


Requirements:
- Create one skill directory for one repeated task in this repo.
- Use the documented `SKILL.md` format with a clear name and description.
- Put the skill at either `/.claude/skills/<skill-name>/SKILL.md` or `/.github/skills/<skill-name>/SKILL.md`, depending on which location best fits this toolchain.
- Make the skill narrowly scoped and task-specific.
- Include the exact steps the agent should follow.
- Include verification requirements when the task changes code or behavior.
- Add supporting files only if they materially improve the skill.
- Do not create a top-level `/SKILLS.md` file.
- Do not use vague skill names like `coding` or `misc`.


Output:
- Create the skill directory and `SKILL.md`
- Use concise markdown
- Optimize for quick scanning and reliable reuse

References

Section titled “References”