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.
Write once, check each client
Can one SKILL.md work across agents?
Yes, compatible agents can reuse the same skill format. A text-only workflow may need no body changes. A workflow that calls a particular tool, runs a script or uses an account needs those dependencies in every target client. Copy the whole skill folder when the instructions reference other files.
On 22 October 2026, AAIF announced Agent Skills as a project contributed by Anthropic. This changes the home of the standard; it does not certify a particular skill or guarantee identical behavior across agents.
1. Share the workflow
Keep the task, input requirements, output shape and stopping conditions in SKILL.md. Use relative links for bundled references.
2. Match the environment
Check tools, executables, operating system, network access and credentials. Replace hard-coded paths and client-only instructions.
3. Verify the result
Check discovery first, then run the same small input in each client. Compare the requested output and permission behavior.
Use name and description as the shared core. The compatibility field records environment requirements; it does not install them. allowed-tools is experimental in the standard, and client extensions are not universal permission controls. Agent Skills specification.
Three different jobs: skills, repository instructions and MCP
- SKILL.md: a reusable procedure loaded for a task.
- AGENTS.md: repository guidance for clients that support it; it is not a skill bundle.
- MCP: a connection to tools or resources. A skill can explain how to use those tools, but does not create the connection or supply credentials.
Local directories do not imply cloud availability. Check Claude Code session rules, Cursor skill syncing, and the target client documentation before distributing a local-only workflow to remote users.
A portable first example: no tools or accounts
Start with a workflow over text the user supplies. This separates a loading problem from a missing tool or credential. The following is an original teaching example, not a cross-client test result.
summarize-decision/SKILL.md
--- name: summarize-decision description: Turn supplied meeting notes into a decision, owner and next step. Use when the user asks for a decision summary. Ask for the notes if none were supplied. --- 1. Read only the notes supplied in the conversation. Do not browse or edit files. 2. Return exactly three lines: Decision, Owner, Next step. 3. Write "Not stated" for missing information. Do not invent names or deadlines.
Save the same text under the client directory listed below. This example has no scripts, MCP servers, external requests or secret values.
Input to try
Use summarize-decision. Notes: We agreed to try the onboarding checklist. Maya will draft it. No deadline was set.
Expected content, not a measured result
Decision: Try the onboarding checklist. Owner: Maya. Next step: Draft the checklist; deadline not stated.
In each client, explicitly select the skill once, then try a natural request matching its description. If explicit selection works but discovery does not, inspect the description and loading scope. If both load but produce different answers, compare model behavior and instructions. Do not add network or file permissions to fix a text-only task.
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
Local Claude Code project skills use this directory; account-synced and cloud skills have a different loading route.
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
This is the documented default. Check the active profile or overridden Hermes home before copying files.
SKILL.md anatomy
The format separates metadata, instructions and supporting files. Keep the core procedure easy to load; link longer references where they become useful. Extra files are allowed by the standard.
| 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
These are local installation examples, checked on 23 October 2026. The same folder may be accepted by more than one client, but a local install is not automatically available in a remote or cloud session. Confirm the active profile, workspace and installation method.
| Client | Local location | First check |
|---|---|---|
| Claude Code (local project) | .claude/skills/<name>/SKILL.md | Invoke /<name> in a trusted local project. Personal skills use ~/.claude/skills/.Official client documentation |
| Cursor (local project) | .cursor/skills/<name>/SKILL.md (or .agents/skills/) | Use the slash menu or a matching task. Local user skills may use ~/.cursor/skills/ or ~/.agents/skills/.Official client documentation |
| OpenAI Codex CLI | .agents/skills/<name>/SKILL.md | In a Codex CLI session, /skills or $ selects the skill. User-level skills live under ~/.agents/skills/.Official client documentation |
| Hermes Agent | ~/.hermes/skills/<name>/SKILL.md | Confirm the active Hermes profile and skill directory; external directories can also be configured. Review any agent-authored edits.Official client documentation |
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.