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:

1. 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.
2. What single capability does this skill provide? One focused domain. If the answer requires "and", split.
3. Target platform(s). Claude Code only? Codex only? Multiple? Determines which frontmatter fields are available — see § Platform targeting below.
4. 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.
5. What does the agent lack? Add only that.
6. 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 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:

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.

1. Single hard task. Pick the worst case the skill must handle. Run it repeatedly. Fix what breaks. Faster signal than broad coverage.
2. 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.
3. Functional tests. Run the same request 3-5 times. Steps in correct order; tool calls succeed; output format correct. Variance reveals ambiguity.
4. Performance comparison. Same task with and without the skill. Messages exchanged, tool failures, total tokens. If no metric improves, simplify or delete.
5. 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:

1. Metadata (~100 tokens): name + description for every installed skill at startup
2. Instructions (< 5000 tokens recommended): SKILL.md body, loaded on activation, retained for the rest of the turn
3. 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:

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?

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:

.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.

1. 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.
2. 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.

1. 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.

1. 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.
2. 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.