| name | make-skill |
| description | Use when creating, improving, comparing, evaluating, reviewing or packaging Agent Skills following the agentskills.io specification. Also use when deciding whether a skill is the right solution vs MCP servers, Claude Rules Files, CLAUDE.md or AGENTS.md. Handles SKILL.md authoring, frontmatter optimization, description writing, progressive disclosure, platform targeting, invocation control, vendor-specific extensions, and distribution. |
| metadata | {"author":"Serghei Iakovlev","version":"2.1","category":"meta"} |
Creating Agent Skills
Author Agent Skills against the agentskills.io specification. A skill is a self-contained directory of instructions, scripts, and resources that turns a general-purpose agent into a specialist for one focused domain.
Core Philosophy
Context is shared. Your skill's tokens compete with the system prompt, conversation history, other skills, and the user's request. Once SKILL.md loads it stays in context for the rest of the turn. Every line must earn its place.
The agent is already smart. Add only context it lacks. Cut explanations of well-known concepts (PDFs, for-loops, HTTP, JSON) and any sentence whose absence would not confuse a competent agent.
Reason over command. Prefer "Use pdfplumber because it handles multi-column layouts and rotated text better than alternatives" to "ALWAYS use pdfplumber". The reasoning becomes the rubric for cases the skill did not anticipate.
Write for the agent, not the human reader. The audience is an LLM ingesting tokens, not a person browsing a wiki page. Optimize for density and clarity, not visual aesthetics. Visual decoration — hard wraps that imply meaningful line breaks, blockquotes around examples, redundant "why this works" paragraphs after every code block, three-deep ladders of indented bullets, decorative Tip:/Note: wrappers around single sentences — costs tokens and earns nothing. See references/writing-patterns.md § Density for dense-vs-decorative examples.
Skill Anatomy
skill-name/
├── SKILL.md # required: YAML frontmatter + markdown body
├── scripts/ # optional: executable code; output enters context
├── references/ # optional: docs loaded on demand
└── assets/ # optional: templates, schemas, images
Only SKILL.md is required. Drop empty directories.
Running scripts bundled with this skill
Script paths are resolved relative to this SKILL.md, not the agent's CWD. If a relative command fails, prefix it with the directory the platform loaded SKILL.md from.
Fallback. If python3 is missing or a script cannot be located, every procedure here ships a manual alternative — follow that instead.
Workflow
Phase 1: Scope the skill
Before writing, answer all of:
- Is a skill the right tool? See references/skills-ecosystem.md. Live data, auth, write operations on external systems → MCP. Always-on rules → custom instructions. Project facts → AGENTS.md. User-triggered templates → prompt files. Reusable procedural how-to → skill.
- What single capability does this skill provide? One focused domain. If the answer requires "and", split.
- Target platform(s). Claude Code only? Codex only? Multiple? Determines which frontmatter fields are available — see § Platform targeting below.
- Invocation model. Model-invoked (the agent decides when to load it), user-invoked only (
/skill-name or $skill-name), or both? Determines how the description should be written and which fields you set — see § Invocation model below and Phase 3.
- What does the agent lack? Add only that.
- What does success look like? Output format, validation step, quality bar.
If the user is converting an existing workflow ("turn this into a skill"), extract: steps, tools, corrections, I/O formats. Confirm the four answers above before scaffolding.
Phase 2: Initialize
python3 scripts/init_skill.py <skill-name> --path <output-directory>
Fallback. Create the directory manually with the skill name; add a SKILL.md from the template in Phase 3 plus only the subdirectories you actually need.
Phase 3: Frontmatter
---
name: skill-name
description: "What this skill does AND when to use it. Max 1024 chars."
---
name rules (must match the parent directory):
- 1-64 chars; lowercase alphanumeric and single hyphens
- No leading/trailing/consecutive hyphens
- No reserved words (
anthropic, claude)
- Prefer gerund:
processing-pdfs, analyzing-data, testing-code
Description by invocation model
The description's purpose changes depending on who invokes the skill. Get this wrong and the description is either dead tokens or a missed trigger.
| Invocation | What the description is for | Style |
|---|
| Model-invoked | The model scans descriptions of every installed skill at startup to decide which to load. | What it does + explicit triggers ("Use when ..."). Edge cases. Slightly pushy. Negative triggers if it over-fires. |
| User-invoked only | The slash-command picker / $skill autocomplete shows it to the user. The model never sees it. | Terse, accurate label of what the skill does. No "Use when ..." triggers. No marketing copy. The user already knows what they typed. |
| Both | The model decides whether to auto-load; the user can also force-invoke. | Triggers for the model, kept concise so the user-facing label is still readable. |
Invocation is a frontmatter decision, not a guess:
- Claude Code.
disable-model-invocation: true removes the description from the model's context entirely. Triggers in it are dead tokens. user-invocable: false does the inverse — only the model invokes; users do not see it.
- OpenAI Codex.
policy.allow_implicit_invocation: false in agents/openai.yaml makes the skill explicit-only ($skill-name); triggers in the description are equally dead.
- Cross-platform. No standard equivalent. Either rely on description-driven discovery or ask the user to invoke explicitly.
Always third person. Descriptions are injected into the system prompt. "Processes PDFs", not "I can help you process PDFs".
No XML tags, no [TODO, ≤ 1024 characters.
Negative triggers for model-invoked skills that fire too broadly:
description: "Advanced statistical analysis for CSV files. Use for regression, clustering, hypothesis testing. Do NOT use for basic data exploration, formatting, or simple aggregation."
Debug a model-invoked description by asking the agent: "When would you use the [skill] skill?" Compare the agent's quoted understanding with your intent.
For the full optional-field reference (license, compatibility, metadata, allowed-tools, plus Claude Code and Codex extensions), see references/frontmatter-fields.md.
Phase 4: Body
The body loads when the skill activates and stays in context for the rest of the turn. Keep it under 500 lines; split surplus into reference files.
Pick a structure:
| Pattern | Best for | Key feature |
|---|
| Workflow | Sequential processes | Step-by-step with checklist |
| Task-based | Tool collections | Grouped by operation type |
| Reference | Standards/specs | Organized by domain |
| Conditional | Branching logic | Decision tree pointing to references |
See references/writing-patterns.md for examples, freedom calibration, multishot prompting, checklists, script integration, and progressive disclosure.
Match freedom to fragility:
- High freedom (creative tasks, code review): general direction, trust the agent
- Medium freedom (reports, analysis): templates with adaptation guidance
- Low freedom (migrations, format ops): exact scripts, exact sequence
Writing principles:
- Imperative: "Extract text with pdfplumber", not "You can extract text"
- One default approach per task; mention alternatives only when context demands
- Concrete I/O examples beat verbal descriptions for teaching style
- Consistent terminology: pick one term ("field", not "field" / "control" / "box")
- Workflows: ship a checklist the agent can copy and tick off
Feedback-loop pattern for quality-critical operations:
1. Make the change
2. Validate: <command>
3. On failure: read error, fix, re-validate
4. Proceed only when validation passes
When a script is unavailable, give the agent a manual checklist with the same checks.
Phase 5: Bundle resources
scripts/ — executable code for deterministic operations. Output enters context; the source does not. Handle errors with helpful messages; document inputs, outputs, exit codes; test before bundling.
references/ — markdown loaded on demand. Keep one level deep from SKILL.md (chained references read as head -100 previews and lose information). Files over 100 lines need a table of contents. Split by domain, not by size.
assets/ — templates, images, schemas used in output generation. Not loaded for reasoning.
Phase 6: Validate
python3 scripts/validate_skill.py <path-to-skill>
The validator is invocation-aware: it skips trigger-keyword warnings when disable-model-invocation: true is set, and warns if a user-invoked-only description still contains Use when ... triggers.
Fallback. Manual check:
- Frontmatter parses;
name and description valid
name matches directory; ≤ 64 chars; lowercase + hyphens; no reserved words- Description ≤ 1024 chars, third person, no XML tags
- Triggers present iff model-invoked
- Body ≤ 500 lines
- References one level deep
- Forward slashes only
Phase 7: Test and iterate
A skill is not done until tested with real prompts.
- Single hard task. Pick the worst case the skill must handle. Run it repeatedly. Fix what breaks. Faster signal than broad coverage.
- Triggering tests (model-invoked skills only). 10-20 queries: should-trigger obvious, should-trigger paraphrased, should-not-trigger. Target 80-90% correct activation. Under-trigger → add phrases. Over-trigger → narrow scope or add negative triggers.
- Functional tests. Run the same request 3-5 times. Steps in correct order; tool calls succeed; output format correct. Variance reveals ambiguity.
- Performance comparison. Same task with and without the skill. Messages exchanged, tool failures, total tokens. If no metric improves, simplify or delete.
- Iterate. Read the agent's reasoning, not just the output. Wasted steps, missed instructions, confusion → tighten the relevant section. Generalize from feedback rather than overfitting.
For automated runs, place evals in evals/evals.json:
{
"skill_name": "my-skill",
"evals": [
{"id": 1, "prompt": "...", "expected_output": "...", "assertions": ["Output includes X"]}
]
}
Progressive Disclosure
Skills load in three tiers:
- Metadata (~100 tokens):
name + description for every installed skill at startup
- Instructions (< 5000 tokens recommended): SKILL.md body, loaded on activation, retained for the rest of the turn
- Resources: bundled files loaded only when referenced
A model-invoked description fights at ~100 tokens. A user-invoked-only description fights for slash-menu legibility. The body should be comprehensive but lean.
Invocation model
Three modes, controlled by frontmatter:
| Mode | Set | Effect |
|---|
| Model + user | nothing (default) | Description in model context; appears in slash menu; both can invoke. |
| User-only | disable-model-invocation: true (Claude Code) / policy.allow_implicit_invocation: false (Codex) | Description not in model context; appears in slash menu; only user invokes. |
| Model-only | user-invocable: false (Claude Code) | Description in model context; hidden from slash menu; only the model invokes. |
Pair invocation control with the right neighboring fields:
- User-only skills (
/commit, /deploy, /send-slack-message) often want argument-hint for autocomplete UX, allowed-tools to skip permission prompts, and arguments for positional args.
- Model-only skills (background context like
legacy-system-conventions) want a strong description with triggers — that is the only thing the model will see at startup.
- Both-mode skills should keep the description tight enough to read in the slash menu while still containing triggers.
Platform targeting
The agentskills.io spec is intentionally minimal: required name and description; optional license, compatibility, metadata, and experimental allowed-tools. Every vendor ships extensions on top.
Decide once, up front: cross-platform or single-vendor?
| Choice | When | What to use |
|---|
| Cross-platform | Public distribution; team uses multiple platforms; portability is the goal. | Spec frontmatter only; no vendor-only fields; forward slashes; bundle deps; document target in compatibility if narrow. |
| Single-vendor | The skill exists for one platform and will not be used elsewhere. | Use vendor extensions where they help; declare the target in compatibility; ignore other platforms. |
Single-vendor is not a smell. A commit skill that lives only in ~/.claude/skills/ should use disable-model-invocation: true, argument-hint: "[scope]", allowed-tools: Bash(git:*), and context: fork if those make the skill correct on its target. Refusing those features to "stay portable" produces a worse Claude Code skill that nobody else runs anyway. The cross-platform default applies when portability is an actual goal — not as a moral rule.
Platform-specific extensions (full reference in references/frontmatter-fields.md):
- Claude Code:
disable-model-invocation, user-invocable, argument-hint, arguments, when_to_use, model, effort, context, agent, hooks, paths, shell. Slash-command invocation /skill-name. Live change detection on ~/.claude/skills/ and .claude/skills/.
- OpenAI Codex:
agents/openai.yaml for UI metadata and policy.allow_implicit_invocation. Invocation $skill-name. Scans .agents/skills/ from CWD upward, then ~/.agents/skills/.
- Cursor:
.cursor/skills/; spec-compliant frontmatter only.
- Gemini CLI: prefers
.agents/skills/ over .gemini/skills/ when both exist.
- VS Code / Copilot:
.github/skills/; spec-compliant frontmatter only.
Storage matrix:
| Platform | Project | User |
|---|
| Claude Code | .claude/skills/ | ~/.claude/skills/ |
| Cursor | .cursor/skills/ | ~/.cursor/skills/ |
| Gemini CLI | .gemini/skills/ | ~/.gemini/skills/ |
| OpenAI Codex | .agents/skills/ | ~/.agents/skills/ |
| VS Code / Copilot | .github/skills/ | VS Code profile |
| Cross-platform fallback | .agents/skills/ | n/a |
.agents/ is the emerging cross-platform convention. Codex uses it natively; Gemini reads it preferentially; Antigravity and OpenCode adopt it.
Precedence: project > personal > extension/plugin. (Codex shows colliding skills in the selector instead of merging.)
Distribution
- skills.sh (Vercel package manager):
npx skills add <owner>/<repo> or ... --skill "<name>" for a multi-skill repo. Publish to GitHub in standard layout.
.skill package (Claude.ai-specific): zip archive with .skill extension; upload via Settings → Features.- Claude Code Plugin marketplace:
/plugin marketplace add <owner>/<repo>.
Reviewing an existing skill
When the user asks to review or improve a skill, run all of these in addition to mechanical validation. Each step has a fix path, not just a diagnosis.
- Parse intent. Read the frontmatter for
disable-model-invocation, user-invocable, and (for Codex) agents/openai.yaml policy.allow_implicit_invocation. The intended invocation model determines what counts as a problem in the description and elsewhere.
- Description audit.
- User-invoked only? Flag any "Use when ..." trigger phrases as dead tokens — propose a terse user-facing label instead.
- Model-invoked? Flag missing triggers, vagueness, first/second person, marketing fluff that crowds out actionable triggers, and over-broad scope without negative triggers.
- Platform audit. Confirm whether the skill is single-vendor or cross-platform.
- Single-vendor skill missing vendor extensions that would help (e.g., a Claude-only
commit skill without disable-model-invocation or argument-hint)? Propose adding them.
- Cross-platform skill using vendor-only fields? Propose removing them or splitting the skill.
- Density audit. Scan the body and references for the patterns in references/writing-patterns.md § Density: hard wraps that imply meaning, blockquote-wrapped examples, ladders of nested indented bullets, "why this works" paragraphs after every example, redundant restatements of a rule already stated by a code block, single-sentence
Tip:/Note: wrappers, decorative external-spec citations, intra-document anchor links (use plain "see § X below" instead), bare citation URLs that the agent will never fetch. Flag and propose tighter alternatives. Lead by example: do not write the review report itself in the style being criticized.
- Structural audit. Run
scripts/validate_skill.py for body length, reference depth, forward slashes, frontmatter validity.
The order matters. Step 1 reframes Step 2; without it, you will give bad advice about the description.
Anti-patterns
Critical (skill never activates correctly):
- Workflow summary in
description. The model may skip the body if the description tells the whole story. Description triggers; body teaches. Bad: "Analyzes git diff, identifies the change type, generates a commit message". Good: "Use when generating commit messages. Handles conventional commits, scope detection, breaking changes."
- Vague description. "Helps with documents" matches nothing.
- Monolithic skill. "Handles all dev workflows" loads slowly and triggers imprecisely. Split.
High impact (degrade performance):
- README-style content. Skills teach how, not what. Procedures with steps, not narrated context.
- Inlining what belongs in
assets/. Templates with placeholders, schemas, and other output-generation patterns go in assets/<name>.md, referenced from SKILL.md. Inlining a per-type catalog loads every variant on every invocation and obscures the skill's structural shape. Inline only when the block is small and used unconditionally.
- External fetch dependencies. Network downloads at activation time are fragile. Bundle.
- Command lists without verification. Add explicit checks and failure handling.
- First/second person in description. "I can help" / "You can use" reads wrong from a system prompt.
- Cross-platform dogma on a single-vendor skill. Refusing
disable-model-invocation, allowed-tools, or argument-hint on a skill that lives only in ~/.claude/skills/ is missed value. Portability is a goal, not a moral rule.
- "Use when ..." triggers in a user-invoked-only description. When
disable-model-invocation: true (Claude Code) or allow_implicit_invocation: false (Codex), the model never reads the description. The triggers consume the user-facing label budget for nothing.
Medium impact (token bloat, lower quality):
- User-guide aesthetics. Hard wraps that imply meaningful line breaks where there are none, blockquotes around examples (use code fences), three-deep ladders of indented bullets where one tight sentence suffices, "why this works" paragraphs after every example, restating a rule in prose immediately after a code block already showing it,
Tip:/Note:/Important: wrappers around single sentences. The reader is a model; visual decoration costs tokens with no benefit. See references/writing-patterns.md § Density.
- Decorative links to external specs and intra-document anchors.
[agentskills.io spec](https://agentskills.io/specification), [Platform targeting](#platform-targeting), bare citation URLs at the end of a sentence — these are documentation aesthetics. The agent does not click during normal execution; the whole SKILL.md is already in context. Anchor links break on heading rename and add nothing the model could not get from "see § Platform targeting below". External URLs are noise unless the agent is genuinely expected to WebFetch them as part of the procedure (rare). Functional links to bundled files — [references/foo.md](references/foo.md) — are different: the path is the operand the agent passes to Read/bash, the link text gives loading context. Keep those.
- Verbose explanations of well-known concepts.
- Multiple equivalent options without a default.
- Windows backslash paths.
- Deep reference chains (SKILL.md → a.md → b.md).
- Time-sensitive notes ("After August 2025 ..."). Move to an "Old patterns" section.
- Inconsistent terminology.
- Heavy
MUSTs without reasoning.
