What a skill actually is
A skill is an onboarding file for one repeated job. The agent already knows how to write, search, and reason. The skill exists to add the procedure, the stop condition, and the local files that a general model cannot invent safely.
AgentSkillsHub already covers discovery at /guides/agent-skills-hub/ and library structure at /guides/skills-library-for-agents/. This guide owns the authoring contract: when to create the file, what must be in it, where to install it, and which failure modes mean you should delete it.
How to choose whether to create one
Create a skill when the same workflow has shown up more than once, the steps are easy to get wrong, and you can name the allowed tools. Do not create a skill to store a witty prompt, to wrap an MCP server you have not reviewed, or to give an agent production write access.
Name one repeated job
Write the user request that should load this skill. If you cannot name three real prompts, you do not have a skill yet. You have a note.
Put the trigger in description
The description is the load contract. Say what the skill does and when to use it. Do not hide the trigger in a later “when to use” heading.
Keep the body short
Give the agent the sequence, the stop condition, and pointers to scripts or references. Do not paste a manual the model already knows.
Declare the permission boundary
List files, commands, network hosts, and credentials the skill may touch. If a step needs more access than the first proof, split the skill or stop.
Install in the exact client path
Create one folder per skill and put SKILL.md at the root of that folder. Confirm the live client directory instead of copying an old path from a chat answer.
Prove one reversible case
Reload the client, confirm the skill is visible, run the smallest useful task, and keep a rollback: delete or disable the folder.
Minimum SKILL.md
--- name: review-public-docs description: Fetch a public documentation URL, extract the live install command and caution notes, and stop if the page is not public. Use when the user asks to check current docs, changelogs, or official install paths. --- 1. Confirm the URL is public documentation, not an admin panel or authenticated app. 2. Read only the install command, arguments, and caution notes. 3. Compare the live command with any cached snippet before recommending it. 4. Stop if the page requires auth, the package is unpublished, or the next step needs a secret.
This is a first-proof skill, not a product. Copy it only if the job is public documentation review.
Codex project folder
mkdir -p .agents/skills/review-public-docs
Create the folder first. Then add SKILL.md at the skill root. Do not nest the file under src/.
Claude project path
.claude/skills/review-public-docs/SKILL.md
Use this only after the Claude client still lists project skills under .claude/skills/.
Cursor project path
.cursor/skills/review-public-docs/SKILL.md
Cursor Agent Skills are SKILL.md workflows. Rules stay in rule files. MCP stays a separate permission surface.
Hermes local path
~/.hermes/skills/review-public-docs/SKILL.md
Hermes can also stage agent-authored edits. Review pending files before they become active.
SKILL.md anatomy
Most clients load skills in three layers: metadata first, body after a match, extra files only when the procedure points to them. That is why a long README inside the skill folder is waste, not documentation.
| Part | Role | Authoring rule |
|---|---|---|
| name | Stable identifier | Use a short kebab-case name that matches the folder. Do not rename it after teammates start invoking it. |
| description | Load trigger | Include the job and the user language that should activate it. Clients usually read this before the body. |
| body | Procedure | Imperative steps, expected output, and a stop condition. Point to extra files instead of growing past a few hundred lines. |
| scripts/ | Deterministic work | Put repeated, fragile commands here so the agent does not rewrite them. Test the script before the skill ships. |
| references/ | On-demand docs | Schemas, API notes, and long examples belong here. Link them from SKILL.md so the agent knows when to open them. |
| assets/ | Output files | Templates, fonts, and boilerplate that should be copied, not loaded into context. |
Install paths by client
The file format is shared. The directory is not. If a directory, plugin page, or AI answer gives you a path that the current client does not list, stop and check the client docs instead of inventing a second folder.
| Client | Current default | First check |
|---|---|---|
| Claude Code / Claude skills | .claude/skills/<name>/SKILL.md | The skill appears in the client skill list and matches one real prompt. |
| Cursor Agent Skills | .cursor/skills/<name>/SKILL.md | The skill can be discovered during a matching task or invoked from the slash menu. |
| OpenAI Codex CLI | .agents/skills/<name>/SKILL.md | codex /skills lists the new folder. Global copy lives under ~/.codex/agents/skills/. |
| Hermes Agent | ~/.hermes/skills/<name>/SKILL.md | Review origin and pending changes before accepting an agent-authored edit. |
Codex details live on /guides/codex-skills/. Hermes review and approval live on /guides/hermes-agent-skills/. Cursor Skills vs Rules vs MCP live on /guides/cursor-skills-hub/.
Worked first proofs
Public docs review
Use the template above. The expected result is the live install command, the caution note, and a stop if the package is unpublished. This proves trigger, output shape, and the no-auth boundary.
Repo preflight, no writes
The skill may read a single project folder and list missing tests or config. It may not commit, push, or edit files on the first run. Promote write steps only after the read-only proof is saved.
Team copy with rollback
Share the folder, the client path, the first prompt, and the delete step. Do not share a zip of mixed skills from a marketplace until each file has an owner and a review date.
Common errors and fixes
The client never loads the skill.
Likely cause: The description does not mention the user request, or the when-to-use text is only in the body.
Fix: Rewrite description so it names the job and the phrases that should trigger it. Reload the client and test with those exact phrases.
The skill fires on unrelated tasks.
Likely cause: The description is a broad mission such as “help with coding” or “use when working with files.”
Fix: Narrow the trigger to one workflow, one input type, and one stop condition. Split extra jobs into a second skill.
The folder exists but the client says the skill is missing.
Likely cause: Wrong client directory, SKILL.md not at the skill root, or the client was not restarted.
Fix: Confirm the live path for that client, keep one SKILL.md per folder, and fully reload. Do not nest SKILL.md under an extra src/ folder.
The first run asks for a token or writes outside the project.
Likely cause: The procedure copied a marketplace skill or an MCP-style command without a permission review.
Fix: Disable the skill. Read every referenced file. Move secrets out. Re-run only after the write target is a disposable folder.
The agent ignores the script and rewrites the command.
Likely cause: SKILL.md does not tell the agent when to execute the bundled script, or the script was never tested.
Fix: Name the script in the procedure, state when to run it, and verify the script independently before the next agent run.