metaskill-authoring（元技能创作）

Writing Great Claude Code Skills

First: Two Key Questions

1. What should I name this? See /metaskill-naming for the naming convention and brainstorming process. 2. Single skill or skill group? Does this topic have 3+ distinct concerns users might approach from different angles? If YES, you need a skill GROUP (multiple skills in a plugin), not a single skill. See /metaskill-grouping for the skill group pattern.

Skill Directory Structure

Simple Skill (Single Concern)

skill-name/
  SKILL.md

Skill with Deep Content

skill-name/
  SKILL.md           <- Quick answers and rules
  references/        <- Deep dives (OPTIONAL reading)
    topic-a.md
    topic-b.md

Skill Group (Multiple Concerns)

plugin-name/
  .claude-plugin/
    plugin.json
  skills/
    plugin-name-doing/      <- ends in -ing
      SKILL.md
    plugin-name-other-ing/  <- ends in -ing
      SKILL.md
  README.md

Note: See /metaskill-naming for naming conventions (neutral noun prefix, -ing suffix for skills).

SKILL.md Structure

Required Frontmatter

---
name: skill-name
description: <What it does>. Use when <specific actions>. Triggers on "<keyword1>", "<keyword2>", "<keyword3>", or when <conditions>.
---

The description is CRITICAL - it's the only field that affects triggering. See /metaskill-triggering for optimization techniques.

Optional Frontmatter Fields

---
name: skill-name
description: ...
allowed-tools: Read, Edit, Bash(npm test:*)
disable-model-invocation: true  # Blocks auto-triggering (user must invoke)
---

Content Structure Template

# Skill Title

## Core Philosophy (1-2 sentences)
What problem does this skill solve? What's the key insight?

## Quick Start
The 80% case - what users need most often.

## Critical Rules
Essential dos and don'ts as code blocks:

✅ CORRECT

good_example()

❌ INCORRECT

bad_example()

## Checklist

Before completing, verify:

- Item 1
- Item 2

## Reference Files (if using references/)

For detailed patterns:

- [references/topic-a.md](https://github.com/gigaverse-app/skillet/blob/HEAD/metaskill/skills/metaskill-authoring/references/topic-a.md) - Deep dive on A
- [references/topic-b.md](https://github.com/gigaverse-app/skillet/blob/HEAD/metaskill/skills/metaskill-authoring/references/topic-b.md) - Deep dive on B

## Related Skills

- For X, see `/related-skill-a`
- For Y, see `/related-skill-b`

Progressive Disclosure

Principle: Quick answers in SKILL.md body, deep dives in references.

Warning: Don't put critical rules ONLY in references - they might be skipped!

When to Use References vs Skill Groups

Use references/ when:

• Content supports the main skill but isn't required
• Users who trigger the skill need the SAME core content
• Deep dives are nice-to-have, not essential

Use a skill group when:

• Content is independently triggerable (different keywords)
• Users might ONLY want a subset
• Each area has substantial, distinct content

Example:

# references/ appropriate

testing/ SKILL.md <- All testers need this references/ mocking.md <- Some need deep mocking info fixtures.md <- Some need deep fixture info

# Skill group appropriate (note: neutral prefix, -ing suffix)

metaskill/ skills/ metaskill-authoring/ <- "write skill" metaskill-triggering/ <- "fix trigger" (different concern!) metaskill-grouping/ <- "create plugin" (different concern!)

Trigger Optimization

Your skill is useless if it never triggers. Key points:

• ONLY the description field affects triggering
• Include exact phrases users say
• Include action verbs (Create, Write, Generate)
• Include keyword variants (test, tests, testing)

For comprehensive trigger optimization, see /metaskill-triggering.

Common Mistakes

Body too long: Extract deep content to references/

Critical rules in references: Keep essential rules in SKILL.md body

Weak description: See /metaskill-triggering for optimization

Monolithic skill for complex topic: See /metaskill-grouping for when to split

Bad naming: See /metaskill-naming for the naming convention

Related Skills

• For naming conventions, see /metaskill-naming
• For trigger optimization, see /metaskill-triggering
• For skill group pattern, see /metaskill-grouping
• For plugin packaging and placement, see /metaskill-packaging
• To test triggers, use the metaskill-trigger-tester agent