Skill Creation

Skill Creation

Create skills from simple single-file to complex multi-reference architectures. Each skill must have unique responsibility and be self-sufficient.

When to Use

• Creating new skill from scratch
• Pattern is used repeatedly and AI needs guidance
• Project conventions differ from generic best practices
• Technology has multiple sub-topics requiring organization

Don't create when:

• Pattern is trivial or self-explanatory
• It's a one-off task

Critical Patterns

✅ REQUIRED [CRITICAL]: Read Template Before Creating

ALWAYS read the template FIRST before creating any skill or reference:

# For new skill:
# 1. Read skills/skill-creation/assets/SKILL-TEMPLATE.md
# 2. Copy template
cp skills/skill-creation/assets/SKILL-TEMPLATE.md skills/{skill-name}/SKILL.md

# For new reference:
# 1. Read skills/skill-creation/assets/REFERENCE-TEMPLATE.md
# 2. Follow structure exactly

Why: Templates define canonical structure. Reading them ensures consistency and prevents structural errors.

✅ REQUIRED: Include Trigger in Description

# ✅ CORRECT
description: "TypeScript strict patterns. Trigger: When implementing TypeScript in .ts/.tsx files."

# ❌ WRONG: Missing Trigger
description: "TypeScript strict patterns."

✅ REQUIRED: Frontmatter Structure

---
name: skill-name              # Required: lowercase-with-hyphens
description: "What it does. Trigger: When to activate." # Required: include Trigger
license: "Apache 2.0"         # Optional: for npx distribution
metadata:
  version: "1.0"              # Required: semantic versioning (X.Y or X.Y.Z)
  type: framework             # Required: behavioral|universal|language|framework|library|tooling|domain
  skills:                     # Skill dependencies (see dependencies-matrix.md)
    - react
    - typescript
  dependencies:                # Package version ranges (if applicable)
    react: ">=17.0.0 <19.0.0"
  allowed-tools:               # Optional: only if skill needs specific tools
    - file-operations
---

CRITICAL: The type field determines which dependencies are allowed. See dependencies-matrix.md for type rules.

See frontmatter.md for full field reference.

✅ REQUIRED: Include Inline Examples

Place focused example (<15 lines) after each Critical Pattern showing correct vs incorrect.

✅ REQUIRED: Add Decision Tree

Every skill MUST include a ## Decision Tree section. Content MUST be inside a ``` code fence (no language tag). Rules inside the fence:

1. Conditions at column 0 (no leading spaces)
2. Actions indented with → (2 spaces + Unicode arrow)
3. Use → not -> (ASCII)
4. No markdown links [text](url) — use plain text (see file.md)
5. No inline backtick code — use plain text names
6. No bullet markers (- or * ) at line start
7. Blank line between each condition block

✅ CORRECT

Simple condition?
  → Single action

Complex condition?
  → Step A → Step B → Step C

Parallel options?
  → Option A (if X)
  → Option B (if Y)

❌ WRONG: outside fence, bullet list, ASCII arrows, backticks, links

- **Condition?** -> Use `someApi()`. See [file.md](references/file.md)

✅ REQUIRED: Create References for Complex Skills

When skill has 40+ patterns or 4+ sub-topics:

skills/{skill-name}/
├── SKILL.md (400 lines max)
└── references/
    ├── {sub-topic-1}.md
    └── {sub-topic-2}.md

For complex skills, invoke reference-creation skill.

✅ REQUIRED: Self-Sufficient Content

Don't duplicate universal rules (naming, formatting, accessibility) — they apply everywhere. Include only skill-specific content. Each skill must work on its own without relying on the reader having other skills loaded.

✅ REQUIRED: Token Efficiency

• Omit empty frontmatter arrays/objects
• Description under 150 characters
• Remove filler words ("comprehensive", "detailed")
• Every word must add unique value

See token-efficiency.md for compression strategies.

❌ NEVER: Duplicate Conventions

Don't rewrite rules that already apply universally (naming, formatting). Skills are self-sufficient — include only skill-specific conventions.

✅ REQUIRED: references/ README.md Structure (Complex Skills Only)

When creating references/ directory, ALWAYS include README.md with this 4-section structure:

# [Skill Name] References

## Quick Navigation

| Reference | Lines | Topic |
|-----------|-------|-------|
| [file1.md](file1.md) | ~300 | Brief description |
| [file2.md](file2.md) | ~450 | Brief description |

## Reading Strategy

**Planning new feature:** Read main SKILL.md → file1.md → file2.md → Implement
**Debugging issue:** Read file2.md → file3.md
**Building design system:** Read file1.md, file3.md

## File Descriptions

### file1.md (~300 lines)
Detailed description of what this reference covers...

### file2.md (~450 lines)
Detailed description...

## Cross-Reference Map

**Topic A:** See file1.md → Links to file2.md section X
**Topic B:** See file2.md → Also covered in file3.md

See interface-design/references/README.md for complete example.

Decision Tree

Creating new skill? (CRITICAL FIRST STEP)
  → Read assets/SKILL-TEMPLATE.md BEFORE creating
  → Understand structure: # Title, summary (1-2 lines), ## When to Use, ## Critical Patterns
  → NO "Overview" or "Objective" sections

Creating new reference file?
  → Read assets/REFERENCE-TEMPLATE.md BEFORE creating
  → Follow structure: # Title, summary (1-2 lines), ## Core Patterns
  → NO "Overview" or "Purpose" sections

Complexity?
  → <15 patterns, 1 topic → Simple: SKILL.md only
  → 15-40 patterns, 2-3 topics → Medium: SKILL.md + assets/
  → 40+ patterns, 4+ topics → Complex: SKILL.md + references/ (invoke reference-creation)

Exceeding 300 lines? → Move content to references/
Need templates/schemas? → Create assets/ directory

Determining skill type? (CRITICAL - type determines dependencies)
  → Read references/dependencies-matrix.md for full guide
  → Is it process/methodology (not tech-specific)? → type: behavioral
  → Tech-agnostic workflow orchestration? → type: universal
  → Programming language (JS, TS, Python)? → type: language
  → Framework (React, Express, Next)? → type: framework
  → Library (MUI, Redux, Zod)? → type: library
  → Dev tool (Vite, Jest, ESLint)? → type: tooling
  → Domain knowledge (a11y, CSS, patterns)? → type: domain

Determining dependencies based on type?
  → Read references/dependencies-matrix.md for type-specific rules
  → behavioral → Can ONLY depend on other behavioral (prefer NONE)
  → universal → Can ONLY depend on behavioral
  → language → Prefer NONE (self-sufficient)
  → framework → Can depend on framework, language, domain, behavioral
  → library → Can depend on library, framework, language, domain, behavioral
  → tooling → Can depend on what it wraps
  → domain → Prefer NONE (or related domain, behavioral)

Check for transitive redundancy? (CRITICAL)
  → Does any current dependency already provide what you need?
  → If YES → Remove redundant dependency
  → If NO → Keep it
  → Example: ag-grid depends on react → Gets javascript + a11y transitively

After creation? → Run ai-agents-skills sync or make sync

Workflow

1. Assess complexity → Determine simple/medium/complex (see Decision Tree)
   • Checkpoint: ✅ Complexity level determined, structure chosen
2. Create structure → mkdir skills/{name} + copy SKILL-TEMPLATE.md
   • Checkpoint: ✅ Directory exists, template copied
3. Determine type and dependencies → Identify skill type (behavioral/universal/language/framework/library/tooling/domain), then determine dependencies per dependencies-matrix.md
   • Checkpoint: ✅ Type correctly identified, dependencies follow type rules, no transitive redundancies
4. Fill template → Frontmatter (name, description+Trigger, version, type, skills), all required sections
   • Checkpoint: ✅ Frontmatter complete with type field, description includes Trigger, dependencies verified
5. Add patterns → Critical Patterns with inline examples, Decision Tree, Edge Cases
   • Checkpoint: ✅ Each pattern has ✅/❌ example, Decision Tree covers all cases, no duplication
6. Validate and sync → Run ai-agents-skills validate --skill {name} then make sync
   • Checkpoint: ✅ Validation passes, skill synced to model directories, SKILL.md under 300 lines (complex)

Example

See examples.md for complete examples:

• Simple skill (Prettier, <15 patterns)
• Medium skill (Formik, 15-40 patterns)
• Complex skill (React, 40+ patterns with references/)

Edge Cases

Migrating to complex: If skill grows beyond 40 patterns, invoke reference-creation skill. Keep top 10-15 patterns in SKILL.md, move rest to references/. REQUIRED: Create README.md in references/ with 4 sections: Quick navigation table (with line counts), Reading strategies by use case, File descriptions, Cross-reference map. See interface-design/references/README.md and tailwindcss/references/README.md for examples.

Version-specific patterns: Use references/current.md, references/legacy.md, references/migration.md. For major versions (e.g., Tailwind v3 → v4), create dedicated migration guide with breaking changes table.

Transversal topics: Create separate reference file, link from multiple patterns. Examples: design-system.md for token hierarchy patterns (brand → semantic → component), dry-principle.md for DRY across frontend/backend.

Checklist

Before finalizing any skill:

Structure & Frontmatter

• Directory under skills/ (lowercase-with-hyphens)
• Based on SKILL-TEMPLATE.md
• name and description (with Trigger) present
• metadata.version set — new skill starts at 1.0; minor update → 1.x; breaking change → 2.0
• metadata.type set (behavioral|universal|language|framework|library|tooling|domain)
• metadata.skills follows type rules from dependencies-matrix.md
• No transitive redundancies (verified against dependency chains)
• Empty arrays/objects omitted
• Complex skills: references/ directory created

Content

• H1 title is the topic name only — no "Skill" suffix (e.g., # React, not # React Skill)
• When to Use (with Don't use when)
• Critical Patterns with ✅/❌ markers and inline examples (<15 lines each)
• Decision Tree: inside ``` fence, → arrows, no links/backticks/bullets inside fence
• Example section
• Edge Cases
• --- separator between every major ## section (except before the first)
• No decorative emojis in headings (✅ ❌ ⚠️ are allowed; pictographic emoji are not)
• Delegates to code-conventions/a11y/humanizer (not duplicated)

Quality

• Token-efficient (no filler, every word adds value)
• SKILL.md under 300 lines (complex skills)
• All referenced skills exist
• Synced to model directories

Resources

• SKILL-TEMPLATE.md - Main skill template
• assets/frontmatter-schema.json - Validation schema (reference only, not enforced by CLI)
• Agent Skills Spec - Official specification