shield_lock
金大哥
← 返回 Skill 列表
extension
分类: AI Agent 能力无需 API Key

generate-skill

当被要求“创建一个技能”、“生成一个SKILL.md”、“为我制作一个技能”、“构建一个自定义技能”，或者用户希望通过新技能扩展Claude Code的功能时使用

person作者: jakexiaohubgithub
open_in_new仓库download下载资源包

Generate Skill

Overview

Produces a single, ready-to-ship SKILL.md (plus optional references/, scripts/, assets/) following 2026-05 conventions distilled from Anthropic's skill-creator, the agentskills.io spec, and empirical activation research.

One skill, one job. This skill's job is the SKILL.md and its frontmatter — not docs, releases, or auxiliary files.

Core principles

  • The description is the product. It is the only thing Claude reads to decide whether to invoke the skill. Tune it like a prompt.
  • Soft directive, third person. "Use this skill whenever the user…" activates reliably without the brittleness of ALL-CAPS commands.
  • Front-load distinctive triggers. The first ~50 chars must contain the noun phrase that makes this skill unique; listing budgets silently truncate at high skill counts.
  • One skill, one job. Bundling unrelated workflows is the most-cited mega-skill failure mode.
  • Claude is already smart. Encode only non-inferable, procedural, skill-specific knowledge. No tutorials.

Workflow

Use AskUserQuestion to ask one question at a time. Never bulk-dump the discovery questionnaire. After each phase, show the artifact and confirm before moving on.

Phase 1 — Discovery

Ask these in order, one per turn:

  1. Skill purpose. One sentence: what job does this skill do?
  2. Skill type. Pick one — drives the body template:
    • methodology — enforces a multi-step workflow (e.g., code-review, track-session)
    • technical — wraps an API, format, or tool (e.g., docx, pdf, semantic-release)
    • auditing — grades or inspects an artifact (e.g., rate-skill, security-review)
    • reference — domain schemas, conventions, lookup tables (e.g., bigquery)
    • automation — wraps a script or external command (e.g., screenshot-local)
  3. Trigger phrases. Collect 5+ verbatim phrases a real user would say. Push for naturalese, not jargon ("create a skill", not "scaffold skill artifact").
  4. Negative scope. Which near-neighbor skills exist that this should not steal from? Drives the Do NOT use… clause.
  5. Enforcement level. Suggestion, guided (checklists), or strict (verification checkpoints). Defaults: methodology=guided, technical/reference=suggestion, auditing=guided, automation=suggestion.

Phase 2 — Description drafting

Compose a single-line YAML string, target ≤230 chars (soft cap — listing-budget safe; no penalty up to 500), shape:

<Third-person noun phrase>. Use whenever the user <wants/asks to> <trigger 1>, "<trigger 2>", or <trigger 3>. <Optional scope note.> Do NOT use this skill for <near-neighbor 1> — see <other-skill>.

Show the draft, count chars (python3 -c "import yaml; print(len(yaml.safe_load(open('SKILL.md').read().split('---',2)[1])['description']))"), iterate.

Quality signals:

  • ✅ Distinctive noun in first 50 chars
  • ✅ Third person (the skill, not "I")
  • ✅ Single line — no | or > block scalars (silently breaks discovery, anthropics/skills #9817)
  • ✅ At least one literal quoted user phrase
  • ✅ Do NOT use this skill for … clause when a near-neighbor exists
  • ✅ ≤230 chars (soft target — safe against listing-budget pressure)

Anti-patterns:

  • ❌ First person: "I help you create skills" — degrades activation
  • ❌ Vague: "A skill for creating skills"
  • ❌ Multi-line: any description: | block — silent discovery failure
  • ❌ Bullet-list description — no surveyed top skill uses this format
  • ❌ ALL-CAPS verb spam — Anthropic flags as a yellow flag

Phase 3 — Frontmatter

Emit only these fields, in this order:

---
name: <kebab-case, ≤64 chars, no "anthropic" or "claude" reserved words>
description: <single-line string from Phase 2>
license: MIT
argument-hint: [<short-token>]      # top-level, not nested
metadata:
  author: <user-supplied>
  version: "1.0.0"
---

Add these optional fields only when the skill genuinely needs them:

| Field | When to add | |---|---| | allowed-tools | Skill must restrict which tools the agent uses (Experimental) | | compatibility | Cross-agent (Cursor, Cline, etc.) compatibility note, ≤500 chars | | disable-model-invocation: true | Skill is slash-only, must not auto-trigger | | user-invocable: false | Skill is only callable by subagents or other skills | | model / effort | Skill needs a specific model tier or thinking budget | | paths | Skill should only auto-trigger inside specific repo paths |

Anti-patterns:

  • ❌ Top-level version, author, tags, category, hooks — produce "unexpected key" errors (anthropics/skills #37). They live under metadata.
  • ❌ Nested argument-hint under metadata — Claude Code reads it at top level.
  • ❌ Reserved-word names containing anthropic or claude.
  • ❌ Consecutive hyphens or uppercase in name.

Phase 4 — Body content

Pick the template that matches the skill type. Full templates live in references/PATTERNS.md — load only when generating the body.

Compact summary:

  • methodology — Overview, Core principles, Phased workflow (numbered, one task per phase), Examples (✅ first, ❌ last), Gotchas, optional Verification checklist.
  • technical — Overview, Quick start (one minimal code block), How it works, Quick reference tables, Examples, Gotchas. Move long API surface to references/API.md.
  • auditing — Overview, Scoring rubric (table: signal → weight → check), Output format, Examples of high/low-quality artifacts, Gotchas.
  • reference — Overview + navigation, then one references/<domain>.md per domain. SKILL.md stays a router; don't inline the data.
  • automation — Overview, Command surface table, Sample invocation, Failure modes, Gotchas. Put the actual script in scripts/.

Always include a ## Gotchas section — Anthropic engineers cite it as the highest-signal section in a skill body.

Length budget: aim <300 lines in SKILL.md, hard cap 500. The ETH Zurich AGENTS.md study (arXiv 2602.11988) found verbose context files reduce task success ~3% and inflate step count >20%.

Phase 5 — Examples

Produce 2–3 ✅ desired examples and 1 ❌ counter-example. Show ✅ first; if room, end on ✅ (recency bias).

Format:

### Example: <one-line task>

✅ Desired

<short code or transcript>

Why it works: <one sentence>.

### Counter-example

❌ Anti-pattern

<short code or transcript>

Why it fails: <one sentence>.

Do not use <Good> / <Bad> XML tags — they appear in zero of the 8 surveyed top community skills.

Phase 6 — Gotchas

Concrete failure modes specific to this skill — not generic skill-authoring advice. Each entry: one-line symptom, one-line cause, one-line fix.

Pair every "do not X" with a positive directive — negation handling in LLMs is empirically weak (arXiv 2503.22395).

Phase 7 — Progressive disclosure check

Count lines in the body. If SKILL.md exceeds 300 lines:

  1. List candidate sections to extract, largest first.
  2. Propose references/<TOPIC>.md files (plural directory — reference/ singular is a non-canonical anti-pattern).
  3. Keep extracted files exactly one level deep from SKILL.md. Deeply nested references silently get truncated by Claude's preview reads.
  4. Add a one-line pointer in SKILL.md for each extracted file: when to load it, what's in it.

Phase 8 — Eval set (required before finalize)

Anthropic's skill-creator now ships an A/B description optimizer with 60/40 train/test eval sets. Generate-skill emits an eval set for every skill before completing.

Generate 20 candidate queries:

  • 10 should-trigger — phrases that should fire the skill
  • 10 should-not-trigger — phrases for adjacent skills or unrelated work (especially near-neighbor skills from Phase 1 negative scope)

Save as references/EVAL.md. Ask the user to spot-check 3–5 in a fresh Claude session before finalizing. If activation is unreliable, return to Phase 2 and rework the description.

Output layout

<skill-name>/
├── SKILL.md                       # <300 lines, one job
├── references/                    # plural — load on demand
│   ├── PATTERNS.md                # optional: body templates by type
│   └── EVAL.md                    # 20-query eval set (Phase 8)
├── scripts/                       # optional: deterministic helpers
└── assets/                        # optional: templates copied into output

Examples

Worked description examples (methodology ✅, technical ✅, multi-line counter-example ❌): references/EXAMPLES.md.

Gotchas

  • Symptom: New skill never auto-invokes. Cause: Description used vague prose without specific triggers. Fix: Rewrite with the "Use whenever the user wants to…" form plus 3+ quoted trigger phrases.
  • Symptom: Skill works in isolation, breaks once user has >20 skills installed. Cause: Distinctive trigger is past char 50; listing budget truncated it. Fix: Move the distinctive noun to the start of description.
  • Symptom: YAML parses but skill never appears in /skills. Cause: Multi-line description: |. Fix: Collapse to a single line; move long context into the body's first paragraph.
  • Symptom: "Unexpected key" warning on load. Cause: Top-level version, author, tags, or hooks. Fix: Move them under metadata (except argument-hint, which stays top-level).
  • Symptom: Two skills both fire on the same prompt. Cause: Overlapping triggers, no negative scope. Fix: Add Do NOT use this skill for X — see Y to whichever skill is the wrong fit.
  • Symptom: SKILL.md is 700 lines, agent quotes the wrong section. Cause: Single-file overflow; Claude reads the head, misses the tail. Fix: Extract to references/ (plural), one level deep, with explicit "load when…" pointers.

Integration

  • rate-skill — Run after generating to grade the new SKILL.md against current standards. generate-skill produces; rate-skill audits.
  • references/PATTERNS.md — body templates by skill type; loaded on demand during Phase 4.

References

  • agentskills.io spec: https://agentskills.io/specification
  • Anthropic skill best practices: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
  • Claude Code skills docs: https://code.claude.com/docs/en/skills
  • Anthropic skill-creator: https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md
  • Anthropic skill-creator eval pipeline (May 2026): https://claude.com/blog/improving-skill-creator-test-measure-and-refine-agent-skills
  • Description activation study (Seleznov n=650): https://medium.com/@ivan.seleznov1/why-claude-code-skills-dont-activate-and-how-to-fix-it-86f679409af1
  • Skill listing budget: https://claudefa.st/blog/guide/mechanics/skill-listing-budget
  • ETH Zurich AGENTS.md study: https://arxiv.org/abs/2602.11988
  • Negation handling: https://arxiv.org/abs/2503.22395
  • anthropics/skills #9817 (multiline description bug): https://github.com/anthropics/claude-code/issues/9817
  • anthropics/skills #37 (unsupported frontmatter fields): https://github.com/anthropics/skills/issues/37