| name | skillception |
| description | Use when authoring, refactoring, auditing, or learning to build any agent skill — for Claude Code, the Claude API, claude.ai, the Claude Agent SDK, Hermes Agent (Nous Research), OpenClaw, Codex, Cursor, Cline, or Antigravity. Use when the user says any of "make a skill", "write a skill", "skill for [tool]", "skill best practices", "fix this skill", "review my SKILL.md", "skill description not triggering", "skill discovery", "skill frontmatter", "progressive disclosure", "agent skill format", "claude skill", "SKILL.md template", "Hermes skill", "skillception", "meta skill". Use even when the user does not say the word "skill" but is clearly authoring a SKILL.md, packaging an onboarding guide for an agent, or trying to make an LLM consistently follow a multi-step procedure. Use proactively whenever a workflow has been repeated more than once. This skill is the canonical, self-contained authority on skill authoring; load it first, follow it exactly. |
| license | MIT |
| compatibility | Format-agnostic. Anthropic Agent Skills (canonical), agentskills.io open standard, Claude Code extensions, Hermes Agent, OpenClaw. Required reading before authoring any skill. |
| metadata | {"version":"1.0.0","author":"zaydiscold","source-of-truth-citations":["https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf","https://agentskills.io/skill-creation/best-practices","https://agentskills.io/specification","https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview","https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices","https://code.claude.com/docs/en/skills"],"hermes-mirror":{"name":"skillception","description":"Master reference for authoring agent skills across platforms. Use whenever creating, editing, auditing, or learning to write a SKILL.md file.","platforms":["macos","linux","windows"],"tags":["Meta","Authoring","Documentation","Skills","BestPractices"]}} |
Skillception
Mandatory authorities — this skill MUST adhere to and defer to these in any conflict:
- Anthropic, The Complete Guide to Building Skills for Claude (33-page PDF, January 2026). https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf
- agentskills.io / Best practices for skill creators (open standard, evolving). https://agentskills.io/skill-creation/best-practices
- agentskills.io / Specification — the canonical wire format. https://agentskills.io/specification
Anything written below that contradicts those three is wrong. Re-read those three first if you are unsure. Violating the letter of these rules is violating the spirit of these rules.
§0. The 60-Second TL;DR
A skill is a folder containing a SKILL.md plus optional scripts/, references/, and assets/. The folder is loaded progressively by an agent: only name + description are pre-loaded (~100 tokens); the body is read on activation (≤5,000 tokens recommended); supporting files are read or executed only when the body tells the agent to.
A skill is an employee, not a file. CLAUDE.md is a sticky note; a skill is the recipe book, the pan, and the pantry inventory together.
The five non-negotiable invariants:
name is ≤64 characters, lowercase a–z + digits + hyphens, no leading/trailing/consecutive hyphens, must match the parent folder name, must not contain XML tags, must not be claude or anthropic.description is ≤1,024 characters, written in third person, and contains both what the skill does and when to use it with concrete trigger keywords. The description IS the trigger; the body is not.- SKILL.md body ≤ 500 lines (this file is a deliberate exception — see header comment). Move detail to
references/ files referenced one level deep from SKILL.md.
- Every reference file >100 lines has a table of contents at the top.
- The body assumes the agent is already smart. Add only what the agent doesn't know on its own. Cut everything else.
If you remember nothing else, remember those five. The rest of this file is why they're true and how to apply them well.
§1. What a Skill Is (and What It Is Not)
1.1 Definition
A skill is a filesystem-based, progressively-loaded module of agent expertise. It packages instructions, optional scripts, optional reference material, and optional assets into a single folder that an agent can discover, evaluate for relevance, and selectively load on demand.
1.2 The two anchoring metaphors
"CLAUDE.md is a sticky note. Skills are the recipe book, the pan, and the pantry inventory." — Thariq Shihipar, Anthropic, Lessons from Building Claude Code
"A skill is an employee, not a file." — Twitter agent-engineering folklore, captures the essential difference between skills and prompts.
Both metaphors point at the same shape: a skill is a bounded competency with structure, references, and tools an agent can reach into — not a paragraph of instructions. The folder shape is what enables progressive disclosure; trying to do the same job in a single inline prompt is what burns context.
1.3 Skills vs. CLAUDE.md vs. MCP — the comparison that matters
| Aspect | CLAUDE.md (memory) | Skill | MCP server |
|---|
| Always loaded? | Yes, every turn | Only metadata (~100 tokens) | Schema dump on connection |
| Body load timing | Always | On description match | Always (full schema) |
| Token cost (idle) | Full file every turn | ~100 tokens / skill | ~10K–50K tokens / server |
| Update without restart | No (re-read on next turn) | Yes (Claude Code watches dirs) | No (reconnect) |
| Best for | Facts that apply to every turn | Procedures repeated >1× / day | External tools Claude can't invoke directly |
| Anti-pattern | Procedures stuffed into CLAUDE.md | Single-use one-off scripts | Schema bloat consuming 88% of a 200K window |
Token math worth memorizing. The GitHub MCP server typically advertises ~50,000 tokens of schema on connection — that is 25% of a 200K context window before the agent has done anything. The same coverage as ten skills costs ~1,000 tokens (10 × ~100), or ~0.5%. Progressive disclosure is two orders of magnitude cheaper than schema dumping. This is the killer argument for skills.
1.4 What a skill is NOT
- NOT a complete application or workflow. One skill, one coherent unit of work. A skill that queries a database and formats results and administers the database is doing too much.
- NOT a custom persona or role-play. Skills add capability, not personality.
- NOT a place to override Claude's safety guidelines. Trusted-source policies apply.
- NOT a dump of generic best practices. "Handle errors appropriately. Follow good practices." is not a skill — it's noise. A skill is non-obvious, project-or-domain-specific knowledge the agent would not have on its own.
- NOT a markdown file. The folder is the unit. Files inside the folder are progressively loaded resources, not the skill itself.
1.5 When to author a skill
Author a skill when all of the following are true:
- The work has been repeated more than once a day OR you have lost time to the same gap more than twice.
- The expertise is non-obvious to a fresh agent — it requires project-specific facts, domain quirks, or learned conventions.
- The expertise is reusable across projects or sessions (otherwise it goes in CLAUDE.md or
.claude/rules/).
- You can describe the trigger conditions in <1024 characters of plain language.
If those four are not all true, stop. Use a slash command, a CLAUDE.md note, or a one-off prompt instead.
§2. The Three-Tier Progressive Disclosure Architecture
This is the architecture every skill inherits whether the author thinks about it or not. Authoring well means designing for it.
┌────────────────────────────────────────────────────────────────────┐
│ Tier 1 — METADATA (always loaded, ~100 tokens / skill) │
│ Source: YAML frontmatter (name + description) │
│ Purpose: Discovery. Agent decides whether to load Tier 2. │
│ Failure mode: vague description → skill never triggers. │
└────────────────────────────────────────────────────────────────────┘
│ description matches user intent
▼
┌────────────────────────────────────────────────────────────────────┐
│ Tier 2 — INSTRUCTIONS (loaded on activation, ≤5,000 tokens) │
│ Source: SKILL.md body (everything after frontmatter) │
│ Purpose: Procedural knowledge — workflows, gotchas, patterns. │
│ Failure mode: 500+ lines of prose → context burn + worse output. │
└────────────────────────────────────────────────────────────────────┘
│ body references a file or runs a script
▼
┌────────────────────────────────────────────────────────────────────┐
│ Tier 3 — RESOURCES (loaded on demand, effectively unlimited) │
│ Source: references/*.md, scripts/*.{py,sh,js}, assets/* │
│ Purpose: API specs, large schemas, executable utilities, data. │
│ Failure mode: nested references → partial reads, missed content. │
└────────────────────────────────────────────────────────────────────┘
Three architectural rules that follow from this picture:
- The description is the gate. If the description is wrong, nothing in Tier 2 or Tier 3 ever runs. Description quality dominates skill quality.
- Tier 2 is for what every activation needs. If a section is needed in 30% of activations, move it to Tier 3 and tell Tier 2 when to read it.
- Tier 3 is free until accessed. Bundle as much reference material as you want. The cost is zero until the agent reaches for it.
§3. Frontmatter — The Two Required Fields and Everything Else
3.1 Required fields (the only two)
---
name: my-skill-name
description: One sentence describing what the skill does, then a sentence describing exactly when to use it, including specific trigger phrases.
---
That is a complete, valid frontmatter. Everything else is optional.
3.2 The name field — hard rules
| Rule | Constraint |
|---|
| Length | 1 ≤ length ≤ 64 characters |
| Allowed characters | Lowercase a–z, digits 0–9, hyphen - |
| Forbidden | Uppercase, spaces, underscores, dots, slashes, XML tags |
| Hyphen rules | No leading hyphen, no trailing hyphen, no consecutive hyphens (my--skill invalid) |
| Reserved words | anthropic, claude (will be rejected) |
| Must match | The name field MUST match the folder name exactly |
| Stylistic preference | Gerund form (processing-pdfs, auditing-skills) over noun form (pdf-processing, skill-audit) — gerunds describe the activity |
Valid: processing-pdfs, analyzing-spreadsheets, running-migrations, skillception, pdf-form-fill, commit, migrate-react-to-vue.
Invalid: PDF-Processing (uppercase), pdf--processor (consecutive hyphens), -pdf (leading hyphen), pdf_processing (underscore), claude-helper (reserved word claude), pdf processing (space), skill.v2 (dot).
3.3 The description field — the single most important decision in your skill
This is the field Claude reads to decide whether to load your skill out of potentially 100+ available skills. More authorial care belongs here than in any other part of the skill.
3.3.1 Hard rules
| Rule | Constraint |
|---|
| Length | 1 ≤ length ≤ 1,024 characters |
| Voice | Third person ("Generates commit messages", not "I generate" or "You can use this to") |
| Content | Both what the skill does AND when to use it |
| Forbidden | XML tags, vague language ("helps with X") |
| Combined cap (Claude Code) | Description + when_to_use ≤ 1,536 characters in the listing |
3.3.2 The single biggest description anti-pattern
❌ Putting the activation criteria in a ## When to Use This Skill section inside the body.
The body is loaded after the description triggers a match. If the trigger isn't in the description, the body never gets read. Putting "when to use" in the body is dead weight.
✅ Put activation criteria in the description. Put rationale in the body.
3.3.3 The "use when" framing template
Every great description follows roughly this shape:
[VERB] [OBJECT] [optional: outcome/constraint]. Use when [trigger phrase 1], [trigger phrase 2], [trigger phrase 3], or even when [non-obvious phrasing the user might not say].
Examples ranked weak → strong:
description: Helps with PDFs.
description: This skill processes PDF files using pdfplumber and pypdf libraries.
description: Extracts text from PDF files. Use when working with PDFs.
description: Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
description: Analyzes a design image and creates a full design system project with separated artboards. Use whenever the user provides a reference image, screenshot, or mockup and wants to extract a design system, build a component library, or reverse-engineer visual patterns — even if they don't explicitly say "design system".
The pattern "even if they don't explicitly say X" is one of the highest-leverage description techniques. It catches the cases where the user describes the symptom but not the category.
3.3.4 Description anti-patterns (each with the fix)
| Anti-pattern | Example | Fix |
|---|
| First-person voice | "I help you with PDFs" | Third person: "Processes PDFs" |
| Workflow summary | "Step 1: load file. Step 2: extract..." | Move steps to body; describe what + when in description |
| Vague verb | "Handles documents" | Concrete verb: "Extracts text and tables from" |
| Missing "when" | "Generates commit messages" | Add: "...Use when the user asks for help writing commit messages or reviewing staged changes" |
| Keyword stuffing | "PDF, pdf, document, file, text, ai, machine learning, claude..." | Pick 3–5 high-signal terms; cut the noise |
Redundant with name | name: pdf-extractor / desc: "Extracts PDFs" | Add the when: triggers, contexts, file types |
| Past-tense language | "Helped extract data..." | Present tense: "Extracts data..." |
| XML / Markdown tags | "Use <parser> to extract" | Plain text only — XML in description is rejected |
3.3.5 Description length budget
Aim for 150–400 characters in most cases. Use the full 1,024 only when the trigger surface is genuinely large (multiple file types, many user phrasings, ambiguity worth disambiguating). For Claude Code, the listing truncates description + when_to_use at 1,536 characters combined — front-load the most important trigger keywords.
3.4 Optional frontmatter fields — full catalog
Different platforms add different optional fields. The list below covers all five major surfaces: agentskills.io spec, Anthropic API, claude.ai, Claude Code, and Hermes.
3.4.1 agentskills.io open-standard fields
| Field | Type | Constraints |
|---|
license | string | Free-form. Recommend short ("MIT", "Apache-2.0") or filename ("LICENSE.txt has terms") |
compatibility | string ≤500 chars | Environment requirements ("Requires Python 3.14+ and uv") |
metadata | map<string, any> | Arbitrary; recommend unique key prefixes to avoid client collisions |
allowed-tools | space-separated string | Experimental; varies by client. Format Bash(git:*) Read |
3.4.2 Claude Code-specific fields (extensions to the open standard)
| Field | Purpose | Default |
|---|
when_to_use | Extra trigger context appended to description in the listing | empty |
argument-hint | Autocomplete hint, e.g. [issue-number] | empty |
arguments | Named positional arguments for $name substitution | empty |
disable-model-invocation | true ⇒ only the user can invoke (/skill) | false |
user-invocable | false ⇒ only Claude can invoke (no / menu) | true |
allowed-tools | Tools Claude can use without approval while skill active | empty |
model | Override session model when this skill is active | inherit |
effort | low / medium / high / xhigh / max | inherit |
context | fork ⇒ run in a forked subagent context | none |
agent | Subagent type when context: fork (Explore, Plan, general-purpose) | general-purpose |
hooks | Skill-scoped hooks (PreToolUse, PostToolUse, Stop) | empty |
paths | Glob patterns; skill auto-loads only when working with matching files | unbounded |
shell | bash (default) or powershell for !`cmd` blocks | bash |
3.4.3 Claude Code dynamic context — !`shell-command`
A SKILL.md may inject the live output of a shell command into the prompt before Claude reads the body. Two forms:
## Inline form
Current branch: !`git rev-parse --abbrev-ref HEAD`
## Block form (multi-line)
```!
node --version
npm --version
git status --short
The command runs at activation; the placeholder is replaced with the output; Claude only sees the rendered text. Combine with `context: fork` and `agent: Explore` for a powerful pattern: *fork a subagent with a tightly-scoped task and live data already inlined*.
#### 3.4.4 Claude Code string substitutions
Available inside SKILL.md when invoked with arguments:
| Variable | Expands to |
|---|---|
| `$ARGUMENTS` | All arguments as a single string |
| `$ARGUMENTS[N]` / `$N` | Nth argument by 0-based index |
| `$name` | Named argument from `arguments:` list (positional mapping) |
| `${CLAUDE_SESSION_ID}` | Current session ID |
| `${CLAUDE_EFFORT}` | Active effort level |
| `${CLAUDE_SKILL_DIR}` | Absolute path to the skill folder (use this for bundled scripts) |
Always reference bundled scripts as `python3 ${CLAUDE_SKILL_DIR}/scripts/foo.py` — never as a relative path that depends on the user's `cwd`.
#### 3.4.5 Hermes Agent (Nous Research) frontmatter
Hermes uses a richer frontmatter for conditional activation and platform gating. If you want a single skill to work in *both* Anthropic surfaces and Hermes, add a `metadata.hermes:` block (see §10.2 for the dual-format pattern):
| Field | Purpose |
|---|---|
| `platforms` | Array; skill auto-hides on incompatible OSes (`[macos]`, `[macos, linux]`) |
| `metadata.hermes.tags` | Categorical tags |
| `metadata.hermes.requires_toolsets` | Skill hidden when ANY listed toolset NOT available |
| `metadata.hermes.requires_tools` | Skill hidden when ANY listed tool NOT available |
| `metadata.hermes.fallback_for_toolsets` | Skill hidden when ANY listed toolset IS available (fallback semantics) |
| `metadata.hermes.fallback_for_tools` | Skill hidden when ANY listed tool IS available |
| `required_environment_variables` | Array of `{ name, prompt, help, required_for }` |
| `required_credential_files` | Array of `{ path, description }` (mounted read-only) |
| Template tokens | `${HERMES_SKILL_DIR}`, `${HERMES_SESSION_ID}` |
Hermes also ships **inline shell snippets** (`` !`cmd` ``) but disabled by default — opt in via `skills.inline_shell: true` in `~/.hermes/config.yaml`.
#### 3.4.6 OpenClaw fields
OpenClaw is closer to the open standard but adds:
```yaml
metadata:
openclaw:
os: ["darwin", "linux"] # OS gating
requires:
bins: ["jq", "git"] # Required binaries on PATH
config: ["api.token"] # Required config keys
OpenClaw also defines discovery precedence layers (highest first): <workspace>/skills/ > <workspace>/.agents/skills/ > ~/.agents/skills/ > ~/.openclaw/skills/ > bundled > custom dirs.
3.5 Frontmatter checklist (apply before shipping)
§4. Naming — Patterns That Make Skills Discoverable
4.1 Gerund-form preference
Anthropic recommends gerund (verb + -ing) form because it describes the activity, which matches how users phrase requests:
| Gerund (preferred) | Noun-form (acceptable) |
|---|
processing-pdfs | pdf-processing |
analyzing-spreadsheets | spreadsheet-analysis |
migrating-databases | database-migration |
auditing-skills | skill-audit |
writing-documentation | doc-writing |
Action-oriented imperative is also acceptable for skills with a single dominant action: commit, deploy, migrate-component.
4.2 Avoid — naming anti-patterns
- Vague:
helper, utils, tools, wizard, assistant
- Overly generic:
documents, data, files
- Reserved words: anything containing
claude or anthropic
- Inconsistent within a collection: mixing gerunds and nouns randomly
- Including the agent name:
cursor-skill, codex-helper (the host already knows what tool it is)
- Versioning in the name:
pdf-extractor-v2 (use metadata.version instead)
4.3 Name as folder name
The folder name must equal the name field. If name: skillception, the folder is skillception/. Loaders enforce this and reject mismatches.
§5. Writing the Body — Everything After the Frontmatter
5.1 The 500-line rule
SKILL.md body should be ≤500 lines. If you exceed it, you have one of these problems:
- Multiple skills in one — split into separate skills.
- Reference content masquerading as procedure — move to
references/*.md and link.
- Over-explanation — assume Claude is smart and cut.
- Deliberate study document — like this file. Document the trade-off in a header comment.
5.2 Recommended body structure (the Hermes pattern, refined)
The Nous Research / Hermes documentation crystallized the most-effective body shape. Use it for any procedural skill:
# Skill Title
Brief one-paragraph intro — what does this enable?
## When to use
(Optional. Mostly redundant with description but useful for human readers
auditing the skill. Don't rely on this section to trigger activation.)
## Quick reference
A table or short list of common commands / API calls / outputs.
## Procedure
Numbered, imperative steps. Reasoning embedded ("...because X").
## Gotchas
The highest-signal section. Concrete corrections to non-obvious failures.
## Verification
How does the agent confirm success? What is the validation loop?
## References
Links to bundled files (one level deep), with WHEN to read each one.
5.3 Voice and style
5.3.1 Imperative form
Models pattern-match to imperative instructions better than to declarative or conditional ones. Anthropic confirmed in their internal source code that production prompts use imperative voice deliberately.
# ✅ GOOD — imperative
Extract the color palette from the image.
# ❌ AVOID — declarative
You should extract the color palette from the image.
# ❌ AVOID — conditional
If the user wants colors, then you can extract the palette.
5.3.2 Reasoning over rigidity
When you find yourself writing ALWAYS or NEVER in all caps, reframe to explain why. A model that understands the reason makes better decisions in unanticipated situations.
# ❌ Rigid — fails when the situation changes slightly
NEVER navigate to the editor during the build.
# ✅ Reasoned — model can generalize
Stay on the hub during the build. The user watches thumbnails appear
progressively — navigating to the editor would break the visual feedback
loop.
The exception: fragile, low-freedom operations (database migrations, irreversible deploys) where you want NO improvisation. For those, prescribe the exact command and forbid modification (see §6 — Calibrating Control).
5.3.3 Consistent terminology
Pick one term for each concept and use it throughout. Inconsistency confuses both Claude and human reviewers.
# ❌ Inconsistent
"API endpoint" → "URL" → "API route" → "path"
"field" → "box" → "element" → "control"
"extract" → "pull" → "get" → "retrieve"
# ✅ Consistent
Always "API endpoint", "field", "extract".
5.3.4 Repeating quality expectations
When quality is the goal (design, writing, code review), repeat the quality bar at multiple points in the skill. Anthropic's internal canvas-design skill deliberately uses language like "meticulously crafted", "painstaking attention", "master-level execution" repeatedly. Each repetition reinforces the standard.
This is not redundancy — it is calibration. The model treats quality language as a probabilistic signal; one mention is weak, three mentions across sections is strong.
5.4 What the body should and should not contain
5.4.1 Add what the agent lacks
The body's only job is to add knowledge the agent doesn't already have. Test every paragraph with three questions:
- Does the agent really need this explanation?
- Can I assume the agent knows this?
- Does this paragraph justify its token cost?
If the answer to (1) is "no" or to (2) is "yes," cut it.
# ❌ TOO VERBOSE (~150 tokens)
PDF (Portable Document Format) files are a common file format that
contains text, images, and other content. To extract text from a PDF,
you'll need to use a library. There are many libraries available for
PDF processing, but pdfplumber is recommended because it's easy to use
and handles most cases well. First, you'll need to install it...
# ✅ CONCISE (~50 tokens)
Use pdfplumber for text extraction:
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
The concise version assumes Claude knows what PDFs are and how Python imports work. It does — those are training-set basics.
5.4.2 No time-sensitive information
Anything dated will go stale. Push deprecated content into a collapsible "Old patterns" section, not the main flow:
# ❌ Time-sensitive
If you're doing this before August 2026, use the old API.
# ✅ Versioned
## Current method
Use the v2 API: `api.example.com/v2/messages`
## Old patterns
<details>
<summary>Legacy v1 API (deprecated 2026-08)</summary>
The v1 API used `api.example.com/v1/messages`. No longer supported.
</details>
5.5 Concrete examples beat abstractions
For any non-trivial pattern, include at least one fully-worked example. Models pattern-match on examples better than on abstract descriptions.
## Commit message format
Generate commit messages following these examples:
**Example 1**
Input: Added user authentication with JWT tokens
Output:
feat(auth): implement JWT-based authentication
Add login endpoint and token validation middleware
**Example 2**
Input: Fixed bug where dates displayed incorrectly in reports
Output:
fix(reports): correct date formatting in timezone conversion
Use UTC timestamps consistently across report generation
Three examples is the sweet spot for most patterns: enough to disambiguate, not so many that the body bloats.
§6. Calibrating Control — Specificity vs. Freedom
This is the most under-appreciated part of skill authoring. The right level of prescriptiveness depends on the fragility of the task.
6.1 The three control modes
| Mode | When to use | Example |
|---|
| High freedom (text instructions) | Multiple valid approaches, decisions depend on context | Code review skills, brainstorming skills, design analysis |
| Medium freedom (template + parameters) | Preferred pattern exists, some variation acceptable | Report generation, scaffolding |
| Low freedom (exact script, no params) | Operations are fragile, consistency is critical, sequence matters | Database migrations, deploys, releases |
6.2 The bridge metaphor (Anthropic, paraphrased)
Think of the agent as a robot exploring a path:
- Narrow bridge with cliffs on both sides: there's only one safe way forward. Provide specific guardrails, exact commands, no improvisation. (Low freedom.)
- Open field with no hazards: many paths lead to success. Give general direction and trust the agent to find the route. (High freedom.)
Most skills are mixed. Calibrate each section independently.
6.3 Example: the same skill, three control levels
## Code review process (HIGH freedom — exploratory)
1. Analyze the code structure and organization.
2. Check for potential bugs or edge cases.
3. Suggest improvements for readability and maintainability.
4. Verify adherence to project conventions.
## Generate report (MEDIUM freedom — preferred pattern)
Use this template; adapt sections as needed:
def generate_report(data, format="markdown", include_charts=True):
# Process, then output in specified format, optionally with charts.
## Database migration (LOW freedom — fragile)
Run exactly this sequence:
python scripts/migrate.py --verify --backup
Do not modify the command or add additional flags.
6.4 Rule of thumb
If the task has side effects you cannot reverse (data loss, prod deploy, sending email, executing trades), default to low freedom with explicit forbidden modifications. If the task is read-only or in a sandbox, default to high freedom unless quality has been visibly suffering.
§7. Defaults, Not Menus
When multiple tools or libraries could solve a problem, pick one as the default and mention alternatives only as escape hatches.
# ❌ Too many choices — produces decision paralysis
You can use pypdf, pdfplumber, PyMuPDF, or pdf2image, depending on...
# ✅ Clear default + escape hatch
Use pdfplumber for text extraction:
import pdfplumber
For scanned PDFs requiring OCR, use pdf2image with pytesseract instead.
This rule is mechanical: every time you write "you could use A, B, or C", stop. Pick one. Demote the rest to a one-line "if X, instead use Y" addendum.
§8. Procedures Over Declarations
Teach the agent how to approach a class of problems, not what to produce for one specific instance. The first generalizes; the second is dead weight.
# ❌ Specific answer — useful only for THIS exact task
Join the `orders` table to `customers` on `customer_id`, filter where
`region = 'EMEA'`, and sum the `amount` column.
# ✅ Reusable method — works for any analytical query
1. Read the schema from `references/schema.yaml` to find relevant tables.
2. Join tables using the `_id` foreign key convention.
3. Apply any filters from the user's request as WHERE clauses.
4. Aggregate numeric columns as needed and format as a markdown table.
The exception: output format templates and "never do X" constraints are legitimately specific. The principle is that the approach should generalize even when individual constraints are specific.
§9. The Patterns — Reusable Body Structures
Use these patterns when they fit. Not every skill needs all of them.
9.1 Gotchas section (the highest-leverage pattern)
The single highest-signal content in any skill is its gotchas list — concrete corrections to mistakes the agent will make without being told. These are not general advice ("handle errors carefully"); they are environment-specific facts that defy reasonable assumptions.
## Gotchas
- The `users` table uses soft deletes. Queries must include
`WHERE deleted_at IS NULL` or results will include deactivated accounts.
- The user ID is `user_id` in the database, `uid` in the auth service,
and `accountId` in the billing API. All three refer to the same value.
- The `/health` endpoint returns 200 as long as the web server is running,
even if the database connection is down. Use `/ready` for full health.
- React 19's `useEffect` runs twice in StrictMode dev. Tests using
effect-spies must account for this or use `useEffectEvent`.
Iterating on gotchas is the single best way to improve a skill over time. Every time you correct an agent's mistake, ask: would the next agent make the same mistake? If yes, it's a gotcha.
Keep gotchas in SKILL.md itself, not in a reference file. Reference files are loaded when the body says to load them; gotchas need to be visible before the agent encounters the situation.
9.2 Templates for output format
When you need a specific format, provide a literal template. Models pattern-match against concrete structures more reliably than they follow prose descriptions.
## Report structure
ALWAYS use this exact template:
# [Analysis Title]
## Executive summary
[One-paragraph overview of key findings]
## Key findings
- Finding 1 with supporting data
- Finding 2 with supporting data
## Recommendations
1. Specific actionable recommendation
2. Specific actionable recommendation
For flexible output, provide the template as "a sensible default, but use your best judgment based on the analysis."
9.3 Checklists for multi-step workflows
For complex tasks with dependencies or validation gates, give the agent a checklist to track progress.
## PDF form filling workflow
Copy this checklist and check off items as you complete them:
Task Progress:
- [ ] Step 1: Analyze the form (run analyze_form.py)
- [ ] Step 2: Create field mapping (edit fields.json)
- [ ] Step 3: Validate mapping (run validate_fields.py)
- [ ] Step 4: Fill the form (run fill_form.py)
- [ ] Step 5: Verify output (run verify_output.py)
9.4 Validation loops
Do work → run validator → fix errors → repeat until validation passes. This pattern enormously improves output quality on any task that has a notion of "correct."
## Editing workflow
1. Make your edits.
2. Run validation: `python scripts/validate.py output/`
3. If validation fails:
- Review the error message.
- Fix the issues.
- Run validation again.
4. Only proceed when validation passes.
The "validator" doesn't have to be a script. A reference checklist, a reference document, or a self-check ("re-read your output and verify each constraint") can all serve.
9.5 Plan-validate-execute
For batch operations, destructive operations, or complex validations: have the agent first produce an intermediate plan in a structured format, validate the plan against a source of truth, and only then execute.
## PDF batch fill
1. Extract form fields: `python scripts/analyze_form.py input.pdf` → `form_fields.json`
2. Create `field_values.json` mapping each field name to its intended value.
3. Validate: `python scripts/validate_fields.py form_fields.json field_values.json`
4. If validation fails, revise `field_values.json` and re-validate.
5. Fill the form: `python scripts/fill_form.py input.pdf field_values.json output.pdf`
The validation script should produce specific, actionable errors:
"Field 'signature_date' not found. Available fields: customer_name, order_total, signature_date_signed."
Vague errors ("validation failed") leave the agent guessing.
9.6 Conditional workflow
When a skill has multiple branches, route the agent explicitly:
## Document modification workflow
1. Determine the modification type:
- **Creating new content?** → Follow "Creation workflow" below.
- **Editing existing content?** → Follow "Editing workflow" below.
2. Creation workflow:
- Use docx-js library.
- Build document from scratch.
3. Editing workflow:
- Unpack existing document.
- Modify XML directly.
- Validate after each change.
If a branch becomes large, push it into a separate file (Tier 3) and have the body say when to read it.
9.7 Bundling reusable scripts
If you find yourself describing the same parsing logic, validation logic, or chart-rendering logic in multiple skills (or watching agents reinvent it on every run), bundle it as a script and have the skill execute it. Scripts:
- Save tokens (script code never enters context)
- Save time (no code generation per run)
- Are more reliable than re-generated code
- Ensure consistency across uses
Reference them with python ${CLAUDE_SKILL_DIR}/scripts/X.py. Make execution intent explicit:
- "Run `analyze_form.py` to extract fields" — execute
- "See `analyze_form.py` for the field-extraction algorithm" — read as reference
9.8 Visual analysis
When inputs can be rendered as images (forms, charts, screenshots), have the agent convert and analyze visually. This unlocks the model's vision capabilities for layout-heavy tasks.
§10. Cross-Platform Compatibility
Authoring a skill that works on Anthropic surfaces and Hermes and OpenClaw is possible if you respect the lowest common denominator and use platform-specific extensions only as additions.
10.1 The lowest-common-denominator rule
A maximally-portable skill uses only:
name (matches folder, lowercase, hyphens, ≤64)description (≤1,024, third person, what + when)- A markdown body following §5
That skill loads on Claude Code, claude.ai, the Anthropic API, OpenClaw, and most third-party clients without modification. Anything beyond those two fields is a platform-specific opt-in.
10.2 The dual-format pattern (Anthropic + Hermes in one file)
For skills that must work on both Anthropic surfaces and Hermes, use a single frontmatter with a nested Hermes block:
---
name: my-skill
description: Standard cross-platform description with what and when. Use when [triggers].
license: MIT
metadata:
version: "1.0.0"
hermes:
platforms: [macos, linux]
tags: [Category, Subcategory]
requires_toolsets: [web]
config:
- key: my.setting
default: "sensible-default"
prompt: "Display prompt"
required_environment_variables:
- name: MY_API_KEY
prompt: "Enter your API key"
help: "Get one at https://example.com"
required_for: "API access"
---
Anthropic clients ignore unknown frontmatter fields. Hermes reads its metadata.hermes: and the top-level Hermes-specific fields (required_environment_variables, required_credential_files). The result: one canonical file, two surfaces.
10.3 Path discipline (Unix-style only)
Use forward slashes in all paths, even when authoring on Windows:
# ✅ GOOD
scripts/helper.py
references/guide.md
# ❌ BREAKS on Unix
scripts\helper.py
references\guide.md
Backslashes are valid Windows separators but Unix interprets them as escape characters. Forward slashes work everywhere.
10.4 Per-surface skill locations (cheat-sheet)
| Surface | Personal scope | Project scope |
|---|
| Claude Code | ~/.claude/skills/<name>/SKILL.md | .claude/skills/<name>/SKILL.md |
| claude.ai | Settings → Features → upload zip | n/a |
| Claude API | POST /v1/skills (workspace-wide) | n/a |
| Hermes | skills/category/<name>/ | optional-skills/category/<name>/ |
| OpenClaw | ~/.openclaw/workspace/skills/<name>/ | <workspace>/skills/<name>/ |
| Codex / Cursor / Antigravity | ~/.agents/skills/<name>/ | .agents/skills/<name>/ |
Symlinking from a single canonical repo (the pattern agent-skills follows) lets you maintain one source of truth across all surfaces.
10.5 Runtime constraints to design around
| Surface | Network | Package install | Filesystem |
|---|
| claude.ai | Varies (admin-controlled) | npm/PyPI/GitHub | Sandbox |
| Claude API | None | None (pre-installed only) | Container |
| Claude Code | Full | Local-only recommended | User's machine |
| Hermes | Configurable backends (local, Docker, Modal) | Per-backend | Per-backend |
If you write a skill that depends on network calls or fresh pip install, it will fail on the Claude API. Bundle dependencies into the skill itself, or document the constraint in compatibility:.
10.6 MCP tool references
If your skill uses MCP tools, always use fully-qualified tool names to avoid "tool not found" errors when multiple MCP servers are connected:
Use the BigQuery:bigquery_schema tool to retrieve table schemas.
Use the GitHub:create_issue tool to create issues.
Format: ServerName:tool_name.
§11. The Nine Skill Archetypes (Anthropic's Internal Taxonomy)
Anthropic's internal skill catalog clusters into nine archetypes. The best skills fit cleanly into one of them; multi-archetype skills are usually doing too much.
| # | Archetype | Examples |
|---|
| 1 | Library & API Reference | Internal SDK docs, CLI gotchas, framework conventions |
| 2 | Product Verification | Playwright tests, tmux session capture, video recording, smoke tests |
| 3 | Data Fetching & Analysis | Dashboard queries, cohort comparisons, monitoring stack hooks (Grafana, Datadog) |
| 4 | Business Process Automation | Standups, ticket creation, weekly recap, recurring batch jobs |
| 5 | Code Scaffolding & Templates | Org-pattern boilerplate, framework-correct stubs |
| 6 | Code Quality & Review | Adversarial review, style enforcement, test-coverage discipline |
| 7 | CI/CD & Deployment | Babysit PRs, deploy services, cherry-pick to prod, release notes |
| 8 | Runbooks | Symptom → investigation → structured incident report |
| 9 | Infrastructure Ops | Cleanup orphaned resources, dep upgrades, cost-spike investigation |
When scoping a new skill, name the archetype out loud first. If the answer is "it's a mix of 4 and 7," that's a smell — split it.
§12. The Discipline — Build Evaluations BEFORE Writing the Skill
This section adapts the Iron Law from superpowers:writing-skills and the official Anthropic best-practices doc into one rigorous workflow. Skip this only at your peril.
12.1 The Iron Law
No skill ships without a failing baseline test first.
If you wrote the body before you watched an agent fail without it, you don't know what the skill is teaching, you only know what you think it's teaching. Those are different.
12.2 The five-step iterative workflow
- Identify gaps. Run an agent on representative tasks without the skill. Document the specific failures verbatim — what choices did it make, what rationalizations did it use, what did it miss?
- Create three evaluations. Concrete tasks the skill should solve. Specify expected behaviors as a checklist.
- Establish baseline. Measure the agent's performance on the three evals without the skill. This is your "RED" state.
- Write the minimum SKILL.md that addresses the documented failures. Don't add content for hypothetical cases.
- Verify. Re-run the evals with the skill loaded. The agent should now comply. This is your "GREEN" state. Iterate until bulletproof.
12.3 The Claude A / Claude B pattern
The most effective dev cycle uses two agent instances:
- Claude A is your collaborator. You work with it to design and refine the skill. Claude A understands what other agents need and helps you write good instructions.
- Claude B is the test subject. A fresh instance with the skill loaded that you give real tasks to. Watch where it struggles, succeeds, or makes unexpected choices.
The cycle:
- Work with Claude A on a real task (no skill yet). Provide context, corrections, preferences.
- Ask Claude A to extract the reusable pattern into a SKILL.md.
- Test on Claude B (fresh instance, skill loaded) on related tasks.
- Bring observations back to Claude A — "Claude B forgot the test-account filter; how do we make that more prominent?"
- Refine. Re-test on Claude B. Repeat.
This is more effective than authoring the skill yourself because Claude A has direct knowledge of agent failure modes and Claude B reveals gaps your domain expertise hides from you.
12.4 Test on every model you'll deploy to
Skills act as additions to the underlying model. What works on Opus may underperform on Haiku. Test the skill on every Claude model (Haiku, Sonnet, Opus) and on Hermes/OpenClaw if you target those surfaces.
A common failure: skill works perfectly on Opus, ships, then a Haiku-driven session ignores it because the description trigger isn't strong enough for the smaller model. Strengthen the description and re-test.
12.5 Three types of test scenario
| Skill type | Test approach |
|---|
| Discipline-enforcing (rules, requirements) | Pressure scenarios — does the agent comply under stress, time pressure, sunk cost? Add explicit counters for each rationalization observed. |
| Technique (how-to guides) | Application scenarios — can the agent apply the technique to novel cases? Variations? Edge cases? |
| Pattern (mental models) | Recognition scenarios — does the agent recognize when the pattern applies? Counter-examples? |
| Reference (API docs, lookups) | Retrieval scenarios — can the agent find the right info? Are common use cases covered? |
12.6 The rationalization table (for discipline skills)
Every excuse the agent makes for skipping the rule goes in a table. Build the table incrementally as you observe new excuses, and include explicit counters in the skill body.
Example table — "common excuses for skipping testing" (paste this into discipline skills as-is):
| Excuse | Reality |
|---|
| "Skill is obviously clear" | Clear to you ≠ clear to other agents. Test it. |
| "It's just a reference" | References can have gaps and unclear sections. Test retrieval. |
| "Testing is overkill" | Untested skills always have issues. 15 min testing saves hours. |
| "I'll test if problems emerge" | Problems = agents can't use skill. Test BEFORE deploying. |
| "Too tedious to test" | Less tedious than debugging in production. |
| "I'm confident it's good" | Overconfidence guarantees issues. Test anyway. |
| "Academic review is enough" | Reading ≠ using. Test application. |
| "No time to test" | Untested skill wastes more time fixing later. |
12.7 Red flags — STOP and restart
These thoughts mean you are rationalizing skipping the discipline:
- "I already manually tested it"
- "The body is fine, I don't need to re-baseline"
- "It's a small change"
- "Tests-after-shipping achieve the same goal"
- "This is different because…"
- "I'll add the test later"
- "I'm confident it works"
All of these mean: stop. Run the baseline. Write the minimum. Verify GREEN.
12.8 Refactor — close every loophole
After the first GREEN, run the agent through more pressure scenarios. If it finds a new rationalization, add an explicit counter. Re-test. Repeat until you cannot break it.
Violating the letter of the rules is violating the spirit of the rules. Spirit-vs-letter arguments are themselves a rationalization. Cut them off explicitly in the body.
§13. Spending Context Wisely (The Token Economy)
The context window is a public good. Every token in your skill competes with conversation history, system prompts, other skills' metadata, the user's actual request, and tool definitions. A skill that wastes tokens degrades every other skill in the session.
13.1 The "Claude is already smart" axiom
Default assumption: the agent already knows the basics of every common technology, library, language, and concept. You are adding domain-specific or project-specific knowledge it does not have.
Cut everything that explains things the agent already knows.
13.2 The audit pass
After drafting a SKILL.md, do an audit pass with three questions on every paragraph:
- Does the agent really need this? (If no, delete.)
- Can I assume the agent already knows this? (If yes, delete.)
- Does this paragraph justify its token cost? (If no, delete or move to Tier 3.)
Be ruthless. The body should feel almost too sparse when you're done — that's the right level. If it feels comfortable and complete, you have probably over-explained.
13.3 Token budgets in practice
| Loaded | Token target | Note |
|---|
| YAML frontmatter (Tier 1) | 50–150 tokens | Counts against every skill in every session |
| SKILL.md body (Tier 2) | <5,000 tokens | Loaded only on activation; aim for <2,500 if possible |
| Combined references files | unlimited | Each file loaded only when body says to |
| Combined scripts | unlimited | Code never enters context — only output |
This skill (Skillception) is the deliberate exception: ~1,800 lines × ~25 tokens/line ≈ 45,000 tokens on activation. Justified because it is a study reference invoked rarely; not a pattern to imitate for tactical skills.
13.4 Skills vs. MCP — token math you can quote
Adding an MCP server typically advertises 10K–50K tokens of schema on connection (the GitHub MCP commonly cited at ~50K). That cost is paid every session, whether you use the server or not, before you've issued a single request.
Adding a skill costs ~100 tokens per skill at startup; the body loads only when activated. An equivalent capability shipped as a skill rather than an MCP server is 100×–500× cheaper per idle session. Skills win whenever the capability can be expressed as a procedure rather than a tool surface.
§14. Anti-Patterns Encyclopedia
Every entry: the anti-pattern, why it fails, and the fix.
14.1 Description anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|
| Trigger lives in the body | Body only loads after trigger; trigger in body never fires | Move all activation criteria into the description |
| First-person voice | Inconsistent POV breaks discovery in some clients | Third person ("Processes…") |
| Workflow summary in description | Steers agent to follow description instead of body | Describe what + when only; no steps |
| Vague verb ("helps with", "handles") | Description doesn't match user phrasing | Concrete action verb ("extracts", "generates") |
| Keyword stuffing | Lowers signal density; description gets truncated | 3–5 high-signal terms, no filler |
| Missing the "when" | Skill never triggers | Add "Use when [phrasings]" |
14.2 Body anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|
| Body >500 lines without justification | Token waste; agent struggles to extract relevant parts | Split into references; or document the trade-off |
| Walls of text | Models lose track in unstructured prose | Headers, numbered steps, tables, code blocks |
| Generic instructions ("make it look good") | Models cannot operationalize | Specific anti-patterns ("avoid uniform spacing") |
| ALWAYS / NEVER without reasoning | Fragile when situation differs from anticipated | Explain why — model generalizes from rationale |
| Time-sensitive content in main flow | Goes stale | "Old patterns" section |
| Inconsistent terminology | Confuses both agent and reviewer | Pick one term per concept |
@import-style references in body | @ syntax only works in CLAUDE.md, not SKILL.md | Use markdown links: [text](path/file.md) |
| Cross-skill dependencies | Each skill must be self-contained | Duplicate critical context, or merge skills |
| "When to Use This Skill" section in body | Body loads after trigger; section is dead | Move to description |
| Agent-name in body ("Claude will…") | Skills run on multiple models/clients | Use "the agent" or imperative voice |
14.3 File-organization anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|
Reference chains (SKILL.md → A.md → B.md → C.md) | Agents partial-read referenced-from-references; miss content | All references one level deep from SKILL.md |
| Reference file >100 lines without TOC | Agents partial-read; miss content past their preview | Add table of contents at top |
| Windows backslashes in paths | Breaks on Unix | Forward slashes only |
| Bundling node_modules / build artifacts | Multi-MB skills, slow loading, security audit nightmare | .gitignore aggressively |
Folder name ≠ name field | Loaders reject | Match exactly |
14.4 Script / scaffolding anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|
Punting errors to the agent (open(path).read() no try/except) | Wastes tokens making agent debug | Handle errors in script with helpful messages |
Voodoo constants (TIMEOUT = 47) | Agent (and humans) can't decide whether to change | Self-documenting comments — why this value? |
| Magic numbers in prose | Same problem | "The timeout of 30s accounts for slow connections" |
| Assuming packages installed | Skill fails first run | Document dependencies; or bundle with skill |
| Network-dependent scripts on Anthropic API | API has no network access | Document compatibility: constraint or restructure |
14.5 Process anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|
| Writing skill before baseline | You don't know what it's teaching | Run agent without skill first; document failures |
| Adding "for hypothetical cases" content | Bloat with no demonstrated value | Only address documented failures |
| Skipping eval on Haiku | Skill underperforms on smaller models | Test on every model you deploy to |
| Editing skill without re-testing | Untested changes regress agents | Re-run evals on every edit |
§15. Distribution & Sharing
15.1 Scope decision tree
Is the skill specific to one project?
├─ YES → .claude/skills/ (project scope, commit to repo)
└─ NO → Does it need to ship with other tools?
├─ YES → Plugin (.claude-plugin manifest, marketplace distribution)
└─ NO → ~/.claude/skills/ (personal scope) and/or your central repo
15.2 Versioning
Use semantic versioning in metadata.version:.
- MAJOR — breaking changes to behavior, frontmatter, or activation triggers
- MINOR — new features, backward-compatible
- PATCH — bug fixes, documentation updates, gotcha additions
Document deprecations in a ## Old patterns section. Give 30 days before deleting deprecated content from skills others depend on.
15.3 Publishing channels
| Channel | When to use |
|---|
| GitHub repo (your own) | Default. One canonical source, others install via npx skills add or symlink |
| Plugin marketplace (Claude Code) | When the skill is part of a larger plugin that includes hooks, agents, commands |
Anthropic Skills Hub (anthropics/skills) | Aspirational — open-source skills with broad utility |
Hermes Hub (hermes skills publish) | If targeting Hermes specifically |
| Internal company registry | At scale (>50 employees), curate centrally |
15.4 The "small team vs. scale" pattern
- Small team: check skills into the project repo. Iterate freely. Don't formalize until you have 20+ skills.
- At scale: stand up an internal plugin marketplace; introduce review workflow; let skills grow organically before curating.
"The best skills started as a few lines and one gotcha, then got better as Claude hit new edge cases." — Anthropic internal
§16. Security
Skills are executable instructions. Treat them like installing software, not like reading documentation.
16.1 Audit checklist for third-party skills
Before adding any skill from an unknown source:
16.2 Threat model
| Threat | Mitigation |
|---|
| Tool misuse — skill instructs agent to invoke tools harmfully | Audit allowed-tools; deny by default |
| Data exfiltration — skill leaks sensitive data to external systems | Block network in untrusted skills; review all fetch/curl/HTTP calls |
| Prompt injection — fetched content contains malicious instructions | Treat any fetched URL as untrusted; sanitize before using as input |
| Supply chain — compromised dependency in scripts/ | Pin versions, audit lockfiles, no global installs |
| Privilege escalation — skill assumes more access than user intended | Constrain via permissions settings, not trust in skill content |
16.3 Hermes trust tiers
Hermes ships a four-tier trust model worth replicating:
- builtin — ships with the host (always trusted)
- official — from a curated optional-skills repo (no third-party warning)
- trusted — from named trusted publishers (e.g.,
openai/skills, anthropics/skills)
- community — non-dangerous findings can be
--forced; dangerous findings blocked
Apply the same tiering to your own catalog: only the builtin tier should run unaudited.
§17. The Pre-Ship Checklist (apply on every skill, every release)
Frontmatter
Body
File organization
Calibration
Testing
Distribution
Discipline
§18. Quick Reference Card
18.1 The numbers
| Quantity | Value |
|---|
name max length | 64 chars |
description max length | 1,024 chars |
Combined description + when_to_use cap (Claude Code listing) | 1,536 chars |
| SKILL.md body recommended max | 500 lines / 5,000 tokens |
| Reference file TOC threshold | 100 lines |
| Reference depth max | 1 level from SKILL.md |
| Tier 1 (metadata) typical cost | ~100 tokens / skill |
| Tier 2 (body) typical cost | <5,000 tokens / activation |
| MCP comparison (GitHub MCP schema) | ~50,000 tokens / session |
| CLAUDE.md target | <200 lines (60 preferred) |
| Skill threshold rule of thumb | repeated >1× / day |
18.2 The hard rules (memorize)
name = lowercase a-z + digits + hyphens, no leading/trailing/consecutive hyphens, ≤64 chars, matches folder.description = third person, ≤1,024 chars, contains both what and when with concrete trigger keywords.- Description is the trigger — body never overrides description-driven discovery.
- SKILL.md ≤500 lines unless deliberately documented otherwise.
- References one level deep, with TOC if >100 lines.
- Forward slashes in all paths.
- Imperative voice.
- Reasoning over rigidity.
- No reserved words (
claude, anthropic) in name.
- No
@import in SKILL.md (works only in CLAUDE.md).
18.3 The reflexes (apply automatically)
- Wrote ALWAYS / NEVER in caps? Reframe with reasoning.
- Listed three options? Pick one as default; demote the rest.
- Wrote "When to Use This Skill" in body? Move to description.
- Body crossing 500 lines? Split or document trade-off.
- About to ship without baseline test? Stop. Run baseline.
- Found a new agent failure? Add to gotchas.
- Skill not triggering? Description is too vague; add concrete trigger phrases.
- Skill triggers too often? Description is too broad; tighten.
18.4 Skill triage flowchart
User has a recurring problem.
│
▼
Is the work repeated >1× / day?
├─ NO → don't write a skill yet; revisit when frequency justifies it
└─ YES ↓
Is the expertise non-obvious to a fresh agent?
├─ NO → put it in CLAUDE.md (always-loaded fact)
└─ YES ↓
Is the trigger describable in <1024 chars?
├─ NO → split into multiple skills with narrower triggers
└─ YES ↓
Does it need filesystem state, scripts, or large references?
├─ NO → consider a slash command instead (lighter weight)
└─ YES → write a SKILL — and follow this document.
§19. The Rationalization Table (Anti-Excuse Defense)
Every excuse for skipping skill discipline. Cut each one off explicitly.
| Excuse / thought | Reality |
|---|
| "It's a small skill, it doesn't need testing" | Small skills ship 90% of bugs. Test it. |
| "The description is obviously clear" | Clear to you ≠ clear to other agents. Test it. |
| "I'll fix the description if it doesn't trigger" | You won't notice it isn't triggering. Test it. |
| "500 lines is a guideline, not a rule" | True; deviations need explicit justification, not a vibes-based pass. |
| "The body covers when to use" | Body loads after trigger. Trigger in body is dead. |
| "I'll add gotchas as I go" | Gotchas you don't capture become gotchas you re-encounter. Capture immediately. |
| "I tested on Opus, it's fine" | Haiku may behave differently. Test on every deployment model. |
| "The skill works in my session, ship it" | Your session has CLAUDE.md / context the next session won't. Test in fresh session. |
| "I edited slightly without re-testing" | Even small edits regress. Re-test on every change. |
| "The agent should figure it out" | Agents don't figure out missing context. Document it. |
| "Spirit not letter — it's basically tested" | Spirit-vs-letter is itself a rationalization. Run the actual test. |
| "I can't be bothered with the dual-format frontmatter" | Then you can't ship to Hermes. Decide and document. |
| "I'll write the skill, then the eval" | Iron Law violated. Eval first. Always. |
§20. Citations and Mandatory Authorities
This skill is grounded in and must defer to:
Primary authorities (must adhere)
- Anthropic. The Complete Guide to Building Skills for Claude. 33-page PDF, January 2026.
https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf
- agentskills.io. Best practices for skill creators. (Open standard, evolving.)
https://agentskills.io/skill-creation/best-practices
- agentskills.io. Specification.
https://agentskills.io/specification
Anthropic official documentation (canonical)
- Anthropic Agent Skills overview. https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
- Anthropic Skill Authoring Best Practices. https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
- Claude Code Skills. https://code.claude.com/docs/en/skills
- Anthropic Skills repository (open-source examples). https://github.com/anthropics/skills
- Anthropic blog announcement. https://claude.com/blog/skills (October 16, 2025; updated December 18, 2025)
Cross-platform references
- Hermes Agent (Nous Research) — Creating Skills. https://hermes-agent.nousresearch.com/docs/developer-guide/creating-skills
- OpenClaw — Creating Skills. https://docs.openclaw.ai/tools/creating-skills
Community wisdom
- Thariq Shihipar (Anthropic). Lessons from Building Claude Code: How We Use Skills. Original thread/article at x.com/trq212/status/2033949937936085378 and gist mirrors. The 9-archetype taxonomy in §11 derives from this article.
- shanraisshan / claude-code-best-practice. https://github.com/shanraisshan/claude-code-best-practice (community gold; CLAUDE.md sizing, sub-agent + skill composition).
- lipex360x — Skill Authoring Guide gist. https://gist.github.com/lipex360x/3a1a662525e88a3e856b7fda02ab8ce3 ("even if they don't explicitly say X" pattern).
- Boris Cherny (Anthropic, Claude Code creator) — internal Anthropic skills tutorial summary on Twitter (cyn2JPlvTG4 video). Source for
/simplify, /batch, anthropic/claude-plugins-official references and frontmatter extensions.
Discipline foundations
superpowers:writing-skills (Iron Law, RED-GREEN-REFACTOR for documentation, rationalization-table pattern).superpowers:test-driven-development (the underlying discipline this skill imports).
Any conflict between this document and items (1)–(3) above resolves in favor of items (1)–(3). Re-read those first if uncertain. The rest of this document distills, organizes, and operationalizes their guidance with cross-platform extensions and discipline machinery from the community sources.
§21. Final Word
Skills are how you turn a generally capable agent into a specific one — your codebase's specialist, your domain's expert, your runbook's executor. Authoring a skill is a discipline, not a sprint.
The five non-negotiables, restated:
- Description is the trigger — third person, what + when, concrete keywords.
- Body ≤500 lines unless you have documented why this skill is the exception.
- Add what the agent doesn't know — cut everything else.
- References one level deep with TOCs over 100 lines.
- No skill ships without a baseline test — RED before GREEN.
Everything else in this document is in service of those five. When in doubt, return to them.
"A skill is an employee, not a file."
Treat your skills like you'd treat your best onboarding: bounded, documented, tested, refined every time you observe a failure. Future-you will thank present-you for the rigor.
— Skillception v1.0.0 — May 2026 — zaydiscold/agent-skills
