skill-architecture-guide

Skill Architecture Guide

When to use

This skill governs the structural design of a Skill (how files are placed, how references point, how the description is written); it does not cover the TDD creation workflow of a Skill. If the user also needs creation workflow guidance,recommended to use together with skill-creator。

Core principles at a glance

Principle	One sentence
Progressive disclosure	Keep SKILL.md concise, put details in references/, load on demand
Self-Contained	Each reference file does only one thing, read independently by the AI
First-level references	All references start from SKILL.md, do not nest
Directory index	Reference files over 100 lines must have a directory
Brevity is king	Assume the AI is already smart enough, do not add redundant explanations

Quick navigation

Designing the SKILL.md entry: references/frontmatter-and-entry.md

• How to write an accurate Description (with many positive and negative examples)
• How to configure triggers / allowed-tools / preamble-tier
• How to build the intent routing table

Splitting references/: references/file-structure-and-references.md

• When to split files, when to merge
• The 3 organizational patterns of progressive disclosure
• Directory structure conventions for long files

Quality control: references/quality-checklist.md

• SKILL.md checklist
• Reference file checklist
• Description checklist
• Common anti-patterns + how to fix them

Get context

Scenario A: The user wants to create a brand-new Skill

1. Read references/frontmatter-and-entry.md to design metadata and the entry
2. Read references/file-structure-and-references.md to plan the directory structure
3. After producing it, use references/quality-checklist.md for self-checking

Scenario B: The user wants to review/optimize an existing Skill

1. Use references/quality-checklist.md to scan item by item
2. For each problem found, go back to the corresponding reference file to see the fix
3. After fixing one item, continue to the next