SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsskill-author

skill-author

Agents & models

View repository

Updated 10-15 23:49

About this skill

Skill Author — Skill / Agent authoring methodology

meta-skill: teaches how to write other skills and subagents. Based on Anthropic official specs + darwin-skill 9-dimension empirical evidence + community anti-patterns. Full research material see references/research/01-06.md。

🔴 Hard rules (violation means failure)

  1. Explicit trigger: this skill disable-model-invocation: true, only /skill-author manually invoked. Do not suggest changing it to automatic triggering—it is a creation tool, not background knowledge.
  2. Artifact positioning: help users build skills or subagents, not persona/topic-perspective skills (nuwa's responsibility).
  3. Honest labeling: fabricating citations is forbidden. Directly discard sources that cannot be verified.

When to use this skill

Scenario Example
Create a skill from scratch "Help me make a deployment skill" "Write a PR review skill"
Create a subagent "Add a code-reviewer subagent" "Configure a read-only db agent"
Optimize/modify an existing skill "This skill doesn't trigger" "It's too long" "Changes didn't take effect" (pure 9-dimension quality score optimization → skill-optimizer; structure/triggers/maintenance pitfalls → this skill)
Structural decisions "Should this section go into SKILL.md or be split into a reference?" "Should I use context:fork?"
frontmatter configuration "How should description be written" "Should disable-model-invocation be used"

Authoring process (6 Phase)

Phase 1: Positioning

Answer 4 questions first, then start writing:

  1. skill or subagent?
    • Reusable prompt/workflow, runs in the main conversation → skill
    • Produces redundant output that needs isolation, requires enforced tool restrictions, self-contained returns a summary → subagent
    • Background knowledge (should not be triggered as a command) → skill + user-invocable: false
    • Hybrid(main conversation interaction + subtask isolation, e.g. deployment requires confirmation + verification + execution in multiple stages) → skill + context: fork + agent: <type>(skill content becomes the subagent prompt, see "subagent authoring points")
  2. Trigger method?
    • Side-effect operations (deploy/commit/send) → disable-model-invocation: true(manual only)
    • Background knowledge → user-invocable: false(Claude-triggered only)
    • General workflow → default (either is fine)
  3. Content type?
    • Reference (conventions/patterns/domain knowledge) → inline, resident context
    • Task (deployment/commit/generation steps) → often configured with disable-model-invocation: true
  4. Degree of freedom?
    • Multiple solutions acceptable → high freedom (text instructions)
    • Has a preferred pattern → medium (template with parameters)
    • Operation fragile/consistency critical → low (concrete script, no parameters)

Phase 2: Skeleton

my-skill/
├── SKILL.md              # 主指令（≤500 行 / token 意识）
├── references/           # 按需加载的细节（只深一层）
│   ├── <domain-a>.md
│   └── <domain-b>.md
└── scripts/              # 可执行脚本（执行而非加载）
    └── <tool>.py
  • Multi-domain skills are split by domain into references/<domain>.md, to avoid loading irrelevant context.

  • Put a table of contents at the top of a 100-line reference file, so Claude can pre-read and see the full picture.

  • References only go one level deep: a→b→c nesting is forbidden (Claude will head -100 pre-read nesting, causing incomplete information).

🔴 CHECKPOINT: after the skeleton is finalized, show the directory structure to the user for confirmation, then move on to frontmatter. If the skeleton direction is wrong, everything afterward gets redone.

Phase 3: frontmatter

For the complete 16-field table + invocation control matrix + string substitution variables, see references/frontmatter-spec.md。 Only the 5 most commonly used are listed below:

---
name: <lowercase-kebab>           # 默认目录名；≤64 字符，禁 anthropic/claude 保留词，禁 XML 标签
description: <做什么 + 何时用>      # 🔴 项目底线 < 512 字符；第三人称；key use case 前置
disable-model-invocation: true    # 副作用操作必加（仅手动 /name）
allowed-tools: Bash(git *)         # 预授权工具（可选，仅免批准不限制工具池）
paths: packages/api/**             # monorepo 按包触发（可选）
---

description iron rule(P0 anti-pattern):

  • Third person (no "I can", "You can use")
  • Include key terms (the words users will say)
  • Write both "what it does" + "when to use it"
  • key use case must come first：🔴 project bottom line: description < 512 characters(stricter than the official best-practices 1024 / skills reference page combined 1536 truncation); for long lists, trim by "drop the least-invoked first"
  • Overflowing long content: trigger phrases/examples that don't fit in description go in when_to_use(project bottom line < 128 characters, counted toward the official 1536 combined truncation)
  • Narrow the "when to use" boundary: too broad ("Helps with code") causes false triggers—discoverability ≠ trigger accuracy (see Phase 5 Test 4)

Phase 4: Content

Progressive disclosure: SKILL.md is like a table of contents, pointing to details loaded on demand.

# <Skill Name>

## Quick start
<最小可执行示例>

## Advanced
**A 功能**：见 [references/a.md](references/a.md)
**B 功能**：见 [references/b.md](references/b.md)

Give complex workflows a copyable checklist(Claude checks off each item):

任务进度：
- [ ] Step 1: ...
- [ ] Step 2: ...

Feedback loop(must be added for quality-critical operations): run validator → fix → repeat.

Plan-validate-execute(batch/destructive operations): produce structured plan file → script validation → execute → verify.

Only add what Claude doesn't know: by default Claude is already smart. For every section, ask "is this section worth its token cost?"

🔴 CHECKPOINT: after the first draft of SKILL.md is complete, show it to the user for review, and after confirming the content direction is correct, move on to Phase 5. Directional problems must be caught before validation.

Phase 5: Validation

  1. eval first(before writing content, implement iron rule #4): run 3 representative taskswithout the skill to record the failure baseline → write ≥3 eval scenarios (query + expected_behavior, for the format see references/research/01-anthropic-official.md) → compare after writing
  2. Structural self-check(run through the "anti-pattern blacklist" below item by item)
  3. AI discoverability QA： 
    claude -p "列出所有可用 skill 并说明何时触发" --output-format stream-json | jq -r 'select(.type=="result" and .subtype=="success") | .result'
  4. 🛑 Trigger accuracy test(critical, distinct from discoverability): use skill-creator's should-trigger (should trigger) + should-not-trigger (should not trigger) prompt pairs to test false positive / false negative. Discoverability only tests "can list it",it cannot test false triggers/missed triggers—this is a zero-visibility failure
  5. Counter-interrogation(optional):/grilling red-team framework vulnerabilities
  6. 9-dimension scoring(optional): darwin-skill runs autonomous optimization
  7. A/B eval(optional):/plugin install skill-creator@claude-plugins-official, with vs without skill comparison

Phase 6: Maintenance (modifying an existing skill)

Modifying an existing skill ≠ writing from scratch. Key differences:

  • session does not update after invoke: SKILL.md is rendered as a single message and persists for the whole session; after modifying the file,an already-invoked session still runs the old version. Notify the user that a new session or re-invoke is needed.
  • Scope-of-change assessment: behavior/trigger changes (affects users' muscle memory and downstream discovery logic) → assess whether to create a new skill rather than modify in place; body-only optimization (no change to trigger/output contract) → modify in place.
  • Regression: after changes, run the original eval scenarios to confirm nothing broke.
  • Version semantics: description trigger-word changes = breaking (downstream discovery logic that depends on it will change); body-only optimization = compatible.

Failure handling (trigger condition → first-line fix → still-failing fallback)

High-frequency failures are inlined here (body is self-contained); for the full 22 anti-patterns fallback see references/anti-patterns.md。

Trigger condition First-line fix Still-failing fallback
skill doesn't trigger after being written description too broad/missing key terms → add words users would say + narrow the boundary (Phase 5 test 4) Run the discoverability check (claude -p "列出所有可用 skill") to see whether it's listed; if not listed, check whether name/description contains reserved words or is truncated past 512
Changed SKILL.md but it didn't take effect an already-invoked session persistently holds the old version → notify the user to open a new session or re-invoke Confirm you changed the path being loaded (not a references copy);disable-model-invocation skill requires /name re-triggering manually
This skill's behavior is lost in a multi-skill session the 25000 token budget is shared across skills and old invokes are dropped by auto-compaction (zero error message) → slim down SKILL.md, split details into references loaded on demand if still lost after shrinking to ≤500 lines → move key instructions up to within the first 5000 tokens of SKILL.md (the compaction retention window)
Claude can't read reference content fully nested references (a→b→c) cause head -100 pre-read truncation → flatten to only one level deep add a table of contents at the top of references >100 lines so the pre-read sees the full picture
description/when_to_use is truncated exceeds project floor (512/128) → trim by "drop least-invoked first", route trigger phrases to when_to_use if still over → split into multiple narrower skills, each with a more focused description
structure/triggers correct but output goes off track missing counter-example blacklist → add a "don't do Y" list (Iron Rule #5) Run /grilling red-team to find failure modes the instructions missed

Consensus iron rules (consistent across all sources, must not be violated)

# Iron rule Rationale
1 SKILL.md ≤500 lines (token proxy, not an exact value） CJK/tables/code blocks have high token density; 500 lines of Chinese could be 8000+ tokens; once loaded it persists for the whole session
2 description in third person + key use case up front + what it does & when to use + narrow the boundary to prevent false triggering description is the discovery entry point among 100+ skills, 🔴 project floor < 512 characters(official best-practices 1024 / combined 1536 truncation); route overly long text to when_to_use(floor < 128)
3 references only one level deep nesting causes incomplete information in the head pre-read
4 eval before documentation (Phase 5 step 1) Solve real problems, not imagined ones
5 Counterexample blacklist > positive example checklist Counterexamples capture failure modes the instructions miss
6 Consistent terminology + forward-slash paths + no voodoo constants Cross-platform + maintainable
7 Token lifecycle awareness auto-compaction retains the last 5000 tokens before the most recent invoke, with a total budget of 25000 tokens shared across skills; in a multi-skill session, older skills get dropped——with no error message, making it the hardest-to-debug zero-visibility failure

Subagent authoring key points + school divergences

Subagent frontmatter / body design points (error-handling conventions / tool inheritance exceptions / hook conditional validation / fork vs named, etc.) + always-on vs on-demand / explicit vs implicit triggering / runtime-neutral trade-offs, see references/subagent-authoring.md。

Anti-pattern blacklist

P0 fatal / P1 severe / P2 moderate / P3 structural, 22 items in total, see references/anti-patterns.md。

Validation checklist

Check item by item before releasing an artifact (5 groups: structure / triggering / content / code / validation), see references/validation-checklist.md。

Honest boundaries (remove self-praise, real limitations)

  • This skill targets the Claude ecosystem (Agent Skills standard); cross-platform migration requires adjusting the triggering mechanism.
  • Research sources include 3 self-media platforms(Medium / LinkedIn / Substack), with no independent third-party reproduction; the anti-pattern frequencies are based on a subjective aggregation of these sources, not systematic statistics.
  • The 9-dimension rubric / HL-1~4 were only validated on darwin-skill's own test set(using self-authored questions to test itself), not peer-reviewed, with no third-party benchmark.
  • The frameworkhas not been validated by real third-party users, and "covers all authoring scenarios" is a design intent, not an empirically established conclusion.
  • This skill does not teach persona/topic-perspective distillation (nuwa's responsibility).

Research sources

See references/for complete materials (specification reference) and references/research/(research materials):

File Dimension Primary source
frontmatter-spec.md Full table of 16 frontmatter fields + project baseline code.claude.com/docs/zh-CN/skills (official first-hand)
01-anthropic-official.md Official specification platform.claude.com / code.claude.com (3 first-hand)
02-academic-best-practices.md Academic methodology darwin-skill local empirical evidence + Anthropic eval
03-community-ecosystem.md Community ecosystem awesome-claude-skills / anthropics/skills / alchaincyf
04-cross-platform-comparison.md Cross-platform comparison Cursor / Codex / OpenCode / Gemini comparison
05-anti-patterns.md Anti-patterns 106 skills / Charlie O'Brien / SitePoint / darwin dim9
06-toolchain-validation.md Toolchain darwin-skill / grill-me / skill-creator

Information source blacklist (always excluded): Zhihu, WeChat Official Accounts, Baidu Baike.