Agent skills

Required

• Give each skill one task and name it for that task

  Required

  Each skill does one task and is named with a verb and an object, such as release-mobile-app. Arguments narrow the scope instead of a second skill.

• Write a description that says when to use the skill

  Required

  Every skill's description says what it does, when to use it and the words people type to ask for it, in under 1024 characters.

• Keep project skills in the repository and review them like code

  Required

  Commit every skill the team relies on to the repository, and review changes to it like code. Personal skills stay in your home folder and never hold team rules.

• Ask before a skill changes data or spends money

  Required

  A skill that deletes or changes data, deploys, sends messages or spends money shows its plan and waits for a yes. After acting, it runs a check that proves the result.

Recommended

• Turn repeated procedures into skills

  Recommended

  Write a skill for a task with three or more steps that you have asked an agent to do twice. Keep facts in the instructions file and fixed steps in plain scripts.

• Keep the skill file short and put fixed steps in scripts

  Recommended

  Keep each SKILL.md under 500 lines. Move every step that needs no judgement into a script the skill runs, and long reference text into files it links.

• Test each skill and keep it current

  Recommended

  Test each skill on a fixed set of three or more tasks before you change it, and keep a log of its runs. A check fails when a skill names a path or command that no longer exists.

Avoid

• Copying rules the agent already has into a skill

  Avoid

  Do not paste the instructions file or another skill's steps into a skill. Two copies drift apart, and the agent follows whichever it read last.