Short answer
AGENTS.md gives an AI coding agent instructions about a project, such as commands, code style, and test rules. SKILL.md explains how to complete one reusable task. Use AGENTS.md for project context and SKILL.md for a focused workflow.
Words used in this guide
- Workflow: a set of steps used to finish a task.
- Repository or repo: a project folder whose changes are saved and tracked.
What this means
AGENTS.md describes the project
Use AGENTS.md for information an AI coding agent needs while working in a repository. It can list build commands, test steps, folder rules, code style, and important limits. Keep it short enough to review when the project changes.
SKILL.md describes a task
A SKILL.md file is the main instruction file inside an Agent Skill. It should say when the skill is useful, what information it needs, which steps to follow, what result to produce, and which actions to avoid.
A project can use both
AGENTS.md can tell the agent how the repository works. A skill can then provide detailed steps for a task such as code review or release preparation. Do not repeat the same project facts in every skill.
Simple steps
- Put shared repository facts and commands in AGENTS.md.
- Choose one repeated task that needs more detailed instructions.
- Create a folder for the skill and add SKILL.md.
- Write the task purpose, inputs, steps, output, and safety limits.
- Test the skill while the project instructions are active.
- Package the skill when several projects need the same version.
Where to go next
If you want to try this in a real project, start with the install guide, then read how to use AIPM. If you want to share your own workflow, read the publishing guide.
FAQ
Should SKILL.md contain all project instructions?
No. Keep general repository instructions in AGENTS.md. Put only the information needed for the skill's task in SKILL.md.
Can one skill work in several repositories?
Yes, when the skill avoids project-specific assumptions or clearly explains the information each project must provide.
Sources
How this guide was checked
Abhishek Srivastava reviewed this guide for plain English and current product behavior. Official references are linked above when the guide depends on outside product details. Product details can change, so the review date is shown at the top of the page.