Make Skill

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](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](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  --path 

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](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](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: 
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 

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 ( personal > extension/plugin. (Codex shows colliding skills in the selector instead of merging.)

Distribution

• skills.sh (Vercel package manager): npx skills add / or ... --skill "" 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 /.

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](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/.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 [refere

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sergeyklay
• Source: sergeyklay/.agents
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.