donggua-zen/guada/skill-creator

Skill Creator — Comprehensive Skill Authoring Guide

Overview

This skill guides you through the complete process of creating a new AI skill for the system. A skill is a reusable instruction bundle that teaches the AI how to perform a specific type of task. Skills follow the AgentSkills open specification.

Skills use progressive disclosure to manage context efficiently:

1. L1 — Metadata (~100 tokens): name + description loaded at startup for all skills
2. L2 — Instructions (SKILL.md body): Loaded only when the skill is activated
3. L3 — Resources (scripts/, references/, assets/): Loaded on demand

1. Skill Directory Structure

1.1 Full File Layout

<skill-name>/                        # Directory name = skill name (lowercase + hyphens)
├── SKILL.md                         # Required: metadata + instructions
├── scripts/                         # Optional: executable code
│   ├── script.py
│   ├── script.sh
│   └── ...
├── references/                      # Optional: reference docs loaded on demand
│   ├── api-spec.md
│   ├── configuration-guide.md
│   └── ...
├── assets/                          # Optional: templates, configs, resources
│   ├── template.json
│   ├── icon.svg
│   └── ...
└── ...                              # Any additional files or directories

1.2 Minimal Structure (always valid)

<skill-name>/
└── SKILL.md

A single SKILL.md file is all that's required. The optional directories are for organizing larger skills.

1.3 Location by Source Type

2. SKILL.md Format Specification

2.1 Overall Structure

---
<YAML frontmatter>
---
 
<Markdown body>

• Opening --- must be at line 1 of the file
• Frontmatter parser pattern: /^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/
• Must have a blank line after closing --- before body content

2.2 Frontmatter Fields

2.3 Name Validation Rules

The system enforces these rules:

✓ name is present (required)
✓ 1-64 characters
✓ matches ^[a-z0-9-]+$  (lowercase letters, digits, hyphens only)
✓ does not start or end with a hyphen
✓ does not contain consecutive hyphens (-- inferred by the pattern)
✓ matches the parent directory name (case-insensitive)

Examples:

✅ code-review
✅ data-analyzing-v2
✅ translation-helper
❌ Code-Review        (uppercase not allowed)
❌ code_review        (underscore not allowed)
❌ -code-review       (leading hyphen)
❌ code-review-       (trailing hyphen)
❌ code--review       (consecutive hyphens)

Naming Strategy

A good name is short, scannable, and self-explanatory:

• Use the core function as the name: pdf, docx, xlsx, mcp-builder
• Avoid vague names: tool, helper, utils, my-script — these don't tell Claude when to trigger
• Compound names OK: slack-gif-creator, web-artifacts-builder, theme-factory
• Version suffix only when needed: data-analyzing-v2 (not data-analyzing-final-final)
• Follow existing conventions: look at other skills in the system for naming patterns

Good names read like CLI commands — users and AI alike can guess what they do by reading the name alone.

2.4 Description Best Practices

The description is the primary trigger mechanism — it's what Claude reads to decide whether to use the skill. Get this right above all else.

Core Rules

• Use third-person ("Generating review reports…" not "Generate review reports…")
• Describe what the skill does and when to use it
• Max 1024 characters

The "Pushy" Style

Claude has a tendency to undertrigger skills — not use them when they'd be useful. To combat this, make descriptions a little pushy. Include not just what the skill does, but specific contexts where it should trigger — even if the user doesn't explicitly ask for it.

Pattern:

<what it does>. Use this skill whenever <context A>, <context B>, or <context C>,
even if the user doesn't explicitly mention <keyword>.

Good:

Creating slide decks, pitch decks, and presentations. Use this skill any time
a .pptx file is involved in any way — as input, output, or both. Trigger
whenever the user mentions "deck," "slides," "presentation," or references a
.pptx filename, regardless of what they plan to do with the content afterward.

Poor (too passive):

Creating PowerPoint presentations

Trigger Coverage

Ask yourself: what are all the ways a user might ask for this? List the synonyms, casual phrasings, and edge cases:

• Formal: "Generate a PDF report"
• Casual: "turn this into a PDF"
• Implicit: "I need to send this to the client" (implies PDF)
• Adjacent: "make this fillable" (implies PDF form)

Cover these in the description so Claude catches them all.

What NOT to Put in Description

• ❌ Implementation details ("uses Python 3.10 with pandas")
• ❌ Step-by-step instructions (that goes in the body)
• ❌ Developer notes ("todo: add error handling")
• ❌ Version info or changelog

Good:

Generating comprehensive code review reports, identifying potential bugs,
security vulnerabilities, and style violations in pull requests. Use when
reviewing PRs or analyzing code quality.

Poor:

Code review tool

2.5 Frontmatter Example

---
name: data-analyzing
description: Analyzing structured datasets, identifying trends, and generating statistical summary reports
version: 2.1.0
author: team-data
tags: [analysis, data-science, reporting]
license: MIT
compatibility: Requires Python 3.10+ with pandas and numpy
---

3. Progressive Disclosure Model

3.1 L1 — Metadata (always loaded)

Only name and description are loaded into the system prompt at startup. The AI uses this to determine if a skill might be relevant to the user's request. This is why description must include trigger keywords.

3.2 L2 — Instructions (activated on demand)

When the AI decides a skill is relevant, it reads the full SKILL.md body from its file path (provided in the skills list). This is the core instruction content.

3.3 L3 — Resources (loaded as needed)

When the skill body references files from scripts/, references/, or assets/, the AI reads them on demand. This keeps the initial skill activation lean.

3.4 Organizing Large Skills

If a skill's instructions exceed 100-200 lines, split them:

writing-assistant/
├── SKILL.md                  # Core instructions + overview
├── references/
│   ├── style-guide.md        # Detailed style rules (loaded only when style is relevant)
│   ├── grammar-rules.md      # Grammar reference (loaded only for grammar tasks)
│   └── templates.md          # Output templates (loaded when generating)
├── scripts/
│   └── validate-markdown.js  # Validation script (run when checking output)
└── assets/
    └── template-letter.docx  # Template file (download when creating letters)

4. Creating a Skill — Step by Step

Step 1: Plan the Skill

Determine:

• Name: Short, lowercase, hyphenated (my-skill-name)
• Description: What + when (will be the AI's main trigger)
• Scope: How much instruction content is needed?
• Resources: Any scripts, templates, or references?

Step 2: Create the Development Directory

Create the skill directory in your current working directory for development:

mkdir -p <skill-name>

Directory name must match the planned name field.

Step 3: Write SKILL.md

Create {SKILL_DIR}/<skill-name>/SKILL.md with:

---
name: my-skill-name
description: What this skill does and when to use it
---
 
# Skill Instructions
 
Detailed instructions the AI should follow when this skill is activated.

Step 4: Add Optional Resources (if needed)

mkdir scripts/ references/ assets/

Step 5: Validate the Skill ⚠️ Required

Before installing, run the bundled validation script to check for errors. The script lives in this skill's own directory (scripts/validate-skill.mjs), relative to the resourceBase directory returned by the skill_learn tool. Run it from that directory:

node scripts/validate-skill.mjs <skill-name>

This checks 14 items: frontmatter format, name rules (lowercase, length, no leading/trailing hyphens), directory-name consistency, description constraints, optional fields, body length, and directory structure. All must pass before proceeding.

If validation fails, fix the reported issues and re-run until it passes.

Step 6: Install the Skill

After validation passes, move the skill directory to the system's skills directory:

mv <skill-name> {SKILL_DIR}/<skill-name>

Windows users: {SKILL_DIR} 已是完整绝对路径（如 C:\Users\<username>\<数据目录>\skills），直接使用即可，不要自行拼 ~。

Step 7: Automatic Registration

Once placed in {SKILL_DIR}/, the file watcher automatically detects the new SKILL.md and registers the skill within seconds — no manual action needed.

Step 8: Verify Registration

Use the read tool to confirm the skill is registered:

read({ path: "{SKILL_DIR}/my-skill-name/SKILL.md" })

This checks 14 items including frontmatter format, name rules, directory-name consistency, description constraints, optional fields, and directory structure. See scripts/validate-skill.mjs for details.

5. SKILL.md Body Writing Guidelines

5.1 Recommended Sections

5.2 Writing Philosophy

Explain the WHY, Not Just the WHAT

Today's LLMs are smart — they have good theory of mind and can go beyond rote instructions when given proper understanding. Instead of heavy-handed ALWAYS / MUST / NEVER, explain the reasoning:

## Good: Explain the WHY
Use the imperative verb form (e.g. "Generate a report") rather than descriptive
("This skill generates a report"). The imperative form makes the instruction
actionable — Claude will execute it directly rather than reading about it.
 
## Poor: Rigid MUST/ALWAYS
ALWAYS use imperative form. NEVER use descriptive form.

When you find yourself typing ALL CAPS or extremely rigid structures, that's a yellow flag — try to reframe and explain the why.

Keep It Lean

Every line in a skill is executed on every invocation. Remove things that aren't pulling their weight: