Skill: leonardo-lb/skill-craft (version 1.0.1)

--- name: skill-craft description: > Create, optimize, or update AgentSkills with evidence-based design. Two modes: (1) CREATE — build new skills from scratch with proven design patterns. (2) OPTIMIZE — diagnose and fix existing skills across 9 evidence-based dimensions: trigger precision, context efficiency, structured instructions, step decomposition, positive constraints, example design, verification, freedom calibration, progressive loading. Based on 25+ peer-reviewed papers (ACL/NeurIPS/EMNLP 2023-2025), Anthropic/Google/Microsoft official guides, and Claude Code/Cursor community practices. Trigger: "create skill", "optimize skill", "improve skill", "fix skill", "package skill", "skill not working", "skill design", "SKILL.md", "写技能", "优化技能", "skill type", "skill classification", "state management", "技能分类" --- # Skill Craft Build and optimize AI agent skills using evidence-based design principles. ## Two Modes of Operation **CREATE mode** — Build a new skill from scratch (Steps 1-6). **OPTIMIZE mode** — Diagnose and fix an existing skill (Step 7). For new skills, follow Steps 1-6 (Step 7 baked into Step 4). For existing skills needing improvement, jump to Step 7. --- ## Skill Classification Before creating or optimizing, classify the skill type — this determines design priorities. ### Nine Skill Types | Type | Code | Definition | Design Priority | |---|---|---|---| | Process Control | PROC | Sequential, phased workflows (brainstorming, planning) | D4 Steps → D7 Verify → D2 Efficiency | | Methodology | METH | Reusable methods with iron laws (TDD, debugging) | D4 Steps → D7 Verify → D5 Positive | | Tool Integration | TOOL | API/CLI wrappers (web-access, calculator) | D1 Description → D8 Freedom → D6 Examples | | Domain Knowledge | KNOW | Domain expertise and standards (design, mobile) | D9 Progressive → D2 Efficiency → D3 Structure | | Creative/Generative | GEN | Creative output with quality bars (prompt refinement) | D5 Positive → D8 Freedom → D6 Examples | | Document Generation | DOC | Structured document output (reports, wikis) | D4 Steps → D3 Structure → D7 Verify | | Orchestration | ORCH | Multi-agent/task coordination (parallel dispatch) | D4 Steps → D7 Verify → D6 Examples | | Meta-Skill | META | Skills about skills (this very skill) | D3 Structure → D9 Progressive → D5 Positive | | Quality Assurance | QA | Verification and review (code review, testing) | D7 Verify → D5 Positive → D4 Steps | See `references/skill-taxonomy.md` for per-type design templates, pitfalls, and the full classification decision tree. --- ## Skill Anatomy ``` skill-name/ ├── SKILL.md (required) — YAML frontmatter + Markdown instructions ├── scripts/ (optional) — Deterministic code (Python/Bash) ├── references/ (optional) — Detailed docs loaded on demand └── assets/ (optional) — Templates/images used in output ``` ### Three-Level Loading (Progressive Disclosure) | Level | Content | When Loaded | Size Target | |---|---|---|---| | 1 | `name` + `description` (frontmatter) | Always in context | ~100 words | | 2 | SKILL.md body | When skill triggers | < 500 lines, < 5k words | | 3 | `scripts/`, `references/`, `assets/` | On demand | Unlimited | **Why this matters:** Context window is the scarcest resource. Claude Code Issue #2544 (39👍) proves rules get ignored when SKILL.md is too long. CFPO research (Fudan/Microsoft, 2025) shows format+content joint optimization yields +5~38% improvement. ### What NOT to Include README.md, CHANGELOG.md, installation guides, user-facing docs. Only what the AI agent needs to do the job. ### State Management in Skills Some skills need state management — tracking progress across steps or sessions. Based on OpenSpec's DAG pattern and LangGraph's checkpoint system (see `references/state-machine-patterns.md`). **Does this skill need state management?** | Condition | Needs State? | Pattern | |---|---|---| | Multi-step workflow with dependencies between steps | YES | DAG + file existence checks | | Output of one step feeds into another | YES | Checkpoint pattern | | Each invocation is independent | NO | Stateless | | Free-form exploration or conversation | NO | Stateless | For state patterns (file existence, checkbox, YAML, DAG) and script integration, see `references/state-machine-patterns.md`. **Key principle:** Use deterministic checks (file exists, script output) rather than LLM judgment for state transitions. Research (arXiv:2511.07585) shows large models have only 12.5% output consistency — scripts are 8× more reliable. --- ## CREATE Mode: Steps 1-6 ### Skill Naming - Lowercase letters, digits, hyphens only. Under 64 chars. - Prefer short, verb-led: `pdf-editor`, `db-migrate`, `brand-styling`. - Namespace by tool when it helps triggering: `gh-address-comments`. ### Step 1: Understand with Concrete Examples Ask the user (one question at a time): 1. "What should this skill do?" 2. "Can you give 2-3 examples of how it would be used?" 3. "What would a user say that should trigger this skill?" 4. "Are there edge cases or error scenarios to handle?" ### Step 2: Plan Resources For each example from Step 1, identify reusable components: | If the task... | Add this resource | |---|---| | Rewrites the same code each time | `scripts/transform.py` | | Requires domain schemas/docs | `references/schema.md` | | Uses templates or boilerplate | `assets/template/` | ### Step 3: Initialize ```bash scripts/init_skill.py <skill-name> --path <output-dir> [--resources scripts,references,assets] [--examples] ``` ### Step 4: Write the Skill (with Built-in Optimization) This step creates SKILL.md following all 9 optimization dimensions from the start. Write using imperative form. #### 4a. Write Frontmatter (D1: Trigger Precision) The `description` field is the **only content always loaded**. It determines whether the skill triggers at all. Issue #9716 (69👍) documents skills ignored because descriptions lacked trigger phrases. **Three-part formula:** ```yaml # BAD — vague, no triggers description: Helps with PDF operations # GOOD — capabilities + trigger scenarios + keywords description: > Create, edit, and analyze PDF documents with form filling, text extraction, and page manipulation. Use when: (1) Creating PDFs, (2) Extracting text or form data, (3) Rotating/merging pages, (4) Converting PDFs to images. Trigger: "pdf", "rotate pdf", "merge pdf", "extract text", "fill form" ``` Only `name` and `description` fields allowed in frontmatter. #### 4b. Write Body Sections (D3: Structure) Separate content types with Markdown headings: ```markdown ## Workflow [Numbered steps — see D4 below] ## Constraints [Specific, measurable rules — see D5 below] ## Examples [Concrete user request → agent behavior — see D6 below] ## Verification [Success criteria and how to check — see D7 below] ## Resources [Links to references/ — see D9 below] ``` #### 4c. Write Workflows (D4: Step Decomposition) Research (CoM, ACL 2025; Watch Every Step, EMNLP 2024) proves numbered steps with decision points outperform free-form descriptions. ```markdown # BAD — paragraph description Process the document by extracting key fields and validating them against the schema, then generating a report. # GOOD — numbered steps with branching ## Workflow 1. **Extract**: Read document, extract fields in `references/schema.md` 2. **Validate**: Check each field against schema rules - If valid → proceed to step 3 - If invalid → report specific errors, suggest fixes, STOP 3. **Transform**: Run `scripts/transform.py --input <extracted.json>` 4. **Report**: Generate output using `assets/report-template.md` 5. **Verify**: Confirm output contains all required sections ``` #### 4d. Write Constraints (D5: Positive Framing) Inverse IFEval (ByteDance, 2025, 1012 test cases) proves positive constraints are followed significantly more reliably. Constraint Decomposition (2025): 41.2% → 73.8% accuracy when constraints are decomposed. ```markdown # BAD — negative constraints Don't write functions longer than 20 lines. Never modify files outside the project. Avoid using deprecated APIs. # GOOD — positive constraints with specifics Keep every function under 20 lines. Extract helpers for complex logic. Only modify files within the target directory specified by the user. Use APIs from the approved list in `references/api-versions.md`. ``` For safety-critical rules, keep negative framing but pair with positive alternative: ```markdown CRITICAL: Only delete files after explicit user confirmation. (safety negative) Prefer creating new files over modifying existing ones when possible. (positive alternative) ``` #### 4e. Write Examples (D6: Example Design) Cursor official data: Good/Bad examples make rules **~3x more effective**. ACL 2025: 1-shot achieves best flexibility/structure balance. ```markdown # BAD — abstract Use the transform script to convert between formats. # GOOD — concrete "user request → agent behavior" ## Examples ### User: "Convert this CSV to JSON" → 1. Run `scripts/transform.py data.csv --output data.json` → 2. Verify JSON has keys: `name`, `date`, `amount` → 3. Report: "Converted 150 records from CSV to JSON" ### User: "The output has wrong date format" → 1. Check current date format in output → 2. Add `--date-format ISO8601` flag → 3. Re-run and verify dates match `YYYY-MM-DD` ``` Include 1-3 examples in SKILL.md. For more, create `references/examples.md`. #### 4f. Write Verification (D7: Verification) Issue #42796 (1781👍): Analysis of 6,852 sessions shows agent Read:Edit ratio dropped 70%, causing "rush to completion" errors. Explicit verification steps prevent this. ```markdown ## Verification After completing the workflow: 1. **Output exists**: Confirm the output file was created 2. **Schema valid**: Run `scripts/validate.py output.json` 3. **Content complete**: Output has all required sections 4. **No regressions**: Run `npm test` If any check fails → diagnose, fix, re-verify. ``` #### 4g. Calibrate Freedom (D8: Freedom Calibration) Match specificity to task fragility (NeurIPS 2024: task type determines optimal approach): | Task Fragility | Freedom Level | How to Write | |---|---|---| | **Fragile** (deployment, DB migration, security) | Low — specific scripts + numbered steps | "Run `scripts/backup.sh` then `scripts/migrate.py --dry-run`" | | **Moderate** (API calls, code generation) | Medium — preferred patterns + alternatives | "Prefer pdfplumber. For encrypted PDFs, use PyMuPDF instead." | | **Open** (writing, brainstorming, design) | High — principles + examples | "Match brand voice in `references/brand-voice.md`. Target 500-800 words." | #### 4h. Manage Context (D2 + D9: Efficiency + Progressive Loading) **D2 — Token economy:** Every line must earn its cost. Delete what the model already knows. One example beats three paragraphs. **D9 — Progressive loading:** Keep SKILL.md < 500 lines. Move details to `references/` with explicit "when to read" pointers: ```markdown ## Resources - **Advanced schemas**: See [SCHEMAS.md](references/schemas.md) when user provides non-standard input - **Error handling**: See [TROUBLESHOOTING.md](references/troubleshooting.md) when scripts fail - **API reference**: See [API.md](references/api.md) when working with specific endpoints ``` Keep references one level deep (no nested references). Files > 100 lines: include table of contents at top. ### Step 5: Package ```bash scripts/package_skill.py <path/to/skill-folder> [output-dir] ``` Automatically validates structure, frontmatter, naming, and description quality before packaging. ### Step 6: Iterate 1. Use the skill on real tasks 2. Notice struggles or inefficiencies 3. Apply Step 7 (Optimize) to systematically improve --- ## OPTIMIZE Mode: Step 7 Use when an existing skill needs improvement. Read `references/skill-optimization.md` for detailed before/after examples and `references/evidence-database.md` for research sources. ### 7.1 Diagnose Read the full skill. Answer each diagnostic question: | ID | Dimension | Diagnostic Question | Impact if Failing | |---|-----------|-------------------|---| | D1 | **Description** | Seeing ONLY name+description, would an AI trigger this skill correctly? | Skill never triggers or triggers incorrectly | | D2 | **Efficiency** | Does every line earn its token cost? | Context bloat degrades all loaded skills | | D3 | **Structure** | Are workflows/constraints/examples visually separated? | Instructions blur together, compliance drops | | D4 | **Steps** | Are complex processes numbered with decision points? | Agent improvises, misses critical sequence | | D5 | **Positive** | Are rules "do X" not "don't do Y"? | Negative constraints poorly followed (IFEval data) | | D6 | **Examples** | Is there a concrete "user request → behavior" example? | Agent guesses expected behavior | | D7 | **Verification** | Does the skill define how to check output? | Agent "rushes to completion" (Issue #42796) | | D8 | **Freedom** | Is specificity matched to task fragility? | Over/under-constrained output | | D9 | **Progressive** | Is SKILL.md lean with details in references/? | All content loaded even when not needed | Run `scripts/quick_validate.py <skill-path>` for automated hints on D1, D2, D5, D6, D7, D9. ### 7.2 Prioritize by Skill Type Focus on the dimensions that matter most for this skill type: | Skill Type | Fix These First | Why | |---|---|---| | **Workflow** (sequential process) | D4 Steps → D7 Verify → D2 Efficiency | Sequence errors are catastrophic; verification catches them | | **Tool Integration** (API/CLI wrapper) | D1 Description → D8 Freedom → D6 Examples | Must trigger on right tool names; right specificity level | | **Knowledge/Reference** (schemas, policies) | D9 Progressive → D2 Efficiency → D3 Structure | Massive content needs aggressive context management | | **Creative/Generative** (writing, design) | D5 Positive → D8 Freedom → D6 Examples | Needs principles not rigid rules; examples set quality bar | | **Debugging/Analysis** (troubleshooting) | D4 Steps → D7 Verify → D5 Positive | Must follow diagnostic sequence; verify fix actually works | | **Document Generation** (reports, analysis) | D4 Steps → D3 Structure → D7 Verify | Output structure must be fixed; verification ensures completeness | | **Orchestration** (multi-agent, parallel tasks) | D4 Steps → D7 Verify → D6 Examples | Dispatch logic must be precise; sub-agent prompts need templates | | **Meta-Skill** (skills about skills) | D3 Structure → D9 Progressive → D5 Positive | Complex logic needs clean structure; must avoid recursive bloat | | **Quality Assurance** (review, testing, verification) | D7 Verify → D5 Positive → D4 Steps | Verification is the core function; positive framing prevents over-flagging | ### 7.3 Apply Dimension Fixes For each failing dimension, apply the fix. See `references/skill-optimization.md` for detailed before/after examples. **D1 — Rewrite description** with 3-part formula: (1) capabilities, (2) trigger scenarios, (3) keywords. **D2 — Audit every line**: delete known knowledge, compress with examples, move details to `references/`. Target < 500 lines. **D3 — Add visual hierarchy**: Markdown `##`/`###` headings for each content type. `---` between major blocks. **D4 — Number the steps**: Convert paragraphs to numbered lists. Add `if/else` decision points. Add error handling. **D5 — Flip to positive**: Convert "don't X" → "do Y". For safety rules, keep negative but add positive alternative. **D6 — Add examples**: 1-3 concrete "User: ... → Agent behavior: ..." examples. Realistic inputs, not placeholders. **D7 — Add verification**: Explicit success criteria at workflow end. What to check, how to check, what if it fails. **D8 — Calibrate freedom**: Fragile tasks → numbered steps/scripts. Creative tasks → principles/examples. **D9 — Move to references**: Anything beyond core workflow → `references/`. Each link says WHEN to read it. ### 7.4 Scan for Anti-Patterns | Anti-Pattern | Symptom | Fix | |---|---|---| | **Kitchen Sink** | SKILL.md > 500 lines | Split into focused skills or references/ | | **Invisible Skill** | No trigger phrases in description | Rewrite with Trigger: keywords | | **Vague Guardrails** | "Write clean code", "Be helpful" | Replace with specific, measurable rules | | **Negative-Only** | Mostly "don't" / "never" rules | Convert to positive framing | | **Missing Exit** | No success/failure criteria | Add verification section | | **Flat Wall of Text** | No headings or visual breaks | Add ## / ### headings | | **Zombie References** | Files exist but unlinked from SKILL.md | Add explicit "See X when Y" pointers | | **Example-Free** | No concrete examples | Add 1-3 user request → behavior examples | | **Stateless Multi-Step** | Multi-step workflow with no state tracking | Add file existence checks or checkbox tracking | | **LLM-as-State-Oracle** | Using LLM to determine workflow state instead of scripts | Replace with deterministic checks (file exists, script output) | | **Missing Script Integration** | References to scripts/ but no scripts/ directory | Create the scripts or remove references | ### 7.5 Validate After Optimization 1. Run `scripts/quick_validate.py <skill-path>` — structure + optimization hints 2. Re-read end-to-end — does each section serve a clear purpose? 3. Count lines — SKILL.md body still < 500? 4. Check all reference links — valid? Explain when to read? --- ## Reference Files | File | When to Read | |---|---| | `references/skill-optimization.md` | Optimizing a skill — detailed before/after examples for all 9 dimensions | | `references/evidence-database.md` | Checking research evidence — papers, data, community issues | | `references/skill-taxonomy.md` | Classifying skill types — 9 types, design templates, user need routing | | `references/state-machine-patterns.md` | Adding state management — DAG patterns, checkpoint design, script-driven workflows | ## Scripts | Script | Purpose | |---|---| | `scripts/init_skill.py` | Create new skill directory with optimized template | | `scripts/package_skill.py` | Validate + package skill into .skill file | | `scripts/quick_validate.py` | Validate structure + check optimization hints |

path: scripts/init_skill.py
content: #!/usr/bin/env python3
"""
Skill Initializer - Creates a new skill from template

Usage:
    init_skill.py <skill-name> --path <path> [--resources scripts,references,assets] [--examples]

Examples:
    init_skill.py my-new-skill --path skills/public
    init_skill.py my-new-skill --path skills/public --resources scripts,references
    init_skill.py my-api-helper --path skills/private --resources scripts --examples
    init_skill.py custom-skill --path /custom/location
"""

import argparse
import re
import sys
from pathlib import Path

MAX_SKILL_NAME_LENGTH = 64
ALLOWED_RESOURCES = {"scripts", "references", "assets"}

SKILL_TEMPLATE = """---
name: {skill_name}
description: >
  [TODO: Follow this 3-part formula:
  (1) Capabilities: what this skill does
  (2) Trigger scenarios: numbered list of when to use it  
  (3) Keywords: specific phrases users might say
  Example: "PDF creation and editing with form support. Use when: (1) Creating PDFs, (2) Filling forms, (3) Extracting text. Trigger: 'pdf', 'fill form', 'extract text'"]
---

# {skill_title}

## Overview

[TODO: 1-2 sentences explaining what this skill enables]

## Examples

[TODO: Add 1-3 concrete examples showing realistic user requests and expected agent behavior.
Format:
### User: "realistic request here"
→ 1. First action
→ 2. Second action  
→ 3. Expected output]

## Structuring This Skill

[TODO: Choose the structure that best fits this skill's purpose. Common patterns:

**1. Workflow-Based** (best for sequential processes)
- Works well when there are clear step-by-step procedures
- Example: DOCX skill with "Workflow Decision Tree" -> "Reading" -> "Creating" -> "Editing"
- Structure: ## Overview -> ## Workflow Decision Tree -> ## Step 1 -> ## Step 2...

**2. Task-Based** (best for tool collections)
- Works well when the skill offers different operations/capabilities
- Example: PDF skill with "Quick Start" -> "Merge PDFs" -> "Split PDFs" -> "Extract Text"
- Structure: ## Overview -> ## Quick Start -> ## Task Category 1 -> ## Task Category 2...

**3. Reference/Guidelines** (best for standards or specifications)
- Works well for brand guidelines, coding standards, or requirements
- Example: Brand styling with "Brand Guidelines" -> "Colors" -> "Typography" -> "Features"
- Structure: ## Overview -> ## Guidelines -> ## Specifications -> ## Usage...

**4. Capabilities-Based** (best for integrated systems)
- Works well when the skill provides multiple interrelated features
- Example: Product Management with "Core Capabilities" -> numbered capability list
- Structure: ## Overview -> ## Core Capabilities -> ### 1. Feature -> ### 2. Feature...

Patterns can be mixed and matched as needed. Most skills combine patterns (e.g., start with task-based, add workflow for complex operations).

Delete this entire "Structuring This Skill" section when done - it's just guidance.]

## [TODO: Replace with the first main section based on chosen structure]

[TODO: Add content here. See examples in existing skills:
- Code samples for technical skills
- Decision trees for complex workflows
- Concrete examples with realistic user requests
- References to scripts/templates/references as needed]

## Verification

[TODO: Add verification criteria. How does the agent know the task is complete?
- What should be checked?
- What commands to run?
- What the expected result looks like]

## Resources (optional)

Create only the resource directories this skill actually needs. Delete this section if no resources are required.

### scripts/
Executable code (Python/Bash/etc.) that can be run directly to perform specific operations.

**Examples from other skills:**
- PDF skill: `fill_fillable_fields.py`, `extract_form_field_info.py` - utilities for PDF manipulation
- DOCX skill: `document.py`, `utilities.py` - Python modules for document processing

**Appropriate for:** Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations.

**Note:** Scripts may be executed without loading into context, but can still be read by Codex for patching or environment adjustments.

### references/
Documentation and reference material intended to be loaded into context to inform Codex's process and thinking.

**Examples from other skills:**
- Product management: `communication.md`, `context_building.md` - detailed workflow guides
- BigQuery: API reference documentation and query examples
- Finance: Schema documentation, company policies

**Appropriate for:** In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information that Codex should reference while working.

### assets/
Files not intended to be loaded into context, but rather used within the output Codex produces.

**Examples from other skills:**
- Brand styling: PowerPoint template files (.pptx), logo files
- Frontend builder: HTML/React boilerplate project directories
- Typography: Font files (.ttf, .woff2)

**Appropriate for:** Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output.

---

**Not every skill requires all three types of resources.**
"""

EXAMPLE_SCRIPT = '''#!/usr/bin/env python3
"""
Example helper script for {skill_name}

This is a placeholder script that can be executed directly.
Replace with actual implementation or delete if not needed.

Example real scripts from other skills:
- pdf/scripts/fill_fillable_fields.py - Fills PDF form fields
- pdf/scripts/convert_pdf_to_images.py - Converts PDF pages to images
"""

def main():
    print("This is an example script for {skill_name}")
    # TODO: Add actual script logic here
    # This could be data processing, file conversion, API calls, etc.

if __name__ == "__main__":
    main()
'''

EXAMPLE_REFERENCE = """# Reference Documentation for {skill_title}

This is a placeholder for detailed reference documentation.
Replace with actual reference content or delete if not needed.

Example real reference docs from other skills:
- product-management/references/communication.md - Comprehensive guide for status updates
- product-management/references/context_building.md - Deep-dive on gathering context
- bigquery/references/ - API references and query examples

## When Reference Docs Are Useful

Reference docs are ideal for:
- Comprehensive API documentation
- Detailed workflow guides
- Complex multi-step processes
- Information too lengthy for main SKILL.md
- Content that's only needed for specific use cases

## Structure Suggestions

### API Reference Example
- Overview
- Authentication
- Endpoints with examples
- Error codes
- Rate limits

### Workflow Guide Example
- Prerequisites
- Step-by-step instructions
- Common patterns
- Troubleshooting
- Best practices
"""

EXAMPLE_ASSET = """# Example Asset File

This placeholder represents where asset files would be stored.
Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed.

Asset files are NOT intended to be loaded into context, but rather used within
the output Codex produces.

Example asset files from other skills:
- Brand guidelines: logo.png, slides_template.pptx
- Frontend builder: hello-world/ directory with HTML/React boilerplate
- Typography: custom-font.ttf, font-family.woff2
- Data: sample_data.csv, test_dataset.json

## Common Asset Types

- Templates: .pptx, .docx, boilerplate directories
- Images: .png, .jpg, .svg, .gif
- Fonts: .ttf, .otf, .woff, .woff2
- Boilerplate code: Project directories, starter files
- Icons: .ico, .svg
- Data files: .csv, .json, .xml, .yaml

Note: This is a text placeholder. Actual assets can be any file type.
"""


def normalize_skill_name(skill_name):
    """Normalize a skill name to lowercase hyphen-case."""
    normalized = skill_name.strip().lower()
    normalized = re.sub(r"[^a-z0-9]+", "-", normalized)
    normalized = normalized.strip("-")
    normalized = re.sub(r"-{2,}", "-", normalized)
    return normalized


def title_case_skill_name(skill_name):
    """Convert hyphenated skill name to Title Case for display."""
    return " ".join(word.capitalize() for word in skill_name.split("-"))


def parse_resources(raw_resources):
    if not raw_resources:
        return []
    resources = [item.strip() for item in raw_resources.split(",") if item.strip()]
    invalid = sorted({item for item in resources if item not in ALLOWED_RESOURCES})
    if invalid:
        allowed = ", ".join(sorted(ALLOWED_RESOURCES))
        print(f"[ERROR] Unknown resource type(s): {', '.join(invalid)}")
        print(f"   Allowed: {allowed}")
        sys.exit(1)
    deduped = []
    seen = set()
    for resource in resources:
        if resource not in seen:
            deduped.append(resource)
            seen.add(resource)
    return deduped


def create_resource_dirs(
    skill_dir, skill_name, skill_title, resources, include_examples
):
    for resource in resources:
        resource_dir = skill_dir / resource
        resource_dir.mkdir(exist_ok=True)
        if resource == "scripts":
            if include_examples:
                example_script = resource_dir / "example.py"
                example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name))
                example_script.chmod(0o755)
                print("[OK] Created scripts/example.py")
            else:
                print("[OK] Created scripts/")
        elif resource == "references":
            if include_examples:
                example_reference = resource_dir / "api_reference.md"
                example_reference.write_text(
                    EXAMPLE_REFERENCE.format(skill_title=skill_title)
                )
                print("[OK] Created references/api_reference.md")
            else:
                print("[OK] Created references/")
        elif resource == "assets":
            if include_examples:
                example_asset = resource_dir / "example_asset.txt"
                example_asset.write_text(EXAMPLE_ASSET)
                print("[OK] Created assets/example_asset.txt")
            else:
                print("[OK] Created assets/")


def init_skill(skill_name, path, resources, include_examples):
    """
    Initialize a new skill directory with template SKILL.md.

    Args:
        skill_name: Name of the skill
        path: Path where the skill directory should be created
        resources: Resource directories to create
        include_examples: Whether to create example files in resource directories

    Returns:
        Path to created skill directory, or None if error
    """
    # Determine skill directory path
    skill_dir = Path(path).resolve() / skill_name

    # Check if directory already exists
    if skill_dir.exists():
        print(f"[ERROR] Skill directory already exists: {skill_dir}")
        return None

    # Create skill directory
    try:
        skill_dir.mkdir(parents=True, exist_ok=False)
        print(f"[OK] Created skill directory: {skill_dir}")
    except Exception as e:
        print(f"[ERROR] Error creating directory: {e}")
        return None

    # Create SKILL.md from template
    skill_title = title_case_skill_name(skill_name)
    skill_content = SKILL_TEMPLATE.format(
        skill_name=skill_name, skill_title=skill_title
    )

    skill_md_path = skill_dir / "SKILL.md"
    try:
        skill_md_path.write_text(skill_content)
        print("[OK] Created SKILL.md")
    except Exception as e:
        print(f"[ERROR] Error creating SKILL.md: {e}")
        return None

    # Create resource directories if requested
    if resources:
        try:
            create_resource_dirs(
                skill_dir, skill_name, skill_title, resources, include_examples
            )
        except Exception as e:
            print(f"[ERROR] Error creating resource directories: {e}")
            return None

    # Print next steps
    print(f"\n[OK] Skill '{skill_name}' initialized successfully at {skill_dir}")
    print("\nNext steps:")
    print("1. Edit SKILL.md to complete the TODO items and update the description")
    if resources:
        if include_examples:
            print(
                "2. Customize or delete the example files in scripts/, references/, and assets/"
            )
        else:
            print("2. Add resources to scripts/, references/, and assets/ as needed")
    else:
        print(
            "2. Create resource directories only if needed (scripts/, references/, assets/)"
        )
    print("3. Run the validator when ready to check the skill structure")

    return skill_dir


def main():
    parser = argparse.ArgumentParser(
        description="Create a new skill directory with a SKILL.md template.",
    )
    parser.add_argument("skill_name", help="Skill name (normalized to hyphen-case)")
    parser.add_argument("--path", required=True, help="Output directory for the skill")
    parser.add_argument(
        "--resources",
        default="",
        help="Comma-separated list: scripts,references,assets",
    )
    parser.add_argument(
        "--examples",
        action="store_true",
        help="Create example files inside the selected resource directories",
    )
    args = parser.parse_args()

    raw_skill_name = args.skill_name
    skill_name = normalize_skill_name(raw_skill_name)
    if not skill_name:
        print("[ERROR] Skill name must include at least one letter or digit.")
        sys.exit(1)
    if len(skill_name) > MAX_SKILL_NAME_LENGTH:
        print(
            f"[ERROR] Skill name '{skill_name}' is too long ({len(skill_name)} characters). "
            f"Maximum is {MAX_SKILL_NAME_LENGTH} characters."
        )
        sys.exit(1)
    if skill_name != raw_skill_name:
        print(f"Note: Normalized skill name from '{raw_skill_name}' to '{skill_name}'.")

    resources = parse_resources(args.resources)
    if args.examples and not resources:
        print("[ERROR] --examples requires --resources to be set.")
        sys.exit(1)

    path = args.path

    print(f"Initializing skill: {skill_name}")
    print(f"   Location: {path}")
    if resources:
        print(f"   Resources: {', '.join(resources)}")
        if args.examples:
            print("   Examples: enabled")
    else:
        print("   Resources: none (create as needed)")
    print()

    result = init_skill(skill_name, path, resources, args.examples)

    if result:
        sys.exit(0)
    else:
        sys.exit(1)


if __name__ == "__main__":
    main()


path: scripts/package_skill.py
content: #!/usr/bin/env python3
"""
Skill Packager - Creates a distributable .skill file of a skill folder

Usage:
    python utils/package_skill.py <path/to/skill-folder> [output-directory]

Example:
    python utils/package_skill.py skills/public/my-skill
    python utils/package_skill.py skills/public/my-skill ./dist
"""

import sys
import zipfile
from pathlib import Path

from quick_validate import validate_skill


def package_skill(skill_path, output_dir=None):
    """
    Package a skill folder into a .skill file.

    Args:
        skill_path: Path to the skill folder
        output_dir: Optional output directory for the .skill file (defaults to current directory)

    Returns:
        Path to the created .skill file, or None if error
    """
    skill_path = Path(skill_path).resolve()

    # Validate skill folder exists
    if not skill_path.exists():
        print(f"[ERROR] Skill folder not found: {skill_path}")
        return None

    if not skill_path.is_dir():
        print(f"[ERROR] Path is not a directory: {skill_path}")
        return None

    # Validate SKILL.md exists
    skill_md = skill_path / "SKILL.md"
    if not skill_md.exists():
        print(f"[ERROR] SKILL.md not found in {skill_path}")
        return None

    # Run validation before packaging
    print("Validating skill...")
    valid, message = validate_skill(skill_path)
    if not valid:
        print(f"[ERROR] Validation failed: {message}")
        print("   Please fix the validation errors before packaging.")
        return None
    print(f"[OK] {message}\n")

    # Determine output location
    skill_name = skill_path.name
    if output_dir:
        output_path = Path(output_dir).resolve()
        output_path.mkdir(parents=True, exist_ok=True)
    else:
        output_path = Path.cwd()

    skill_filename = output_path / f"{skill_name}.skill"

    # Create the .skill file (zip format)
    try:
        with zipfile.ZipFile(skill_filename, "w", zipfile.ZIP_DEFLATED) as zipf:
            # Walk through the skill directory
            for file_path in skill_path.rglob("*"):
                if file_path.is_file():
                    # Calculate the relative path within the zip
                    arcname = file_path.relative_to(skill_path.parent)
                    zipf.write(file_path, arcname)
                    print(f"  Added: {arcname}")

        print(f"\n[OK] Successfully packaged skill to: {skill_filename}")
        return skill_filename

    except Exception as e:
        print(f"[ERROR] Error creating .skill file: {e}")
        return None


def main():
    if len(sys.argv) < 2:
        print("Usage: python utils/package_skill.py <path/to/skill-folder> [output-directory]")
        print("\nExample:")
        print("  python utils/package_skill.py skills/public/my-skill")
        print("  python utils/package_skill.py skills/public/my-skill ./dist")
        sys.exit(1)

    skill_path = sys.argv[1]
    output_dir = sys.argv[2] if len(sys.argv) > 2 else None

    print(f"Packaging skill: {skill_path}")
    if output_dir:
        print(f"   Output directory: {output_dir}")
    print()

    result = package_skill(skill_path, output_dir)

    if result:
        sys.exit(0)
    else:
        sys.exit(1)


if __name__ == "__main__":
    main()


path: scripts/quick_validate.py
content: #!/usr/bin/env python3
"""
Quick validation script for skills - minimal version
"""

import re
import sys
from pathlib import Path

import yaml

MAX_SKILL_NAME_LENGTH = 64


def validate_skill(skill_path):
    """Basic validation of a skill"""
    skill_path = Path(skill_path)

    skill_md = skill_path / "SKILL.md"
    if not skill_md.exists():
        return False, "SKILL.md not found"

    content = skill_md.read_text()
    if not content.startswith("---"):
        return False, "No YAML frontmatter found"

    match = re.match(r"^---\n(.*?)\n---", content, re.DOTALL)
    if not match:
        return False, "Invalid frontmatter format"

    frontmatter_text = match.group(1)

    try:
        frontmatter = yaml.safe_load(frontmatter_text)
        if not isinstance(frontmatter, dict):
            return False, "Frontmatter must be a YAML dictionary"
    except yaml.YAMLError as e:
        return False, f"Invalid YAML in frontmatter: {e}"

    allowed_properties = {"name", "description", "license", "allowed-tools", "metadata"}

    unexpected_keys = set(frontmatter.keys()) - allowed_properties
    if unexpected_keys:
        allowed = ", ".join(sorted(allowed_properties))
        unexpected = ", ".join(sorted(unexpected_keys))
        return (
            False,
            f"Unexpected key(s) in SKILL.md frontmatter: {unexpected}. Allowed properties are: {allowed}",
        )

    if "name" not in frontmatter:
        return False, "Missing 'name' in frontmatter"
    if "description" not in frontmatter:
        return False, "Missing 'description' in frontmatter"

    name = frontmatter.get("name", "")
    if not isinstance(name, str):
        return False, f"Name must be a string, got {type(name).__name__}"
    name = name.strip()
    if name:
        if not re.match(r"^[a-z0-9-]+$", name):
            return (
                False,
                f"Name '{name}' should be hyphen-case (lowercase letters, digits, and hyphens only)",
            )
        if name.startswith("-") or name.endswith("-") or "--" in name:
            return (
                False,
                f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens",
            )
        if len(name) > MAX_SKILL_NAME_LENGTH:
            return (
                False,
                f"Name is too long ({len(name)} characters). "
                f"Maximum is {MAX_SKILL_NAME_LENGTH} characters.",
            )

    description = frontmatter.get("description", "")
    if not isinstance(description, str):
        return False, f"Description must be a string, got {type(description).__name__}"
    description = description.strip()
    if description:
        if "<" in description or ">" in description:
            return False, "Description cannot contain angle brackets (< or >)"
        if len(description) > 1024:
            return (
                False,
                f"Description is too long ({len(description)} characters). Maximum is 1024 characters.",
            )

    return True, "Skill is valid!"


def check_optimization_hints(skill_path):
    """Check skill for optimization opportunities. Returns list of warnings."""
    skill_path = Path(skill_path)
    warnings = []

    skill_md = skill_path / "SKILL.md"
    if not skill_md.exists():
        return warnings

    content = skill_md.read_text()

    # --- D1: Description quality ---
    match = re.match(r"^---\n(.*?)\n---", content, re.DOTALL)
    if match:
        try:
            frontmatter = yaml.safe_load(match.group(1))
            if isinstance(frontmatter, dict):
                desc = str(frontmatter.get("description", ""))
                if not re.search(r"Trigger:|Use when", desc, re.IGNORECASE):
                    warnings.append(
                        "D1: Description may lack trigger phrases — "
                        "consider adding 'Trigger:' or 'Use when' keywords"
                    )
        except yaml.YAMLError:
            pass

    # --- D2: Context efficiency (line count) ---
    line_count = content.count("\n")
    if line_count > 500:
        warnings.append(
            f"D2: SKILL.md is {line_count} lines (over 500 limit) — "
            "MUST split into references/"
        )
    elif line_count > 300:
        warnings.append(
            f"D2: SKILL.md is {line_count} lines — "
            "consider splitting content into references/"
        )

    # --- D6: Examples ---
    example_markers = r"Example|示例|### User:"
    if not re.search(example_markers, content):
        warnings.append(
            "D6: No examples found — consider adding at least 1 concrete example"
        )

    # --- D5: Positive constraints ---
    negative_patterns = [
        r"\bdon't\b",
        r"\bdo not\b",
        r"\bnever\b",
        r"\bavoid\b",
    ]
    negative_count = 0
    for pat in negative_patterns:
        negative_count += len(re.findall(pat, content, re.IGNORECASE))
    if negative_count > 3:
        warnings.append(
            f"D5: Found {negative_count} negative constraints — "
            "consider converting to positive framing"
        )

    # --- D7: Verification keywords ---
    verification_keywords = r"verify|check|validate|confirm|确保|验证"
    if not re.search(verification_keywords, content, re.IGNORECASE):
        warnings.append(
            "D7: No verification keywords found — consider adding verification steps"
        )

    # --- D9: Progressive loading ---
    references_dir = skill_path / "references"
    if not references_dir.is_dir() and line_count > 200:
        warnings.append(
            f"D9: SKILL.md is {line_count} lines with no references/ — "
            "consider creating references/ for details"
        )

    # --- D10: Script references without scripts/ directory ---
    scripts_mentioned = bool(re.search(r"scripts/", content))
    scripts_dir = (skill_path / "scripts").is_dir()
    if scripts_mentioned and not scripts_dir:
        warnings.append(
            "D10: SKILL.md references scripts/ but scripts/ directory does not exist"
        )

    # --- D11: Script executability ---
    if scripts_dir:
        import os

        for script_file in (skill_path / "scripts").iterdir():
            if script_file.is_file() and not os.access(script_file, os.X_OK):
                warnings.append(
                    f"D11: Script '{script_file.name}' is not executable — "
                    "run: chmod +x scripts/{script_file.name}"
                )

    # --- D12: State management awareness ---
    # Check if multi-step workflow lacks state tracking
    has_numbered_steps = bool(re.search(r"^\d+\.\s+\*\*", content, re.MULTILINE))
    has_state_tracking = bool(
        re.search(
            r"requires|checkpoint|state|checkbox|\[.\]|\.state\.|phase:",
            content,
            re.IGNORECASE,
        )
    )
    if has_numbered_steps and not has_state_tracking and line_count > 150:
        warnings.append(
            "D12: Multi-step workflow detected without state tracking — "
            "consider adding file existence checks, checkboxes, or state file"
        )

    return warnings


if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("Usage: python quick_validate.py <skill_directory>")
        sys.exit(1)

    valid, message = validate_skill(sys.argv[1])
    print(message)

    if valid:
        hints = check_optimization_hints(sys.argv[1])
        if hints:
            print("\nOptimization hints:")
            for hint in hints:
                print(f"  ⚠ {hint}")

    sys.exit(0 if valid else 1)


path: references/state-machine-patterns.md
content: # State Machine Patterns for Skills

> Design patterns for adding state management to AI agent skills.
> Sources: OpenSpec (DAG + artifact graph), LangGraph (StateGraph + checkpoint), Source Code Agent (arXiv:2508.02721), Compiled AI (arXiv:2604.05150), Claude Code Hooks (25+ events), MetaGPT (Code=SOP), smolagents (Code-as-Action).

## When to Add State Management

| Condition | Needs State? | Why |
|---|---|---|
| Multi-step workflow with step dependencies | YES | Step B needs output from Step A |
| Output feeds into next invocation | YES | Resume from checkpoint |
| Single-shot tool call | NO | Stateless is simpler |
| Free-form exploration / brainstorming | NO | No fixed path to track |
| Verification reads current state | Light | Reads state but doesn't advance it |

**Key insight:** Research (arXiv:2511.07585) shows large models (GPT-OSS-120B) have only **12.5% output consistency** across runs. Deterministic state checks (file existence, script output) are **8x more reliable** than LLM self-assessment. Small models (8B) at T=0.0 achieve 100% consistency.

## 4 State Patterns (Simple to Complex)

### Pattern 1: File Existence Checks (Simplest)

**Concept:** Each step generates a file. File exists = step done. Zero config, Git-friendly, human-readable.

**How it works:**
```javascript
// OpenSpec's actual implementation (~15 lines)
function isArtifactComplete(generates, changeDir) {
    if (isGlobPattern(generates)) {
        return hasGlobMatches(path.join(changeDir, generates));
    }
    return fs.existsSync(path.join(changeDir, generates));
}
```

**Workflow example:**
```markdown
## Workflow
1. Research -> writes `output/research.md`
2. Plan -> requires `output/research.md` -> writes `output/plan.md`
3. Implement -> requires `output/plan.md` -> writes code files
4. Verify -> requires implementation -> runs tests
```

**SKILL.md integration:**
```markdown
## State Detection
Before starting, check which phase to resume:
- If `output/research.md` exists AND `output/plan.md` does NOT -> start at Plan
- If `output/plan.md` exists AND no code files -> start at Implement
- If code exists -> start at Verify
```

**Advantages:** Zero infrastructure, Git-trackable, LLM can read/write directly.
**Disadvantages:** No metadata (timestamps, error info), glob patterns need care.

### Pattern 2: Checkbox Tracking (Medium)

**Concept:** Markdown checkboxes track sub-task progress. LLM reads checkboxes to know what's done, marks them complete as it progresses.

**OpenSpec's implementation (Apply phase):**
```javascript
// State detection from tasks.md checkboxes
if (remaining === 0 && total > 0) state = 'all_done';
else if (total === 0) state = 'blocked';  // no tasks defined
else state = 'ready';                       // work to do
```

**Example:**
```markdown
## Tasks
- [x] 1.1 Extract fields from schema
- [x] 1.2 Validate against rules
- [ ] 2.1 Generate output report
- [ ] 2.2 Run integration tests
```

**SKILL.md integration:**
```markdown
## Progress Tracking
1. Read `tasks.md` to find unchecked items
2. Work through the next unchecked task
3. Mark it complete: `- [x]` when done
4. Repeat until all items are checked
5. When all checked -> move to next phase
```

**Advantages:** Human-readable, Git-diffable, natural LLM interaction.
**Disadvantages:** No parallel tracking, checkbox parsing can be fragile.

### Pattern 3: YAML State File (Complex)

**Concept:** Explicit YAML file records workflow state, metadata, and context. Supports richer information than file existence alone.

**Example:**
```yaml
# .skill-state.yaml
phase: design
completed: [research, plan]
blocked: [implement]
metadata:
  started: 2026-04-14
  last_updated: 2026-04-14T10:30:00
  iterations: 2
  errors: []
```

**State machine definition (optional):**
```yaml
state_machine:
  initial: brainstorming
  states:
    - name: brainstorming
      transitions: [planning, direct_response]
    - name: planning
      transitions: [executing, cancelled]
    - name: executing
      transitions: [verifying, failed]
    - name: verifying
      transitions: [complete, executing]  # loop back for fixes
    - name: complete
      transitions: []  # terminal
```

**Advantages:** Rich metadata, supports iteration counts and error history.
**Disadvantages:** Extra file to manage, must stay in sync with reality.

### Pattern 4: Schema-Driven DAG (Most Complete)

**Concept:** YAML defines artifact dependency graph. Script detects state via topological sort. Prevents skipping steps, supports parallel-ready artifacts.

**Full schema example (OpenSpec pattern):**
```yaml
name: my-workflow
version: 1
artifacts:
  - id: research
    generates: research.md
    template: templates/research.md
    instruction: |
      Research the topic and document findings.
      Include: Background, Current State, Key Findings.
    requires: []
  - id: plan
    generates: plan.md
    requires: [research]
  - id: implement
    generates: "src/**/*.py"
    requires: [plan]
  - id: verify
    generates: verification-report.md
    requires: [implement]
apply:
  requires: [verify]
  tracks: verification-report.md
```

**Three-state model per artifact:**

| State | Meaning | Condition |
|---|---|---|
| `done` | Completed | `generates` file exists in change dir |
| `ready` | Can create | All `requires` are done, self not done |
| `blocked` | Waiting | At least one `requires` not done |

**Parallel-ready detection:** If two artifacts share the same dependency but don't depend on each other, both become `ready` simultaneously (e.g., `specs` and `design` both depend only on `proposal`).

**Advantages:** Prevents step-skipping, supports parallel work, fully declarative.
**Disadvantages:** Requires schema file, more complex setup. OpenSpec core is ~500 lines.

## Generate-Validate-Fix Loop

**Core pattern from MindStudio + Compiled AI research:**

```
Agent generates -> Script validates -> If fail -> Agent fixes (max 3 rounds) -> If still fail -> escalate
```

**Research evidence:**
- Compiled AI (arXiv:2604.05150): 96% task completion with **zero runtime tokens** after compilation
- MindStudio: 3-5 iteration limit is the production standard
- Source Code Agent: Blueprint-First beats free-form by **+10.1 pp Pass@1**

**SKILL.md integration:**
```markdown
## Verification Loop
1. Generate output following the workflow
2. Run `scripts/validate.sh <output>` to check format/schema/tests
3. If validation passes -> done, mark task complete
4. If validation fails:
   a. Read the exact error message
   b. Fix ONLY the specific issues reported
   c. Re-run validation (go to step 2)
5. After 3 failed attempts -> report to user with partial results and error log
```

**Three-level validation hierarchy (from OpenSpec):**

| Level | When | What | Tool |
|---|---|---|---|
| Structure | Init / transition | Files exist, schema valid, no cycles | Zod/JSON Schema |
| Content | After artifact creation | Required sections present, format correct | Regex / parser / script |
| Semantic | After all artifacts | Implementation matches spec, no missing requirements | Code search / tests / LLM |

## Script Integration Patterns

### The Golden Rule

> **If a step CAN be a script, it SHOULD be a script.**

Compiled AI proves that compiling LLM output into deterministic code achieves **57x cost reduction** at scale (1000 transactions). smolagents' Code-as-Action reduces steps by **30%** vs ReAct.

### Deterministic vs Probabilistic Steps

| Step Type | Implementation | Reliability | Token Cost |
|---|---|---|---|
| Format checking | `scripts/validate.py` | 100% | 0 |
| Schema validation | `scripts/check_schema.py` | 100% | 0 |
| Code formatting | `prettier --write` | 100% | 0 |
| Dependency checking | `scripts/check_deps.sh` | 100% | 0 |
| Test execution | `pytest / npm test` | 100% | 0 |
| Creative decisions | LLM judgment | ~50-87% | High |
| State assessment | File existence check | 100% | 0 |
| State assessment | LLM self-report | ~12.5% | High |

### Script + SKILL.md Integration Modes

**Mode A: Script as Validation Gate**
```markdown
## Verification
1. Run `scripts/validate.sh <output>` to check format compliance
2. If exit code 0 -> proceed to next step
3. If exit code != 0 -> read stderr, diagnose, fix, re-validate
```

**Mode B: Script as Core Execution (Blueprint-First)**
```markdown
## Workflow
1. Prepare: `scripts/prepare.py --input <source>` -> generates working files
2. Transform: LLM processes each file following template
3. Verify: `scripts/validate.py --config references/schema.yaml <output>`
4. Format: `scripts/format.sh <output>` -> final cleanup
```

**Mode C: Script as Environment Check**
```markdown
## Prerequisites
Before starting, run `scripts/check_env.sh` to verify:
- Required tools are installed
- Target directory exists and is writable
- Dependencies are available
```

**Mode D: Script as State Detector (OpenSpec pattern)**
```bash
#!/bin/bash
# scripts/detect-state.sh <change-dir> <schema-file>
# Outputs: completed:[] ready:[] blocked:[]
```

## 6 Design Principles (Cross-Pattern)

### 1. Blueprint-First, Model Second
LLM never decides workflow path. Script/SKILL.md defines the path; LLM executes bounded sub-tasks within that path. (Source Code Agent, arXiv:2508.02721)

### 2. Dependency-Driven Progression
State transitions unlock when dependencies are met, not by external command. Prevents step-skipping and guarantees consistency.

### 3. State as Source of Truth
All behavior derives from reading current state, not inferring from history. Enables idempotency and recovery.

### 4. Instruction Injection
Provide structured context to LLM (templates, rules, dependency info) rather than letting it improvise. Reduces hallucination.

### 5. Validation Guards
Validate at every state transition. Reject invalid transitions early. Three severity levels: CRITICAL (must fix), WARNING (should fix), SUGGESTION (nice to have).

### 6. Persistent Checkpoints
Save state at key points. Long-running agents without persistence have **90% higher failure risk** (Indium Tech 2026). File system is the simplest checkpoint store.

## Quick Decision Guide

```
How many steps does your skill have?
  1-2 steps  -> Pattern 1 (file existence) or no state needed
  3-5 steps  -> Pattern 2 (checkbox tracking)
  5+ steps   -> Pattern 3 (YAML state) or Pattern 4 (schema DAG)

Does output from one invocation feed into the next?
  YES -> Need checkpointing (file existence or YAML state)
  NO  -> Stateless is fine

Are there conditional branches in the workflow?
  YES -> Pattern 3 or 4 (explicit state machine)
  NO  -> Pattern 1 or 2 (linear progression)

Do you need parallel-ready phases?
  YES -> Pattern 4 (DAG with topological sort)
  NO  -> Any simpler pattern
```

## Key Evidence

| Finding | Data | Source |
|---|---|---|
| Blueprint-First beats free-form | +10.1 pp Pass@1 | arXiv:2508.02721 |
| Compiled AI reduces tokens | 57x at scale (1000 txns) | arXiv:2604.05150 |
| Compiled AI task completion | 96% with zero runtime tokens | arXiv:2604.05150 |
| Large model output consistency | Only 12.5% (GPT-OSS-120B) | arXiv:2511.07585 |
| Small model at T=0.0 | 100% consistency | arXiv:2511.07585 |
| Long agent failure without persistence | 90% higher risk | Indium Tech 2026 |
| Generate-Validate-Fix optimal iterations | 3-5 rounds | MindStudio |
| Code-as-Action reduces steps | 30% vs ReAct | smolagents (HF) |
| OpenSpec core code | ~500 lines | OpenSpec source |
| smolagents core code | ~1,000 lines | smolagents source |
| Multi-agent token overhead | 15x vs standard dialog | Indium Tech 2026 |
| Context >20k tokens accuracy drop | 30-50% | Indium Tech 2026 |

## Sources

| Source | URL | Key Contribution |
|---|---|---|
| Source Code Agent | https://arxiv.org/abs/2508.02721 | Blueprint-First paradigm |
| Compiled AI | https://arxiv.org/abs/2604.05150 | Compile LLM output to deterministic code |
| LLM Output Drift | https://arxiv.org/abs/2511.07585 | Output consistency measurements |
| Know When To Stop | https://aclanthology.org/2024.naacl-long.202/ | Semantic drift in generation |
| Adding Determinism (IWSDS) | https://aclanthology.org/2026.iwsds-1.26.pdf | FSM vs pure prompt comparison |
| OpenSpec | Local source: `@fission-ai/openspec` | DAG artifact graph, file-as-state |
| LangGraph | https://github.com/langchain-ai/langgraph | StateGraph, checkpoint, conditional edges |
| MetaGPT | https://github.com/FoundationAgents/MetaGPT | Code=SOP(Team), ICLR 2025 oral |
| smolagents | https://github.com/huggingface/smolagents | Code-as-Action, 30% step reduction |
| MindStudio | https://www.mindstudio.ai/blog/structured-ai-coding-workflow-deterministic-agentic-nodes/ | Generate-Validate-Fix loop |
| Indium Tech | https://www.indium.tech/blog/7-state-persistence-strategies-ai-agents-2026/ | 7 persistence strategies |
| DOMINO | https://proceedings.mlr.press/v235/beurer-kellner24a.html | Constrained decoding, ICML 2024 |
| Agent-States | https://github.com/AlgorithmicResearchGroup/Agent-States | FSM for agent state |
| AgentScript | https://github.com/AgentScript-AI/agentscript | Code-as-plan, AST execution |


path: references/skill-optimization.md
content: # Skill Optimization Guide

基于同行评审研究（ACL/NeurIPS/EMNLP 2023-2025）、AI 厂商官方指南（Anthropic/Google/Microsoft）和生产级工程实践（Claude Code/Cursor/Windsurf 社区）的技能优化框架。AI agent 读取后即可立即对技能进行针对性优化。

## Table of Contents

1. [诊断优先原则](#1-诊断优先原则)
2. [9 大优化维度](#2-9-大优化维度)
   - [D1: 触发描述质量](#d1-触发描述质量-trigger-precision)
   - [D2: 上下文效率](#d2-上下文效率-token-economy)
   - [D3: 结构化指令](#d3-结构化指令-visual-separation)
   - [D4: 步骤分解](#d4-步骤分解-actionable-sequences)
   - [D5: 正向约束](#d5-正向约束-affirmative-framing)
   - [D6: 示例设计](#d6-示例设计-concrete-demonstrations)
   - [D7: 验证机制](#d7-验证机制-quality-gates)
   - [D8: 自由度校准](#d8-自由度校准-specificity-matching)
   - [D9: 渐进式加载](#d9-渐进式加载-context-architecture)
3. [按技能类型的优化优先级](#3-按技能类型的优化优先级)
4. [反模式目录](#4-反模式目录)
5. [证据来源](#5-证据来源)

---

## 1. 诊断优先原则

在修改任何内容之前，先完整读取技能文件并诊断哪些维度存在问题。并非每个技能都需要在所有维度上优化。

### 快速诊断问题

对每个维度回答诊断问题。如果答案是"否"或"不确定"，则该维度需要优化。

| # | 维度 | 诊断问题 |
|---|------|---------|
| D1 | 触发描述质量 | 遮住 SKILL.md 正文，只看 name + description，能判断何时触发吗？ |
| D2 | 上下文效率 | 逐行审计——"删掉这行 agent 会犯错吗？"——每行都通过了吗？ |
| D3 | 结构化指令 | 不同类型的内容（工作流、约束、示例）是否用视觉分隔？ |
| D4 | 步骤分解 | 复杂的多步骤流程是否被分解为编号的、有序的步骤？ |
| D5 | 正向约束 | 规则是用"做 X"而非"不要做 Y"来表达的？ |
| D6 | 示例设计 | 是否包含至少一个具体的"用户请求 → 期望行为"示例？ |
| D7 | 验证机制 | 技能是否告诉 agent 如何验证其输出是否正确？ |
| D8 | 自由度校准 | 具体程度是否匹配任务脆弱性（脆弱任务用严格步骤，创意任务用灵活指导）？ |
| D9 | 渐进式加载 | SKILL.md 是否精简，详细信息是否推迟到 `references/`？ |

### 诊断输出

诊断后，生成一个按预期影响排序的、需要优化的维度排名列表。首先关注前 3-4 个问题。

---

## 2. 9 大优化维度

### D1: 触发描述质量 (Trigger Precision)

#### 为什么这样做

`description` 字段是**唯一始终加载到上下文中**的内容。无论 agent 当前在做什么任务，description 都会被扫描以判断是否触发该技能。如果 description 无法让 agent 正确识别触发时机，技能即使存在也不会被调用。

Claude Code Issue #9716（69+ 👍）明确记录了这一现象：安装在 `.claude/skills/` 中的技能因为 description 缺少触发短语而**完全不被识别**。这意味着无论 SKILL.md 写得多好，如果 description 不合格，整个技能等于不存在。

**核心原理**：description 的作用是"路由器"——它决定技能是否被激活，而非说明技能如何工作。工作细节属于 SKILL.md 的职责。

#### 诊断方法

1. **遮罩测试**：用纸遮住 SKILL.md 全文，只看技能的 `name` 和 `description`
2. 问自己：如果 agent 当前正在处理任务 X，它能仅凭这两个字段判断"我需要加载这个技能"吗？
3. 如果答案是"不确定"或"不能"，description 需要重写

#### 优化操作：三步公式

1. **能力描述**：一句话说明技能做什么（25词以内）
2. **触发场景编号列表**：用 `(1)...(2)...(3)...` 列出具体使用场景
3. **具体触发关键词**：列出用户可能使用的短语/关键词

#### Before/After 对比示例

**示例 1：PDF 处理技能**

```yaml
# ❌ BEFORE: 无触发短语，无具体场景
name: pdf-helper
description: Helps with PDF operations and document processing.

# ✅ AFTER: 能力 + 场景 + 关键词
name: pdf-helper
description: >
  Create, edit, and analyze PDF documents. Use when working with .pdf
  files for: (1) Extracting text or form data, (2) Rotating or merging
  pages, (3) Filling form fields, (4) Converting PDFs to images.
  Trigger: "pdf", "rotate pdf", "merge pdf", "extract text", "fill form"
```

**示例 2：数据库操作技能**

```yaml
# ❌ BEFORE: 只描述功能，不描述触发时机
name: db-toolkit
description: Provides database operation capabilities for multiple database types.

# ✅ AFTER: 明确列出触发场景和关键词
name: db-toolkit
description: >
  轻量级多数据库操作工具，支持 MySQL/PostgreSQL/SQLite 的 DDL/DML 操作。
  触发场景：(1) 连接/测试数据库 (2) 查看表结构/列出所有表 (3) 执行 SQL 查询
  (4) 创建/修改/删除表 (5) 增删改数据。
  触发词："连接数据库"、"查看表结构"、"执行SQL"、"创建表"
```

**示例 3：前端设计技能**

```yaml
# ❌ BEFORE: 抽象描述，缺乏可操作性
name: ui-design
description: Senior UI/UX engineering guidance for building better interfaces.

# ✅ AFTER: 具体场景 + 明确触发词
name: design-taste-frontend
description: >
  Senior UI/UX Engineer. Enforces metric-based rules, strict component
  architecture, CSS hardware acceleration, and balanced design engineering.
  Use when: (1) Building new UI components (2) Reviewing CSS/HTML quality
  (3) Deciding layout or animation approaches (4) Optimizing rendering
  performance. Trigger: "design", "UI", "CSS", "component", "layout",
  "animation", "responsive"
```

#### 检查清单

- [ ] Description 包含技能做什么（能力）
- [ ] Description 包含何时使用（触发场景，编号列表）
- [ ] Description 包含具体关键词/短语
- [ ] Description 在 1024 字符以内
- [ ] Description 中无尖括号（破坏 YAML 解析）
- [ ] 遮罩测试通过：仅凭 name+description 能判断触发时机

---

### D2: 上下文效率 (Token Economy)

#### 为什么这样做

上下文窗口是最稀缺的资源。过载的技能不仅自身被忽略，还会**拖累所有已加载技能的性能**。

Claude Code Issue #2544（39+ 👍）证明：当 CLAUDE.md（与 SKILL.md 机制相同）超过 200 行时，规则开始被系统性地忽略。Issue #6354（27+ 👍）进一步证明：在上下文压缩（compaction）后，长文件的规则会被遗忘。

CFPO 论文（Liu et al., Fudan/Microsoft, 2025）提供了定量证据：仅通过格式优化（不改变内容）即可带来 **5-38%** 的性能提升。这证明**信息密度**本身就是一个独立的优化维度。

Anthropic 最佳实践总结为一条原则："大多数最佳实践源于一个约束：上下文很快就会填满。"

#### 诊断方法

1. **逐行审计**：对 SKILL.md 中的每一行问"如果删掉这行，agent 会犯错吗？"
2. 如果答案是"不会"或"大概率不会"，该行应删除或移至 references
3. **重复检测**：SKILL.md 和 references 之间是否有信息重复？
4. **已知知识检测**：是否有内容是 LLM 已经知道的通用知识？

#### 优化操作：三步精简法

1. **删除已知知识**：移除 LLM 已知的通用概念（"Python 是一种编程语言"、"REST API 使用 HTTP 方法"等）
2. **用示例替代段落**：一个具体示例胜过三段文字解释
3. **细节移入 references**：边缘情况、完整 API 文档、高级用法 → `references/`

#### Before/After 对比示例

**示例 1：冗长解释 → 精简指令**

```markdown
# ❌ BEFORE: 30+ tokens，包含已知知识
When you encounter a PDF file that has fillable form fields, you should
use the pdfplumber library to first identify what fields exist in the
document, and then fill them using the fill_form_fields.py script located
in the scripts directory of the project.

# ✅ AFTER: 20 tokens，直接指令 + 引用
Fill PDF forms: Run `scripts/fill_form_fields.py <pdf_path>` to list
and fill form fields. See [PDF-FORMS.md](references/pdf-forms.md) for
field types and advanced options.
```

**示例 2：重复信息 → 单一来源**

```markdown
# ❌ BEFORE: SKILL.md 中重复了 references 的内容
## API Endpoints
- GET /api/users — List all users (returns User[])
- GET /api/users/:id — Get user by ID (returns User)
- POST /api/users — Create user (body: CreateUserDTO, returns User)
- PUT /api/users/:id — Update user (body: UpdateUserDTO, returns User)
- DELETE /api/users/:id — Delete user (returns void)
See references/api.md for more details.

# ✅ AFTER: SKILL.md 只保留摘要，详情在 references
## API Endpoints
CRUD operations on `/api/users`. See [API.md](references/api.md) when
you need specific endpoint signatures, request/response types, or
authentication headers.
```

**示例 3：段落解释 → 具体示例**

```markdown
# ❌ BEFORE: 解释"为什么"，agent 不需要
Before running the migration, it is important to back up the database
because migrations can sometimes fail and leave the database in an
inconsistent state. We use a custom backup script that creates a
timestamped snapshot, which allows us to restore to any point in time.

# ✅ AFTER: 直接指令 + 示例
## Pre-migration
Always backup before migrating:
  `scripts/backup.sh`  # Creates timestamped snapshot at backups/
Verify backup exists before proceeding.
```

#### 检查清单

- [ ] SKILL.md 正文在 500 行以内（硬性上限）
- [ ] 目标长度：200-300 行
- [ ] 每行都通过"删掉会犯错吗？"测试
- [ ] 无 SKILL.md 和 references 之间的信息重复
- [ ] 无 LLM 已知的通用知识解释
- [ ] 边缘情况和详细信息已移至 `references/`

---

### D3: 结构化指令 (Visual Separation)

#### 为什么这样做

LLM 解析结构化内容的可靠性显著高于混合格式的内容块。当不同类型的内容（工作流、约束、示例）混在一起时，指令会"模糊化"——agent 难以区分哪些是必须遵守的规则、哪些是参考信息、哪些是示例。

CFPO 论文（Liu et al., 2025）提供了关键发现：**联合优化内容和格式**优于分别优化（GSM8K: 63.38% vs 各自优化之和）。这意味着结构本身就是一种"指令"——告诉 agent 如何理解内容的格式。

Anthropic、Google 和 Microsoft 三家独立推荐使用 XML 标签或 Markdown 分隔来组织提示词：
- Anthropic：推荐 `<instructions>`、`<example>`、`<constraints>` 等 XML 标签
- Google Gemini 3 指南："Use XML tags or Markdown headings to clearly separate prompt sections"
- Microsoft：将提示词分解为 Instructions / Content / Examples / Cue 四个组件

#### 诊断方法

1. 扫描 SKILL.md：不同类型的内容是否有视觉分隔？
2. 约束条件是否被埋在段落中间？
3. 工作流步骤是否和说明注释混在一起？

#### 优化操作

1. 用 `###` 标题分隔不同类型的内容（工作流、约束、示例、验证）
2. 用 `---` 分隔符创建视觉边界
3. 用代码块（` ``` `）包裹代码和命令
4. 关键规则用加粗或列表强调

#### Before/After 对比示例

**示例 1：无结构 → 有结构**

```markdown
# ❌ BEFORE: 所有内容混在一起
This skill helps you deploy applications. First you need to check if
all tests pass by running npm test. If tests pass, build the project
with npm run build. Then deploy to staging using the deploy script.
Make sure you never deploy to production without staging approval.
Also remember to update the changelog. Here's an example: when the
user says "deploy v2.3", run tests, build, deploy to staging, then
ask for approval. If the user says "deploy to prod", verify staging
is approved first.

# ✅ AFTER: 结构化分隔
## Workflow

1. **Test**: Run `npm test` — all tests must pass
2. **Build**: Run `npm run build`
3. **Stage**: Run `scripts/deploy.sh staging`
4. **Verify**: Confirm staging deployment is healthy

---

## Constraints

- Always update `CHANGELOG.md` before deploying
- Production deploy requires explicit staging approval

---

## Examples

### User: "deploy v2.3"
→ 1. Run tests  2. Build  3. Deploy to staging  4. Ask for prod approval

### User: "deploy to prod"
→ 1. Verify staging is approved  2. If yes, deploy  3. If no, STOP and inform
```

**示例 2：约束埋在段落中 → 独立约束区**

```markdown
# ❌ BEFORE: 约束分散在说明文本中
When generating API documentation, you should always include the endpoint
URL, HTTP method, request parameters, and response format. Don't include
internal implementation details. Also make sure the examples use realistic
data, not placeholder text like "foo" or "bar".

# ✅ AFTER: 独立约束区，视觉清晰
## Constraints

- Include for every endpoint: URL, HTTP method, parameters, response format
- Use realistic data in examples (never "foo", "bar", "test")
- Omit internal implementation details
```

#### 检查清单

- [ ] 指令、约束和示例在不同区域
- [ ] 每个区域有清晰的 Markdown 标题
- [ ] 复杂区域使用子标题增强可扫描性
- [ ] 没有超过 5 行的段落没有视觉分隔
- [ ] 代码和命令用代码块包裹

---

### D4: 步骤分解 (Actionable Sequences)

#### 为什么这样做

逐步指令产生的 agent 行为质量显著优于自由格式描述。这是因为编号步骤为 agent 提供了明确的执行顺序和进度追踪能力。

**Chain of Methodologies（CoM, Liu et al., ACL 2025）** 证明：结构化的逐步推理在复杂任务上优于非结构化方法。关键机制是"方法论链"——每个步骤都是可验证的、有明确输入输出的单元。

**Watch Every Step（Xiong et al., EMNLP 2024）** 证明：步骤级指导显著增强 agent 效率。具体而言，当 agent 知道"下一步做什么"时，减少了无效的探索和回溯。

**Read Before You Think（2025）** 补充证明：将推理分解为显式步骤比自由推理更有效，因为每个步骤可以被独立验证。

Cursor 最佳实践中的 "Plan-and-Act" 模式也体现了同一原理：先规划（步骤列表），再执行。

#### 诊断方法

1. 工作流是否用编号步骤描述？
2. 每个步骤是否是单一、可执行的指令？
3. 是否有决策分支（if X → do Y, else → do Z）？
4. 是否有错误处理（步骤失败时怎么办）？

#### 优化操作

1. **段落 → 编号列表**：将流程描述转换为编号步骤
2. **添加决策点**：在关键分支处添加 if/else 条件
3. **添加错误处理**：每个可能失败的步骤都有失败处理路径

#### Before/After 对比示例

**示例 1：段落 → 编号步骤**

```markdown
# ❌ BEFORE: 自由格式描述
Process the document by extracting key fields, validating them against
the schema, and then generating a report. Handle errors gracefully and
make sure all required fields are present before generating the report.

# ✅ AFTER: 编号步骤 + 决策点 + 错误处理
## Workflow

1. **Extract**: Read document, extract fields listed in `references/schema.md`
2. **Validate**: Check each field against schema rules
   - If validation passes → proceed to step 3
   - If validation fails → report specific errors with line numbers, suggest fixes, STOP
3. **Transform**: Run `scripts/transform.py --input <extracted.json>`
   - If script fails → capture stderr, check `references/troubleshooting.md`, report
4. **Report**: Generate output using `assets/report-template.md`
5. **Verify**: Confirm output contains all required sections (summary, details, metadata)
   - If any section missing → regenerate from step 4
```

**示例 2：无决策分支 → 有决策分支**

```markdown
# ❌ BEFORE: 线性描述，缺少分支处理
Run the migration script and then verify the database. If something
goes wrong, fix it and try again.

# ✅ AFTER: 明确决策分支和失败处理
## Migration Workflow

1. **Backup**: Run `scripts/backup.sh` → verify `backups/` has new snapshot
2. **Dry-run**: Run `scripts/migrate.py --dry-run`
   - If dry-run succeeds → proceed to step 3
   - If dry-run shows conflicts → STOP, report conflicts, ask user to resolve
3. **Migrate**: Run `scripts/migrate.py`
   - If migration succeeds → proceed to step 4
   - If migration fails → run `scripts/rollback.sh`, report error, STOP
4. **Verify**: Run `scripts/verify-migration.py`
   - If verify passes → report success
   - If verify fails → run `scripts/rollback.sh`, escalate to user
```

#### 检查清单

- [ ] 多步骤流程使用编号列表
- [ ] 每个步骤是单一、可执行的指令
- [ ] 决策点包含清晰的分支（if X → do Y）
- [ ] 错误处理是显式的（失败时做什么）
- [ ] 工作流末尾有验证步骤

---

### D5: 正向约束 (Affirmative Framing)

#### 为什么这样做

LLM 遵循正向约束（"做 X"）的可靠性显著高于负向约束（"不要做 Y"）。这不是"风格偏好"，而是已被定量研究证实的能力边界。

**Inverse IFEval（Zhang et al., ByteDance/NJU/PKU, 2025）** 系统测试了所有主流 LLM 在正向约束和负向约束上的表现，结论明确：**所有 LLM 在负向/非常规约束上的表现都显著差于正向约束**。这是跨模型的普遍现象，不是某个模型的特有问题。

**Constraint Decomposition（Paunova, 2025）** 提供了更精确的数据：将复杂约束分解为单条简单约束，可将 prompt 级别的准确率从 **41.2% 提升到 73.8%**（+32.6 个百分点）。这意味着"不要做 X 且不要做 Y 且不要做 Z"远不如分别表达为三个独立的正向规则。

Anthropic 最佳实践明确建议："Instead of 'don't use markdown', say 'use flowing prose paragraphs'."

#### 诊断方法

1. 扫描技能文件中的 "don't"、"never"、"avoid"、"no"、"without" 等否定词
2. 每个否定约束是否有对应的正面表述？
3. 是否有"不要做 X 且不要做 Y"这种复合否定？

#### 优化操作

1. **负约束 → 正约束**：将"不要做 Y"改写为"做 X"
2. **安全关键负约束保留但配正面替代**：涉及安全/不可逆操作的否定约束可以保留，但必须同时给出正面替代
3. **复杂约束分解为单条**：一个约束只表达一个规则

#### Before/After 对比示例

**示例 1：基本否定 → 肯定**

```markdown
# ❌ BEFORE
Don't write functions longer than 20 lines.

# ✅ AFTER
Keep every function under 20 lines. If logic is complex, extract helper functions.
```

**示例 2：复合否定 → 分解的肯定**

```markdown
# ❌ BEFORE: 三条否定约束堆叠
Never modify files outside the project directory. Don't use deprecated APIs.
Avoid adding new dependencies without approval.

# ✅ AFTER: 三条独立正向约束
- Only modify files within the project directory
- Use the latest stable API version from `references/api.md`
- Request user approval before adding new dependencies (list the package and reason)
```

**示例 3：安全关键场景**

```markdown
# ❌ BEFORE: 纯否定，agent 不知道该做什么
CRITICAL: Never delete files without asking the user first. Don't modify
production configuration files.

# ✅ AFTER: 保留安全否定 + 给出正面替代
## Safety Rules
- CRITICAL: Ask user confirmation before deleting any file
- CRITICAL: Only modify production configs after explicit user approval
- When in doubt about a destructive action: STOP, describe the action, ask for confirmation
```

**示例 4：模糊否定 → 具体肯定**

```markdown
# ❌ BEFORE: "avoid" 是最弱的否定词
Avoid using global variables in your code.

# ✅ AFTER: 具体的正向替代方案
Pass state as function parameters or use dependency injection. If shared
state is necessary, use a module-level singleton with clear access patterns.
```

#### 检查清单

- [ ] 规则用"做 X"而非"不要做 Y"表达
- [ ] 安全关键的否定约束配有正面替代
- [ ] 约束是具体可测量的（"20 行以内"而非"简短"）
- [ ] 复杂约束集分解为独立规则
- [ ] 无 "avoid" 这类模糊否定词

---

### D6: 示例设计 (Concrete Demonstrations)

#### 为什么这样做

示例是控制 LLM 输出行为的**最可靠机制**。这不是"锦上添花"，而是与指令同等重要的核心组件。

Cursor 官方数据：Good/Bad 示例使规则效果提升 **3 倍**。注意不是 30%，而是 300%——这意味着一个带示例的规则比三个不带示例的规则更有效。

**1-shot CoT Distillation（Chen et al., ACL 2025）** 证明：1-shot（一个示例）是灵活性和结构之间的最优平衡点。更多示例的边际收益递减，但 0 个示例则完全没有结构引导。

Google Gemini 指南："We recommend to always include few-shot examples"——"always" 这个词在官方文档中很少见，表明示例的重要性。

Anthropic 推荐 3-5 个精心设计的示例，并使用 `<example>` 标签包裹。

#### 诊断方法

1. 技能中是否有"用户请求 → agent 行为"格式的示例？
2. 示例是否使用了真实场景（而非占位符如 "process a file"）？
3. 示例是否覆盖了最常见的使用场景？

#### 优化操作

1. 添加 1-3 个具体示例
2. 格式：`### User: "..." → 1. ... 2. ... 3. ...`
3. 简单技能 1-2 个，中等技能 3-5 个，复杂技能 3-5 个核心 + references 中的详细示例

#### 好示例 vs 坏示例

```markdown
# ❌ BAD: 抽象示例，无具体输入输出
Use the transform script to convert between formats. For example,
you might process a CSV file and convert it to JSON format.

# ✅ GOOD: 具体的用户请求 → 期望的 agent 行为
## Examples

### User: "Convert this CSV to JSON"
→ 1. Run `scripts/transform.py data.csv --output data.json`
→ 2. Verify the JSON has expected keys: `name`, `date`, `amount`
→ 3. Report: "Converted 150 records from CSV to JSON"

### User: "The output has wrong date format"
→ 1. Check current date format in output
→ 2. Add `--date-format ISO8601` flag to transform command
→ 3. Re-run and verify dates match `YYYY-MM-DD`

### User: "Merge these two PDFs"
→ 1. Run `scripts/pdf-merge.py input1.pdf input2.pdf --output merged.pdf`
→ 2. Verify page count: original1 + original2 = merged
→ 3. Report: "Merged into N pages"
```

**为什么好示例有效**：好示例同时展示了三件事——(1) agent 应该执行什么命令 (2) 如何验证结果 (3) 如何向用户报告。坏示例只展示了"做什么"，遗漏了验证和沟通。

#### 检查清单

- [ ] 至少 1 个具体的"用户请求 → agent 行为"示例
- [ ] 示例使用真实的用户输入（非占位符）
- [ ] 示例覆盖最常见使用场景
- [ ] 错误/边缘情况示例（如适用）
- [ ] SKILL.md 中不超过 5 个示例（多余的放入 references）

---

### D7: 验证机制 (Quality Gates)

#### 为什么这样做

没有验证标准的 agent 会产出"看起来正确"但实际错误的结果。这不是偶发问题，而是 agent 的系统性倾向。

Claude Code Issue #42796（**1781 👍**，是该仓库最高赞 issue 之一）提供了定量分析：agent 的 Read:Edit 比率下降了 70%——意味着 agent 在修改文件前越来越少地先读取文件，直接跳过验证步骤导致错误。Issue 标题直指问题本质："Claude rushes to completion"（Claude 急于完成任务）。

Anthropic 最佳实践明确要求："Always provide validation criteria"（始终提供验证标准）。

生产级模式 Plan → Act → Verify 被 Cursor、Aider 和 Claude Code 一致采用，因为这是唯一能确保输出质量的方法。

#### 诊断方法

1. 工作流最后是否有验证步骤？
2. 是否有可测试的成功标准？（不是"确保质量好"，而是"运行 `npm test` 且全部通过"）
3. 验证失败时 agent 知道该怎么做吗？

#### 优化操作

1. **添加验证步骤**：每个工作流末尾添加明确的验证环节
2. **定义可测试标准**：标准必须是机器可验证的（命令输出、文件存在性、断言）
3. **失败时的处理流程**：验证失败 → 诊断 → 修复 → 重新验证

#### Before/After 对比示例

**示例 1：无验证 → 有验证**

```markdown
# ❌ BEFORE: 无验证步骤
## Deployment
1. Build the project
2. Deploy to staging
3. Inform the user

# ✅ AFTER: 完整验证链
## Deployment
1. Build: `npm run build` — confirm exit code 0
2. Deploy: `scripts/deploy.sh staging`
3. **Verify**:
   - Run `curl -f https://staging.example.com/health` — expect 200
   - Run `scripts/smoke-test.sh` — all tests pass
4. Report results to user
5. If any verification fails → capture logs, diagnose, fix, re-deploy, re-verify
```

**示例 2：模糊成功标准 → 可测试标准**

```markdown
# ❌ BEFORE: 不可测试的标准
After generating the report, make sure it looks good and contains
all the necessary information.

# ✅ AFTER: 可测试的验证标准
## Verification

After generating the report, verify all checks pass:

1. **File exists**: `ls -la reports/<report-name>.md`
2. **Sections complete**: Report contains `## Summary`, `## Details`, `## Metadata`
3. **Data accurate**: Run `scripts/validate-report.py reports/<report-name>.md`
4. **No regressions**: `npm test` — all existing tests pass

If any check fails: diagnose the specific failure, fix the report, re-verify.
Do NOT inform the user of success until all 4 checks pass.
```

#### 检查清单

- [ ] 工作流包含显式验证步骤
- [ ] 成功标准是具体可测试的
- [ ] agent 知道验证失败时做什么
- [ ] 尽可能引用自动化检查（测试命令、脚本）
- [ ] 验证失败时不会向用户报告"完成"

---

### D8: 自由度校准 (Specificity Matching)

#### 为什么这样做

过度约束创意任务会不必要地限制模型；约束不足的脆弱任务会导致错误。这不是"一刀切"的问题，而是需要根据任务类型精确校准。

**NeurIPS 2024 论文 "Teach Better or Show Smarter?"** 证明：教学（指令优化）vs 示例（模仿学习）的效果取决于任务类型。对于需要精确遵循步骤的任务（如数学证明），显式指令更有效；对于需要创造力的任务（如写作），示例更有效。

Claude Code 的设计原则形象地描述了这一思想："Think of Codex exploring a path — a narrow bridge needs guardrails, an open field allows many routes"（想象 Codex 在探索路径——窄桥需要护栏，开阔田野允许多条路线）。

#### 诊断方法

1. 脆弱任务（部署、数据库迁移）的指令是否足够具体？
2. 创意任务（写作、设计）是否过度约束？
3. 同一技能中是否存在矛盾的 specificity 信号？

#### 优化操作

按任务类型校准自由度：

| 任务类型 | 自由度 | 信号词 | 优化策略 |
|---------|--------|-------|---------|
| 脆弱序列（部署、DB 迁移） | **低** | "必须"、"精确"、"按顺序" | 编号步骤、具体命令、脚本 |
| 模式化任务（代码生成、API 调用） | **中** | "优先"、"通常"、"默认" | 首选模式 + 允许的替代方案 |
| 创意/开放式（写作、头脑风暴） | **高** | "考虑"、"可以"、"探索" | 原则 + 示例，少量硬规则 |

#### 低/中/高自由度的典型示例

**低自由度（数据库迁移）**：
```markdown
## Migration Workflow
1. Run `scripts/backup.sh` to create DB backup
2. Run `scripts/migrate.py --dry-run` and verify output
3. ONLY if dry-run succeeds: run `scripts/migrate.py`
4. Run `scripts/verify-migration.py` to confirm data integrity
```
→ 每步都是具体命令，无解释，无替代方案。

**中等自由度（API 客户端生成）**：
```markdown
## Code Generation
- Prefer typed request/response interfaces (TypeScript/zod)
- Use fetch with proper error handling; axios is acceptable if already in project
- Follow existing project patterns in `src/api/` for consistency
```
→ 有偏好但不强制，允许合理的替代方案。

**高自由度（技术博客写作）**：
```markdown
## Writing Guidelines
- Match the brand voice described in `references/brand-voice.md`
- Target length: 500-800 words
- Structure: Lead with the key insight, then expand with evidence
- Include at least one code example if the topic is technical
```
→ 原则而非规则，给 agent 充分的创作空间。

#### 检查清单

- [ ] 自由度级别匹配任务脆弱性
- [ ] 脆弱任务有编号的具体步骤（可能包含脚本）
- [ ] 创意任务有原则，而非死板的规则
- [ ] 同一区域中无矛盾的 specificity 信号

---

### D9: 渐进式加载 (Context Architecture)

#### 为什么这样做

一次性加载所有内容会浪费上下文空间——agent 在当前任务中并不需要所有信息。

不同平台的加载机制不同，但原则一致：**只在需要时加载需要的内容**。

- **Claude Code**：三层加载机制——Metadata（~100 词，始终加载）→ SKILL.md（<5k 词，触发时加载）→ Resources（按需加载）
- **Cursor**：.mdc 模式，按文件路径触发规则，只有匹配路径时才加载对应规则
- **Windsurf**：**6000 字符硬限制**，强制要求激进的上下文管理

#### 诊断方法

1. SKILL.md 是否在 500 行以内？
2. references/ 是否从 SKILL.md 链接？
3. 链接是否说明了**何时**读取？（不是"更多信息见 X"，而是"当用户要求 Y 时，读取 X"）
4. references 是否嵌套超过 1 层？

#### 优化操作

1. **核心工作流留在 SKILL.md**：处理 80% 场景的最小工作流
2. **详细信息移到 references**：边缘情况、完整 API 文档、高级用法
3. **每个链接说明 WHEN**：明确告诉 agent 在什么条件下读取 reference

#### Before/After 对比示例

**示例 1：所有内容塞进 SKILL.md → 渐进式加载**

```markdown
# ❌ BEFORE: SKILL.md 600+ 行，包含所有内容
## API Endpoints
[50 行完整 API 文档]

## Error Codes
[30 行错误码列表]

## Authentication
[20 行认证说明]

## Rate Limiting
[15 行限流说明]

## Examples
[40 行示例]

## Troubleshooting
[50 行排错指南]
[总计：205+ 行，仅 API 相关]

# ✅ AFTER: SKILL.md 只保留核心 + 引用
## API Usage
Base URL: `https://api.example.com/v2`
Auth: Bearer token in `Authorization` header

For endpoint details, read the relevant reference:
- **CRUD operations**: See [API.md](references/api.md) when working with users/orders endpoints
- **Authentication**: See [API.md](references/api.md#auth) when configuring auth
- **Error handling**: See [ERRORS.md](references/errors.md) when API returns 4xx/5xx
[总计：6 行 + 3 行引用]
```

**示例 2：模糊引用 → 条件化引用**

```markdown
# ❌ BEFORE: 引用但不说何时读取
For more details, see references/advanced.md.

# ✅ AFTER: 明确的触发条件
- **Custom schemas**: Read [SCHEMAS.md](references/schemas.md) when user provides non-standard input formats
- **Error handling**: Read [TROUBLESHOOTING.md](references/troubleshooting.md) when any script exits with non-zero code
- **Performance tuning**: Read [PERFORMANCE.md](references/performance.md) when user mentions "slow", "timeout", or "optimize"
```

#### 检查清单

- [ ] SKILL.md 正文在 500 行以内
- [ ] 详情移至 `references/`，有从 SKILL.md 的清晰链接
- [ ] 每个引用链接说明了**何时**读取
- [ ] 引用深度为 1 层（无嵌套引用）
- [ ] 大型引用文件（>100 行）有目录

---

## 3. 按技能类型的优化优先级

不同技能类型有不同的优化优先级。使用此矩阵聚焦优化努力。

| 技能类型 | 优先级排序（高→低） | 典型优化操作 |
|---------|-------------------|-------------|
| **工作流技能**（顺序流程） | D4 步骤 > D7 验证 > D2 效率 | 编号步骤、验证检查点、边缘情况移入 references |
| **工具集成技能**（API/CLI 封装） | D1 描述 > D8 自由度 > D6 示例 | 触发词包含工具/API 名、校准具体度、添加使用示例 |
| **知识/参考技能**（schema、策略、标准） | D9 渐进 > D2 效率 > D3 结构 | 激进地将详情移至 references、SKILL.md 只留导航、结构化分区 |
| **创意/生成技能**（写作、设计、头脑风暴） | D5 正向 > D8 自由度 > D6 示例 | 表达为原则而非规则、高自由度、用示例设定质量标杆 |
| **调试/分析技能**（排错、调查） | D4 步骤 > D7 验证 > D5 正向 | 诊断流程逐步化、内置验证、正向表达修复方案 |

### 优先级矩阵

```
              D1  D2  D3  D4  D5  D6  D7  D8  D9
工作流          ●   ●   ○   ★   ○   ○   ★   ○   ●
工具集成        ★   ○   ●   ●   ○   ★   ○   ★   ●
知识/参考       ○   ★   ★   ○   ○   ○   ○   ○   ★
创意/生成       ●   ●   ○   ○   ★   ★   ○   ★   ●
调试/分析       ●   ●   ○   ★   ★   ●   ★   ○   ●

★ = 最高优先级  ● = 重要  ○ = 可选
```

---

## 4. 反模式目录

已知会降低技能性能的模式。优化时检查这些反模式。

### AP-1: Kitchen Sink（大杂烩）

**症状**：SKILL.md > 500 行，涵盖过多主题，什么都想说
**根因**：害怕遗漏信息，把所有内容都塞进 SKILL.md
**修复**：核心工作流留在 SKILL.md，其余移至 `references/`
**证据**：Issue #2544 — 规则超过 200 行开始被忽略

### AP-2: Invisible Skill（隐形技能）

**症状**：技能已安装但从不触发
**根因**：description 缺少触发短语和场景
**修复**：用三步公式重写 description（能力 + 场景 + 关键词）
**证据**：Issue #9716 — 技能因缺少触发词而不被识别

### AP-3: Vague Guardrails（模糊护栏）

**症状**："Write clean code"、"Be helpful"、"Ensure quality"
**根因**：规则不可操作、不可测量
**修复**：替换为具体、可测量的规则（"函数 < 20 行"、"运行 `npm test` 且全部通过"）
**证据**：Anthropic — "Delete lines Claude could infer"

### AP-4: Negative-Only Rules（纯否定规则）

**症状**：满篇 "Don't do X"、"Never Y"、"Avoid Z"
**根因**：人类思维习惯用否定表达禁止，但 LLM 遵循负约束的能力差
**修复**：转换为正向表达（"Don't write long functions" → "Keep functions under 20 lines"）
**证据**：Inverse IFEval — 所有 LLM 在负约束上表现差

### AP-5: Missing Exit Condition（缺失退出条件）

**症状**：Agent 不断工作，不确定何时完成；或过早宣布完成
**根因**：没有定义"成功"的具体标准
**修复**：添加可测试的成功标准和显式的验证步骤
**证据**：Issue #42796（1781👍）— Agent 跳过验证导致错误

### AP-6: Flat Structure（扁平结构）

**症状**：所有内容在一个块中，无标题层级
**根因**：快速编写技能时忽略了结构
**修复**：添加 Markdown 层级（`##`、`###`）和 `---` 分隔符
**证据**：CFPO — 结构优化可带来 +5-38% 提升

### AP-7: Zombie References（僵尸引用）

**症状**：references/ 中有文件，但 SKILL.md 中没有链接
**根因**：创建了引用文件但忘记在 SKILL.md 中添加链接
**修复**：在 SKILL.md 中添加 "See [X](Y) when..." 的条件化引用
**证据**：Claude Code — 未链接的引用不会被 agent 发现和读取

### AP-8: Over-Specified Creative（过度约束创意任务）

**症状**：创意任务有 20 条死板规则（"精确 3 段"、"每段以...开头"）
**根因**：对创意任务使用了脆弱任务的约束策略
**修复**：减少为原则 + 示例，给 agent 创作空间
**证据**：NeurIPS 2024 — 任务类型决定最优方法

---

## 5. 证据来源

### 同行评审研究

| 论文 | 发表 venue | 核心发现 |
|------|-----------|---------|
| CFPO (Liu et al.) | arXiv 2025 | 内容+格式联合优化：相比基线 +5-38% |
| Inverse IFEval (Zhang et al.) | arXiv 2025 | 所有主流 LLM 在负约束上表现显著差于正约束 |
| Constraint Decomposition (Paunova) | Optimization Online 2025 | 约束分解：41.2% → 73.8% 准确率 |
| Chain of Methodologies (Liu et al.) | Findings of ACL 2025 | 结构化逐步推理优于自由格式 |
| Watch Every Step (Xiong et al.) | EMNLP 2024 | 步骤级指导增强 agent 效率 |
| What's in a Prompt (Atreja et al.) | ICWSM 2025 | 提示词结构因素显著影响输出质量 |
| Teach Better or Show Smarter | NeurIPS 2024 | 指令 vs 示例的有效性取决于任务类型 |
| 1-shot CoT Distillation (Chen et al.) | Findings of ACL 2025 | 1-shot 是灵活性和结构的最优平衡 |

### 官方指南

| 来源 | 核心建议 |
|------|---------|
| Anthropic | XML 标签、3-5 个示例、正向表达、"golden rule" 测试 |
| Google Gemini | "始终包含 few-shot 示例"、关键指令放最前 |
| Microsoft | 将提示词分解为 Instructions / Content / Examples / Cue |
| Brex | 命令语法、假设隐藏提示词可见 |

### 社区证据

| 来源 | 核心发现 |
|------|---------|
| Claude Code Issue #2544 (39+) | CLAUDE.md 规则在过长时被忽略 |
| Claude Code Issue #6354 (27+) | 上下文压缩后规则被遗忘 |
| Claude Code Issue #9716 (69+) | 技能因缺少触发词而不被识别 |
| Claude Code Issue #42796 (1781+) | Agent 跳过验证导致错误 |
| Cursor 官方博客 | Good/Bad 示例使规则效果提升约 3 倍 |

> **详细数据和完整引用**见 [evidence-database.md](evidence-database.md)


path: references/evidence-database.md
content: # Evidence Database for Skill Optimization

Complete research findings from 25+ peer-reviewed papers (ACL/NeurIPS/EMNLP/ICWSM 2023-2025), 6 official AI vendor guidelines (Anthropic/Google/Microsoft/Brex/DAIR.AI/Lilian Weng), and production-grade engineering practices from Claude Code/Cursor/Windsurf/Aider communities.

## Table of Contents

- [D1: Trigger Description Quality](#d1-trigger-description-quality)
- [D2: Context Efficiency](#d2-context-efficiency)
- [D3: Structured Instructions](#d3-structured-instructions)
- [D4: Step Decomposition](#d4-step-decomposition)
- [D5: Positive Constraints](#d5-positive-constraints)
- [D6: Example Design](#d6-example-design)
- [D7: Verification Mechanisms](#d7-verification-mechanisms)
- [D8: Freedom Calibration](#d8-freedom-calibration)
- [D9: Progressive Loading](#d9-progressive-loading)
- [Cross-Dimension Studies](#cross-dimension-studies)
- [Official Guidelines Comparison](#official-guidelines-comparison)
- [Community Evidence](#community-evidence)

---

## D1: Trigger Description Quality

> 触发描述是 skill 能否被正确激活的关键入口。描述质量直接决定 LLM 在意图匹配阶段是否选择加载该 skill。

### Academic Evidence

| 来源 | 关键发现 |
|---|---|
| Meta-analysis of prompt quality (Do et al., ACL 2025) | 单一属性优化（如描述精确度）往往产生最大影响；触发匹配属于"首次交互"维度，错误率在此阶段最高 |

### Official Guidelines

| 来源 | 指导原则 |
|---|---|
| Anthropic Official | description 是首要触发机制；将 "when to use" 信息放在描述中，而非 body 内部 |
| Claude Code plugin-dev SKILL.md 模式 | 使用第三人称，包含具体触发短语，如 "create a hook"、"add a PreToolUse hook" |

### Community Evidence

| Issue | 投票数 | 关键发现 |
|---|---|---|
| Claude Code Issue #9716 | 69👍 | Skill "shadcn-components" 已存在于 `.claude/skills/` 但未被识别。原因是 description 缺少具体组件名和触发短语 |
| Claude Code Issue #18192 | 40👍 | 社区请求递归 skill 发现 — 子目录中的 skill 未被找到 |

### Design Implications

1. **必含触发短语**：描述中必须包含用户可能使用的自然语言短语
2. **具体而非笼统**：`"创建 OpenClaw 插件（hook/tool/provider/channel 任意类型）"` 优于 `"帮助开发插件"`
3. **场景枚举**：列出所有适用的触发场景，用编号或无序列表
4. **第三人称**：与 Claude Code 的 skill 匹配机制保持一致

---

## D2: Context Efficiency

> 上下文窗口是稀缺资源。skill 加载的每一行都在与其他指令、代码、对话历史竞争注意力。效率即性能。

### Academic Evidence

| 来源 | 关键发现 |
|---|---|
| **CFPO** (Liu et al., Fudan University & Microsoft Research Asia, 2025, arXiv) | 首个系统性研究 content + format 联合优化。GSM8K 数学推理：LLaMA-3.1-8B baseline 50.03% → CFPO 63.38% (+13.35pp)；Big-Bench 分类：Mistral-7B baseline 56.00% → CFPO 94.00% (+38pp!)。消融实验：content-only (58.07%) + format-only (52.46%) < joint (63.38%) — 证明内容与格式相互依赖 |
| **LinguaShrink** (Liang et al., IEEE Access 2024) | 心理语言学提示压缩可在维持性能的同时减少 token 数量 |
| **SCOPE** (Zhang et al., arXiv 2025) | 过度压缩会丢失关键约束。需要在压缩率与信息保留之间取得平衡 |
| **What's in a Prompt** (Atreja et al., ICWSM 2025) | 16 条件析因实验，跨 4 个模型。精简提示降低成本，但可能在某些任务上降低准确率 |

### Official Guidelines

| 来源 | 指导原则 |
|---|---|
| Anthropic Best Practices | "Most best practices derive from one constraint: context fills fast, performance degrades as it fills."（大多数最佳实践源于一个约束：上下文填满快，性能随填充而下降） |
| Anthropic on Multi-Context Windows | 首个窗口构建框架（测试、setup 脚本）；后续窗口迭代 todo-list；优先使用新鲜上下文而非压缩 |

### Community Evidence

| Issue | 投票数 | 关键发现 |
|---|---|---|
| Claude Code Issue #2544 | 39👍 | CLAUDE.md 规则在文件超过 ~200 行时被一致性地忽略 |
| Claude Code Issue #6354 | 27👍 | CLAUDE.md 内容在上下文压缩后被遗忘 |
| Claude Code Issue #41279 | New | Compaction-Protected Rulebook 提案 — 三层分离：Skills（任务流程）、Rulebook（持久规则，压缩保护）、CLAUDE.md（项目上下文） |

### Design Implications

1. **Skill body 限制在 <5k 词**：Claude Code 的三级加载机制已证明此阈值有效
2. **首 100 词决定命运**：metadata 层（~100 词）始终加载，必须包含最关键信息
3. **用结构化格式替代冗长描述**：表格、列表、流程图比散文更高效
4. **避免与 CLAUDE.md 重复**：重复内容浪费上下文且在压缩后产生不一致

---

## D3: Structured Instructions

> 结构化指令通过清晰的分区和格式约定，显著提升 LLM 对复杂指令的遵从度。

### Academic Evidence

| 来源 | 关键发现 |
|---|---|
| **CFPO** (Liu et al., 2025) | Format + content 联合优化显著优于单独任一维度。不同 LLM 有截然不同的格式偏好 — 没有通用的"最佳格式"，模型特定格式优化至关重要 |
| **Structured Outputs in Prompt Engineering** (Ye et al., ACL 2025 Workshop) | 结构化 I/O 显著提升 LLM 对反直觉指令的遵从度 |

### Official Guidelines

| 来源 | 指导原则 |
|---|---|
| Anthropic | 推荐 XML 标签（`<instructions>`、`<example>`、`<constraints>`）进行清晰分区。嵌套标签用于层级内容：`<documents>` > `<document>`。长文档放提示词顶部，查询放末尾 → 质量提升可达 30%。引用锚定：要求模型在回答前引用相关文档段落 |
| Google Gemini 3 Guide | "Use XML tags or Markdown headings to clearly separate prompt sections." 关键指令放在 System Instruction 首位。具体查询放在 user prompt 末尾。使用 "Based on the information above..." 锚定上下文 |
| Microsoft | 将提示词分解为 4 组件：Instructions、Primary Content、Examples、Cue。GPT 本质上是补全引擎 — "answer" 只是给定问题输入的最可能补全。提示短语（如 "Key Points:"）可控制输出格式 |

### Community Evidence

Claude Code 的 SKILL.md 模式广泛使用 Markdown 标题 + 列表 + 表格 + 代码块的结构化格式，社区反馈表明此模式显著优于无结构散文。

### Design Implications

1. **每个 skill 使用一致的章节结构**：触发场景 → 核心原则 → 步骤 → 示例 → 约束 → 验证
2. **XML 标签用于动态内容**：需要 LLM 填充或引用的部分使用 `<placeholder>` 标签
3. **关键信息首尾放置**：利用 primacy 和 recency 效应
4. **层级嵌套不超过 3 层**：过深嵌套降低可读性

---

## D4: Step Decomposition

> 将复杂任务分解为明确步骤可提升推理质量和执行可靠性，但并非所有任务都需要同等程度的分解。

### Academic Evidence

| 来源 | 关键发现 |
|---|---|
| **Chain of Methodologies** (Liu et al., Findings of ACL 2025) | 将方法论洞察注入结构化推理过程的迭代提示框架。在复杂推理上优于竞争基线，无需训练 |
| **Watch Every Step** (Xiong et al., EMNLP 2024) | 迭代步骤级过程细化。步骤级指导显著提升 agent 训练效率。使用蒙特卡洛估计进行步骤级奖励评估 |
| **Read Before You Think** (Han et al., arXiv 2025) | 引导 LLM 在思考前逐步阅读的结构化提示族。即使系统提示为空，结构化阅读指导也能显著改善复杂理解 |
| **Think or Step-by-step** (Gohani Sadr, Brock University, 2025) | "Let's think step by step" vs "Let's think" 产生显著不同的内部推理行为。"Step by step" 并非普遍有益 — 取决于任务和模型 |
| **Guiding LLMs via Directional Stimulus Prompting** (Li et al., NeurIPS 2023) | "Let's think step by step using our creative brains" 产生比简单 "think step by step" 更高质量的推理。需要任务特定的刺激短语 |
| **What Should We Engineer in Prompts** (Ma et al., ACM TOCHI 2025) | 30 名提示工程新手的对照实验。结构化提示工程训练导致更具迭代性、结构化的提示行为 |

### Official Guidelines

| 来源 | 指导原则 |
|---|---|
| Anthropic | Claude 4.6 Adaptive Thinking — "Think thoroughly" 通常优于手写逐步计划。但对于 skill 设计，显式步骤仍优先，因为 skill 需要确定性指导 |

### Community Evidence

| 来源 | 关键发现 |
|---|---|
| Cursor Best Practices | Plan-and-Act 策略 — 执行前始终展示包含文件路径的详细实现计划。计划保存至 `.cursor/plans/` |

### Design Implications

1. **步骤数量与任务复杂度匹配**：简单任务 2-3 步，复杂任务 5-8 步
2. **每步一个可验证的输出**：步骤终点应有明确的完成标准
3. **步骤间依赖关系显式声明**：使用"前置条件"/"后续步骤"标注
4. **避免过度分解**：每增加一步都增加上下文消耗和出错概率

---

## D5: Positive Constraints

> 正面约束（"使用 X"）比负面约束（"不要使用 Y"）更可靠地被遵循，这是经过大规模基准测试验证的结论。

### Academic Evidence

| 来源 | 关键发现 |
|---|---|
| **Inverse IFEval** (Zhang et al., ByteDance Seed / Nanjing University / Peking University, arXiv 2025) | 首个反直觉指令大规模基准。1012 个高质量中英文问题，23 个领域，8 种反直觉指令类型。**所有主流 LLM 在反直觉指令上的表现显著差于常规指令**。"反常规格式"（如"不要使用列表格式"）是最难的类型。思考模型（Qwen3-235B-Thinking）远优于非思考模型 — 反思有助于克服 SFT 偏差 |
| **Compact Constraint Encoding** (Tang, arXiv 2026) | 正面约束（"use X"）比负面约束（"don't use Y"）更可靠地被遵循。编码紧凑性与遵从率之间存在权衡 |
| **Constraint Decomposition** (Paunova, Optimization Online 2025) | 将多目标约束分解后，IFEval 基线的 prompt 级准确率从 41.2% 提升至 73.8%（+32.6pp）。消融实验确认约束分解是改进的主要来源 |

### Official Guidelines

| 来源 | 指导原则 |
|---|---|
| Anthropic | "Instead of 'don't use markdown', say 'use flowing prose paragraphs'" |
| Google | "Be precise and direct — avoid unnecessary or overly persuasive language" |

### Design Implications

1. **所有约束转化为正面表述**：`"不要使用 emojis"` → `"使用纯文本，不含 emoji 字符"`
2. **约束分解**：`"遵循代码规范"` → `"使用 TypeScript strict mode"、"函数不超过 20 行"、"所有公共 API 必须有 JSDoc"`
3. **约束分级**：MUST / SHOULD / MAY 区分优先级
4. **反直觉约束需加解释**：当约束违反模型训练偏好时，说明"为什么"

---

## D6: Example Design

> 精心设计的示例是控制 LLM 输出最可靠的机制，但数量并非越多越好——质量和多样性更为关键。

### Academic Evidence

| 来源 | 关键发现 |
|---|---|
| **ACL 2025 Distillation Study** (Chen et al., Findings of ACL 2025) | 1-shot 在灵活性与结构之间取得最佳平衡。更多示例不一定有帮助。教师模型多样性比准确率更重要 |
| **Effect of Prompt Strategy on Code Generation** (Wang, University of Gothenburg, 2025) | 从 zero-shot → few-shot → CoT + role 呈渐进式改进。示例的质量和多样性比数量更重要 |
| **Are Prompts All You Need** (Binkhonain & Alfayez, Requirements Engineering, Springer, 2025) | 最优 few-shot 示例数量因任务复杂度而异。简单任务：1-2 个，复杂任务：5-8 个 |
| **Heart Team Simulation** (Garin et al., European Heart Journal, 2025) | 超过最优数量后，额外示例导致性能下降，原因是注意力稀释 |

### Official Guidelines

| 来源 | 指导原则 |
|---|---|
| Anthropic | 推荐 3-5 个精心设计的示例。使用 `<example>` 标签。示例应相关、多样、结构化 |
| Google Gemini Guide | "We recommend to always include few-shot examples." 即使 2 个示例也能逆转模型偏好 |
| Microsoft | 示例可以展示模型在训练中从未见过的模式。Few-shot 是最可靠的输出控制机制 |

### Community Evidence

| 来源 | 关键发现 |
|---|---|
| Cursor Official Blog (2026-01) | 在 .mdc 文件中包含 Good vs. Bad 示例块，使规则有效性提升约 3 倍 |

### Design Implications

1. **使用 Good/Bad 对照示例**：正反对比比单一正面示例有效 3 倍
2. **示例数量因任务而异**：skill 核心流程 2-3 个，边界情况 1-2 个
3. **示例必须来自真实场景**：合成示例容易被模型识别为"模板"而降低遵从度
4. **示例多样性**：覆盖不同输入类型、不同复杂度级别

---

## D7: Verification Mechanisms

> 没有验证标准的 agent 会产生"看起来对但实际不工作"的输出。验证机制是生产级 AI 工程的基石。

### Academic Evidence

当前维度主要依赖社区实证数据和生产实践证据，学术界尚未有直接针对"agent 内置验证"的大规模研究。以下间接相关：

| 来源 | 关键发现 |
|---|---|
| **Watch Every Step** (Xiong et al., EMNLP 2024) | 步骤级奖励评估 + 蒙特卡洛估计 — 为验证机制提供了理论基础 |
| **Self-Supervised Prompt Optimization** (Xiang et al., arXiv 2025) | LLM 可通过成对输出比较有效评估任务遵从度，无需外部参考。成本仅为现有方法的 1.1%-5.6% |

### Official Guidelines

| 来源 | 指导原则 |
|---|---|
| Anthropic Best Practices | 始终提供验证标准。没有验证标准的 agent 会产生"looks right but doesn't work"的输出 |

### Community Evidence

| Issue | 投票数 | 关键发现 |
|---|---|---|
| Claude Code Issue #42796 | **1,781👍** | "Rush to completion" 定量分析（6,852 sessions, 234,760 tool calls）：Read:Edit 比率从 6.6 降至 2.0（-70%）；每编辑读取率从 93.8% 降至 66.3%；"Simplest" 词频（每千次调用）：2.7 → 6.3（+133%）；过早停止/逃避：0 → 173。根因：(1) Adaptive thinking 分配不足 (2) 默认 effort 降至 medium (3) 系统提示简洁性偏差（~5:1 比例偏好"简单"方案） |

### Production Patterns

| 工具 | 验证模式 |
|---|---|
| Cursor | Plan Mode — 执行前必须展示实现计划（含文件路径），计划保存至 `.cursor/plans/` |
| Aider | 复杂变更以 `/ask` 开始，先讨论计划再编码 |
| Claude Code | Hooks — 可在工具调用前后注入自定义验证逻辑 |

### Design Implications

1. **每个 skill 必须包含验证步骤**：不能只有"做什么"，还要有"怎么确认做对了"
2. **验证标准可自动化**：提供具体的命令或检查清单
3. **防"rush to completion"**：显式要求"完成前必须运行验证"
4. **Read:Edit 比率监控**：设计步骤时确保每步修改前有充分的读取

---

## D8: Freedom Calibration

> 不同任务需要不同程度的自主性。过于严格的约束扼杀创造性，过于宽松的约束导致不可预测的输出。

### Academic Evidence

| 来源 | 关键发现 |
|---|---|
| **NeurIPS 2024 "Teach Better or Show Smarter"** (Wan et al.) | 系统性比较指令优化 vs 示例模仿在自动提示优化中的效果。每种策略的有效性取决于任务类型 — 没有通用赢家 |
| **LLMFacility Framework** (Aslam et al., SSRN 2025) | 核心提示元素的定量评估。角色定义和约束规范显著提升输出质量 |
| **Prompt Patterns for Agile** (Sainio et al., ICSOB 2023/2024) | 清晰的角色定义有助于克服常见项目痛点。输出格式模板进一步收紧输出控制 |

### Official Guidelines

| 来源 | 指导原则 |
|---|---|
| Claude Code Skill Design | "Think of Codex exploring a path: narrow bridge with cliffs needs guardrails (low freedom), open field allows many routes (high freedom)."（想象 Codex 探索路径：悬崖边的窄桥需要护栏（低自由度），开阔原野允许多条路线（高自由度）） |

### Design Implications

1. **按任务类型校准自由度**：
   - 代码生成（确定性高）：低自由度，详细步骤
   - 架构设计（创造性高）：高自由度，原则指导
   - Bug 修复（分析性）：中等自由度，验证优先
2. **用 "MUST/SHOULD/MAY" 分级**：明确哪些是硬约束，哪些是软建议
3. **为创造性任务提供"探索空间"**：使用 "consider"、"evaluate options" 而非 "always do X"

---

## D9: Progressive Loading

> 并非所有指令都需要同时加载。渐进式加载策略可以在保证指令完整性的同时最小化上下文消耗。

### Academic Evidence

当前维度主要基于工程实践，学术界直接相关研究较少。以下间接支撑：

| 来源 | 关键发现 |
|---|---|
| **CFPO** (Liu et al., 2025) | 内容与格式联合优化证明：信息呈现的时机和方式与信息本身同等重要 |
| **LinguaShrink** (Liang et al., 2024) | 心理语言学压缩证明：信息分层呈现可减少认知负担 |

### Community Evidence — Tool Loading Strategies

| 工具 | 核心文件 | 加载策略 | 上下文限制 | 关键模式 |
|---|---|---|---|---|
| **Claude Code** | SKILL.md | 三级渐进：Metadata (~100词, 始终加载) → SKILL.md body (<5k词, 触发时加载) → Bundled resources (无限, 按需加载, 脚本可执行无需上下文加载) | body <5k词 | Two-Phase Retrieval |
| **Cursor** | .mdc files | Glob-scoped rules: Global Rules → Project Rules → Scoped Rules (glob-triggered). 使用 `@include` 跨文件共享 | 无明确限制 | Plan-and-Act, Good/Bad examples |
| **Windsurf** | .windsurfrules | 始终加载。双层：global_rules.md + workspace .windsurfrules | **6000 字符硬限制** | 强制上下文纪律 |
| **Aider** | CONVENTIONS.md | 手动 `/read`。利用 prompt caching。仅添加 1-2 个高相关文件。使用 Repository Map 进行代码库概览，无需手动添加文件 | Prompt caching | Repository Map |
| **Continue.dev** | .continue/rules/ | 自动检测 + Hub | Per agent/chat/edit | Local + Hub rules |

### Community Evidence — Standardization Trend

| Issue | 投票数 | 关键发现 |
|---|---|---|
| Claude Code Issue #41279 | New | 三层分离提案：Skills（任务流程，按需加载）→ Rulebook（持久行为规则，始终活跃，压缩保护）→ CLAUDE.md（项目上下文和偏好，初始加载，压缩后重新注入） |

### Design Implications

1. **三级加载是业界共识**：Metadata → Body → Resources
2. **Metadata 必须自包含**：~100 词内让 LLM 决定是否加载完整 skill
3. **Bundled resources 延迟加载**：大文件、参考文档、脚本不应在触发时全部加载
4. **压缩保护关键规则**：使用 Rulebook 层或 Hooks 确保核心规则在上下文压缩后仍然生效

---

## Cross-Dimension Studies

> 跨维度研究揭示 prompt 工程的整体规律，为 skill 设计提供宏观指导。

### What Makes a Good Natural Language Prompt (Do et al., ACL 2025 Long Paper)

- **规模**：Meta-analysis of 150+ prompt-related papers (2022-2024)
- **贡献**：提出 21 个属性、6 个维度的提示质量评估框架
- **关键发现**：
  - 模型和任务之间在属性支持上存在显著不平衡
  - **单一属性增强往往产生最大影响**（与 D1 触发描述质量直接相关）
  - 没有万能的最佳提示格式 — 任务和模型特定优化至关重要

### Why Prompt Design Matters and Works (Zhang et al., ACL 2025 Long Paper)

- **贡献**：解释为什么某些提示有效而另一些失败的理论框架
- **关键发现**：
  - 提示作为选择器，从隐藏状态中提取任务特定信息
  - 每个提示在答案空间中定义唯一轨迹 — **轨迹选择至关重要**
  - **朴素 CoT ("think step by step") 可能严重损害性能**
  - 最优提示搜索可在推理任务上产生 **>50% 的改进**

### Self-Supervised Prompt Optimization (Xiang et al., arXiv 2025)

- **贡献**：无需外部参考（ground truth 或人工标注）的提示优化
- **关键发现**：
  - LLM 可通过成对输出比较有效评估任务遵从度
  - **成本仅为现有方法的 1.1%-5.6%**
  - 仅需 3 个样本即可匹配/超越 SOTA

### Adaptive Prompt Structure Factorization (Liu et al., arXiv 2026)

- **贡献**：将提示分解为语义因子，使用 Architect 模型发现任务特定的提示结构
- **关键发现**：
  - 干预式单因子评分估计每个因子的边际贡献
  - 错误引导的因子选择将更新路由到当前主要失败源
  - **平均改进 +2.16pp，优化成本降低 45%-87%**

---

## Official Guidelines Comparison

> 六大 AI 供应商的官方提示工程指南对比，揭示行业共识与差异。

| 原则 | Anthropic | Google Gemini | Microsoft | Brex | DAIR.AI |
|---|---|---|---|---|---|
| 清晰/具体 | ★★★★★ | ★★★★★ | ★★★★★ | ★★★★☆ | ★★★★★ |
| 使用示例 | 3-5 个示例，`<example>` 标签 | "Always include few-shot" | 示例可展示未见过的模式 | 嵌入数据 + 引用 | 20+ 提示技术 |
| 结构化提示 | XML 标签分区 | XML 或 Markdown 标题 | 4 组件模型 | 命令语法 | 完整技术目录 |
| 任务分解 | Prompt chaining | Chain/parallel prompts | N/A | ReAct pattern | Prompt chaining |
| 正面表述 | 说 "do X" 而非 "don't Y" | "Be precise and direct" | N/A | N/A | N/A |
| 角色设定 | 即使 1 句话也有帮助 | 放在 system instruction 中 | N/A | N/A | N/A |
| 输出控制 | 格式匹配 | 繁简/语调参数 | Cue phrases | 编程化消费 | 结构化输出 |
| 位置效应 | 关键指令放首尾 | 指令放首位，查询放末尾 | N/A | N/A | N/A |
| 安全性 | 假设隐藏提示可见 | N/A | N/A | 意识越狱/泄露 | N/A |
| 思考模型 | Adaptive Thinking, effort 参数 | N/A | "推理模型不需要" | N/A | CoT, ToT, ReAct |

### 跨指南共识（所有 5+ 指南一致同意）

1. **清晰具体** — 模糊指令产生模糊输出
2. **使用示例** — 少量高质量示例胜过大量低质量示例
3. **结构化** — 清晰分区提升遵从度
4. **任务分解** — 复杂任务需要分解为可管理的步骤

---

## Community Evidence

> 来自生产环境的实证数据，包括高影响力 GitHub Issues 和跨工具对比。

### High-Impact GitHub Issues (Claude Code)

| Issue | 投票数 | 关键发现 |
|---|---|---|
| #6235 - AGENTS.md 标准化 | **3,580👍**, 269💬 | 社区希望跨工具通用 agent 指令格式 |
| #42796 - 复杂工程退化 | **1,781👍** | 定量证明：agent 性能退化（Read:Edit -70%，简洁性偏差 +133%） |
| #45596 - Bring Back Buddy | 654👍 | 社区怀念早期更谨慎的 agent 行为 |
| #3382 - 谄媚行为 | 874👍, 179💬 | Claude 对所有内容都说 "You're absolutely right!"，甚至对 "Yes please" |
| #9716 - Skills 未被识别 | 69👍 | 因 description 缺少触发短语导致 skill 未触发 |
| #18192 - 递归 skill 发现 | 40👍 | 子目录中的 skill 未被找到 |
| #2544 - CLAUDE.md 规则被忽略 | 39👍 | 文件过长时规则被忽略 |
| #41279 - Compaction-Protected Rulebook | New | 三层分离提案：Skills / Rulebook / CLAUDE.md |
| #6354 - 压缩后遗忘 | 27👍 | 关键指令在上下文压缩后丢失 |

### Production-Grade Tool Comparisons

| 工具 | 核心文件 | 加载策略 | 上下文限制 | 关键模式 |
|---|---|---|---|---|
| Claude Code | SKILL.md | 三级渐进 | <5k words body | Two-Phase Retrieval |
| Cursor | .mdc files | Glob-scoped rules | 无明确限制 | Plan-and-Act, Good/Bad examples |
| Windsurf | .windsurfrules | 始终加载 | 6000 chars 硬限制 | Global + Workspace 双层 |
| Aider | CONVENTIONS.md | 手动 /read | Prompt caching | Repository Map |
| Continue.dev | .continue/rules/ | 自动检测 + Hub | Per agent/chat/edit | Local + Hub rules |

### Cross-Tool Standardization Trend

- **SKILL.md 正成为事实标准**：12+ 工具采用（Claude Code, Codex CLI, Gemini CLI, Cursor, OpenClaw, Hermes Agent, Kimi 等）
- **AGENTS.md 运动**（Issue #6235, 3580👍）推动通用格式
- **Anthropic 响应**：在 CLAUDE.md 中使用 `@AGENTS.md` 导入

---

*Last updated: 2025-04-14. Sources verified against original papers, official documentation, and GitHub issue threads.*


path: references/skill-taxonomy.md
content: # Skill Taxonomy Reference

> Evidence-based classification system for AI agent skills.
> Sources: 10 academic papers (CoALA, PromptPrism, etc.) + 5 engineering platforms (Claude Code, Cursor, Superpowers, OpenClaw, Windsurf).

---

## Quick Classification Decision Tree

When classifying a skill, ask these questions in order:

1. **Is it about skills themselves?** (create/optimize/discover skills) → META
2. **Does it wrap an external tool/service?** (database, browser, calculator) → TOOL
3. **Does it enforce a proven method?** (TDD, debugging, verification) → METH
4. **Does it define execution order/phases?** (brainstorming, planning, execution) → PROC
5. **Does it coordinate multiple agents/tasks?** (parallel dispatch, sub-agents) → ORCH
6. **Does it verify/audit work quality?** (code review, completion checks) → QA
7. **Does it provide domain expertise?** (UI design, mobile patterns, framework docs) → KNOW
8. **Does it generate structured output?** (reports, wikis, documentation) → DOC
9. **Does it guide creative output?** (prompt refinement, design ideation) → GEN

**Priority rules when multiple types apply:**
- Safety/Quality first: QA > METH > PROC
- Process before execution: PROC (brainstorming → plans) > METH (TDD)
- Meta skills last: META only on explicit request
- Tools on demand: TOOL only when specific capability is needed
- Domain by context: KNOW only when relevant domain is detected

---

## 9 Skill Types

### PROC — Process Control

- **Definition**: Defines what order tasks should be executed in and which phases they pass through.
- **Design Template**:
  ```markdown
  ## Overview
  [One sentence: what this process does]

  ## When to Use
  - [Scenario 1]
  - [Scenario 2]

  ## Process Flow
  [Numbered steps or Mermaid diagram]

  ## Checklist
  1. [Step 1]
  2. [Step 2]

  ## Decision Points
  [Key branches and conditions]

  ## Transition
  [What to do after the process completes]
  ```
- **Key Elements**: Clear phase boundaries (start → middle → end); completion criteria per phase; decision nodes with branch logic; transition points to other skills; HARD-GATE to prevent skipping steps.
- **Common Pitfalls**: Steps too vague ("analyze code" should be specific sub-steps); no completion criteria; no decision points (every real flow has branches).
- **Examples**: brainstorming, writing-plans, executing-plans, finishing-a-development-branch

---

### METH — Methodology

- **Definition**: Provides proven, reusable methods and principles for engineering activities.
- **Design Template**:
  ```markdown
  ## The Iron Law
  [Core principle in a code block — inviolable]

  ## When to Use
  **Always:**
  - [Mandatory scenarios]
  **Exceptions (ask your human partner):**
  - [Exception scenarios]

  ## Process
  1. [Step 1]
  2. [Step 2]

  ## Anti-Patterns
  | Wrong | Right | Why |
  |-------|-------|-----|

  ## Verification
  [How to verify the method was followed correctly]
  ```
- **Key Elements**: Iron Law in a code block (emotionally salient, impossible to miss); explicit "Always" and "Exceptions"; Anti-Pattern table (wrong vs right + reason); verification steps; positive constraints ("do X" not "don't do Y").
- **Common Pitfalls**: Too many rules (agent selectively ignores); excessive negative constraints (positive constraints are empirically more reliable per Inverse IFEval); no exceptions (causes rigidity); "this is too simple" fallacy (simple tasks still need methodology).
- **Examples**: test-driven-development, systematic-debugging, verification-before-completion, post-dev-verification

---

### TOOL — Tool Integration

- **Definition**: Wraps an external tool, API, or CLI into a reusable agent capability.
- **Design Template**:
  ```markdown
  ## Prerequisites
  [Installation and configuration requirements]

  ## Decision Guide
  | Need | Method | Example |
  |------|--------|---------|

  ## Usage
  ### Basic
  [Simplest usage]
  ### Advanced
  [Complex scenarios]

  ## Error Handling
  [Common errors and solutions]

  ## Verification
  [How to verify the tool works correctly]
  ```
- **Key Elements**: Prerequisites check (don't assume installed); Decision Guide table (what need → what method); progressive usage (simple → complex); error handling guide; script wrappers (deterministic ops, no context consumed).
- **Common Pitfalls**: Assuming tool is pre-installed; only one usage path (missing Decision Guide); incomplete error handling (agent doesn't know what to do on script failure).
- **Examples**: web-access, calculator, db-toolkit, context7-docs-lookup

---

### KNOW — Domain Knowledge

- **Definition**: Provides specialized expertise, conventions, and best practices for a specific domain.
- **Design Template**:
  ```markdown
  ## Configuration
  [Baseline configuration parameters]

  ## Rules
  [Specific, quantifiable rules]

  ## Anti-Patterns / Bias Corrections
  [LLM biases and how to counter them]

  ## Examples
  ### Good
  [Correct approach]
  ### Bad
  [Incorrect approach]

  ## References
  - **Detailed spec**: See [file.md](references/file.md) when [trigger condition]
  ```
- **Key Elements**: Quantifiable rules ("Max 1 Accent Color. Saturation < 80%"); Anti-Patterns for LLM bias correction; Good/Bad contrast examples; progressive loading (core rules in SKILL.md, details in references/); baseline config parameters.
- **Common Pitfalls**: Rules too vague ("write clean code" → needs specific, measurable rules); SKILL.md too long (move details to references/); no bias correction (LLM statistical bias causes generic output).
- **Examples**: design-taste-frontend, mobile-design, openclaw-plugin-dev

---

### GEN — Creative/Generative

- **Definition**: Guides creative output by providing quality standards and inspiration without rigid constraints.
- **Design Template**:
  ```markdown
  ## Principles
  [Creative philosophy and guiding principles]

  ## Quality Bar
  [Quality standards and evaluation criteria]

  ## Freedom Calibration
  [Freedom settings and creative boundaries]

  ## Examples
  [High-quality reference examples]

  ## Process
  1. [Understand requirements]
  2. [Explore approaches]
  3. [Generate output]
  4. [Self-review and refine]
  ```
- **Key Elements**: Principles over rules (High Freedom); quality bar (example-driven standards); freedom calibration (explicit creative boundaries); self-review step (evaluate creative output against requirements).
- **Common Pitfalls**: Too many rules constraining creative space; no quality bar (output quality inconsistent); no self-review (output may drift from requirements).
- **Examples**: prompt-refiner

---

### DOC — Document Generation

- **Definition**: Generates structured documents, reports, or analyses with consistent formatting.
- **Design Template**:
  ```markdown
  ## Report Structure
  [Output document structure specification]

  ## Sections
  ### Section 1: [Title and content requirements]
  ### Section 2: [Title and content requirements]

  ## Output Format
  [Format requirements: Markdown, Mermaid, tables, etc.]

  ## Verification
  [Document completeness checklist]
  ```
- **Key Elements**: Fixed output structure; per-section content requirements; format specification (Markdown, Mermaid, tables); completeness verification checklist.
- **Common Pitfalls**: Unfixed output structure (format inconsistency); no verification step (documents may be incomplete).
- **Examples**: repowiki, project-docs-generator

---

### ORCH — Orchestration

- **Definition**: Manages collaboration between multiple agents, tasks, or resources.
- **Design Template**:
  ```markdown
  ## When to Use
  [Decision flowchart: under what conditions]

  ## Dispatch Strategy
  [How to split and assign tasks]

  ## Sub-agent Prompt Template
  [Template for sub-agent prompts]

  ## Result Aggregation
  [How to collect and merge results]

  ## Error Handling
  [Strategy when sub-tasks fail]
  ```
- **Key Elements**: Decision flowchart (dot format); sub-agent prompt template; result aggregation strategy; error handling and retry logic.
- **Common Pitfalls**: Sub-tasks with dependencies are parallelized; sub-agent prompts lack necessary context; no error handling (one failure cascades to all).
- **Examples**: dispatching-parallel-agents, subagent-driven-development, using-git-worktrees

---

### META — Meta-Skill

- **Definition**: Skills about skills — managing, creating, discovering, and optimizing the skill system itself.
- **Design Template**:
  ```markdown
  ## Core Principle
  [The meta-skill's foundational principle]

  ## Two Modes of Operation
  **MODE A:** [Description]
  **MODE B:** [Description]

  ## Framework
  [Underlying framework or taxonomy the meta-skill operates on]

  ## Anti-Patterns
  [Common errors when using the meta-skill]
  ```
- **Key Elements**: Clear meta-level positioning (skill about skills); multiple operation modes; underlying framework or taxonomy; recursion safety (must not infinitely invoke itself).
- **Common Pitfalls**: Infinite recursion (meta-skill invoking itself); blurred responsibility with managed skills.
- **Examples**: using-superpowers, skill-craft, writing-skills, prompt-refiner

---

### QA — Quality Assurance

- **Definition**: Verifies, audits, and ensures work quality through evidence-based checks.
- **Design Template**:
  ```markdown
  ## The Iron Law
  [Inviolable verification principle: evidence before assertions]

  ## When to Use
  **Mandatory:** [Must-use scenarios]
  **Optional:** [Recommended scenarios]

  ## Verification Steps
  1. [Step 1]
  2. [Step 2]

  ## Failure Protocol
  [What to do when verification fails]

  ## Evidence Requirements
  [What counts as "passing"]
  ```
- **Key Elements**: Iron Law (evidence before assertions always); explicit verification steps; failure protocol; evidence requirements (what proves quality).
- **Common Pitfalls**: Incomplete verification commands (only partial tests run); stale evidence (using cached old results); no failure handling (don't know what to do when checks fail).
- **Examples**: requesting-code-review, receiving-code-review, post-dev-verification, doc-sync-all

---

## Skill Type Combination Patterns

Common tasks and recommended skill combinations:

| Task | Recommended Skills | Order |
|------|-------------------|-------|
| New feature | brainstorming → writing-plans → TDD → verification → code-review | Sequential |
| Bug fix | systematic-debugging → TDD → verification | Sequential |
| Large refactor | brainstorming → writing-plans → parallel-agents → verification | Mixed |
| Frontend work | brainstorming → design-taste-frontend → TDD → verification | Sequential |
| Skill development | skill-craft (CREATE) → skill-craft (OPTIMIZE) | Sequential |
| Research task | web-access + calculator + prompt-refiner | On-demand |
| Documentation | repowiki / project-docs-generator | Single |
| Multi-task parallel | dispatching-parallel-agents → per-task skills → verification | Fan-out/fan-in |
| PR submission | verification → requesting-code-review → finishing-a-branch | Sequential |

---

## Eight Classification Dimensions

Each skill can be tagged: `TYPE:GRANULARITY:AUTONOMY:FREEDOM`

1. **Type** (PROC/METH/TOOL/KNOW/GEN/DOC/ORCH/META/QA) — Core classification of what the skill does.

2. **Granularity** — Atomic (single function, e.g. calculator) / Molecular (multi-step flow, e.g. systematic-debugging) / Composite (composable capabilities, e.g. brainstorming).

3. **Autonomy** — Guided (requires human step-by-step confirmation, e.g. brainstorming) / Supervised (autonomous execution with key-node confirmation, e.g. executing-plans) / Autonomous (fully independent, e.g. verification-before-completion).

4. **Freedom Level** — Low (numbered steps + scripts, strict constraints → best for METH/TOOL) / Medium (preference patterns + parameters → best for PROC/DOC) / High (principles + examples → best for GEN/KNOW).

5. **Loading Level** — L1 (name + description, always loaded, ~100 tokens) / L2 (SKILL.md body, loaded on trigger, <5k tokens) / L3 (references/scripts/assets, loaded on demand).

6. **Statefulness** — Stateless (each invocation independent, e.g. calculator) / Session-state (persists within conversation, e.g. brainstorming) / Persistent (persists across sessions).

7. **Trigger Mode** — Keyword (description keyword match) / Context (task context inference) / Explicit (user explicitly requests) / Always (loaded every conversation, e.g. using-superpowers).

8. **Dependency Complexity** — Standalone (no external deps) / External-Tool (requires external tool/service) / Multi-Resource (requires multiple scripts/references/templates).

**Tag examples:**
- `systematic-debugging` → `METH:Molecular:Supervised:Low`
- `brainstorming` → `PROC:Composite:Guided:Medium`
- `calculator` → `TOOL:Atomic:Autonomous:Low`
- `design-taste-frontend` → `KNOW:Molecular:Supervised:High`
- `skill-craft` → `META:Composite:Guided:Medium`

---

## Key Design Principles

These are empirically supported by the research:

| Principle | Evidence | Impact |
|-----------|----------|--------|
| Keep SKILL.md under 500 lines | Claude Code Issue #2544 (39👍) | Longer skills → lower compliance |
| Use positive constraints ("do X") | Inverse IFEval (ByteDance, 2025) | More reliable than negative ("don't do Y") |
| Good/Bad examples | Cursor official data | ~3x more effective than rules alone |
| 1-shot examples | ACL 2025 | Best flexibility/structure balance |
| Decompose constraints | Constraint Decomposition (2025) | 41.2% → 73.8% accuracy |
| Format + content optimization | CFPO (Fudan/Microsoft, 2025) | +5~38% improvement |
| Iron Law in code blocks | Superpowers practice | Emotionally salient, hard to miss |
| Progressive disclosure (L1→L2→L3) | Claude Code architecture | Tokens are a shared resource |

---

## Sources

### Academic Papers (10)
1. Sumers et al., "Cognitive Architectures for Language Agents" (CoALA), ICLR 2024 Oral
2. White et al., "A Prompt Pattern Catalog to Enhance Prompt Engineering", 2023 (600+ citations)
3. Jeoung et al., "PromptPrism: A Linguistically-Inspired Taxonomy for Prompts", EACL 2026
4. Joyce & Maheshwari, "A Design-Driven Taxonomy of AI Agentic Patterns", IEEE ICAI 2025
5. Fagbohun et al., "An Empirical Categorization of Prompting Techniques", 2024
6. Buyya et al., "Agentic AI: Architectures, Taxonomies, and Evaluation", 2026
7. Li et al., "Towards Secure Agent Skills: Architecture, Threat Taxonomy", 2026
8. Piskala, "Agent, Sub-Agent, Skill, or Tool?", Authorea 2026
9. Gao et al., "A Taxonomy for Human-LLM Interaction Modes", 2025
10. Ng & Fulford, "ChatGPT Prompt Engineering for Developers", DeepLearning.AI 2023

### Engineering Platforms (5)
1. Anthropic Claude Code — Agent Skills Overview & Authoring Best Practices (2025)
2. Cursor — Rules Documentation (2025-2026)
3. obra/superpowers — Five-type classification + nine-dimension optimization framework
4. OpenClaw — Plugin system (Hook/Tool/Provider/Channel)
5. Windsurf — Agent skill patterns

---

*Condensed from the full 1231-line research report. See `/home/leonardo123/docs/superpowers/research/phase3/skill-taxonomy.md` for complete analysis.*


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)