Skill Creator

Agent Skill Creator Standard

Priority: P0 (CRITICAL)

Strict guidelines for authoring High-Density Agent Skills. Maximize information density while minimizing token consumption through progressive disclosure and strategic content organization.

Core Principles

Token Economy First ⚡

Every word costs tokens. Design skills for maximum information/token ratio:

• Progressive Loading: Load only essential content initially
• Lazy References: Move detailed examples to references/ folder
• Imperative Compression: Use verbs, abbreviations, bullet points
• Context Window Awareness: Design for 4k-32k token limits across agents

Three-Level Loading System

Level 1: Metadata (100 words) → Always loaded
Level 2: SKILL.md Body (100 lines) → When triggered
Level 3: References/Scripts/Assets → As needed

Directory Structure

skills/
└── {category}/                     # e.g., "flutter" (lowercase)
    └── {skill-name}/               # e.g., "bloc-state-management" (kebab-case)
        ├── SKILL.md                # Core Logic (High Density, <100 lines)
        ├── scripts/                # Executable code (Deterministic tasks)
        │   └── automation.py
        ├── references/             # Heavy Examples (Lazy loaded)
        │   ├── patterns.md
        │   └── examples.md
        └── assets/                 # Output templates (Never loaded)
            └── template.json

Writing Rules (Token-Optimized)

• Imperative Compression: Start with verbs. No "Please/You should".
• _Waste_: "You should use BLoC for state management." (8 words)
• _Efficient_: "Use BLoC for state management." (5 words)

• Token Economy: Maximize info/token ratio.
• Skip articles ("the", "a") if readable
• Use standard abbreviations (cfg, param, impl)
• Bullet points > paragraphs (3x density)

• Progressive Disclosure: Essential info first, details on-demand.
• Core workflow in SKILL.md
• Complex examples in references/
• Templates/assets never loaded

• Context-Aware Design: Different agents have different limits.
• Cursor: ~100k tokens
• Claude: ~200k tokens
• Windsurf: ~32k tokens

Content Sections (Token-Budgeted)

Required sections in SKILL.md:

• Frontmatter (Mandatory): Metadata for triggering (100 words max)

   ---
   name: Skill Name
   description: What it does + when to use it (triggers activation)
   metadata:
     labels: [tag1, tag2]
     triggers:
       files: ['**/*.ext']
       keywords: [term1, term2]
   ---

• Priority: P0 (Critical), P1 (Standard), or P2 (Optional)
• Structure: ASCII tree of expected file layout
• Guidelines: Bullet points of "Do this" (imperative)
• Anti-Patterns: Bullet points of "Don't do this"
• Reference Links: Links to references/ files (lazy loading)

Size Limits (Strict)

| Element | Limit | Action if Exceeded |

| -------------------------- | --------- | ------------------------ |

| SKILL.md total | 100 lines | Extract to references/ |

| Inline code block | 10 lines | Move to references/ |

| Anti-pattern item | 15 words | Compress to imperative |

| Description after Priority | 0 lines | Remove (use frontmatter) |

| Tables | 8 rows | Extract to references/ |

| Explanatory sections | 10 lines | Extract to references/ |

Resource Organization (Token-Saving)

scripts/ - Executable Code

When to use: Deterministic, repeated tasks

Benefits: Never loaded into context, executed directly

Examples: Code generators, formatters, validators

references/ - Documentation

When to use: Detailed examples, API docs, complex patterns

Benefits: Loaded only when needed, keeps SKILL.md lean

Examples: Implementation patterns, error handling guides

assets/ - Output Templates

When to use: Boilerplate files, images, configs

Benefits: Never loaded, copied to output as-needed

Examples: Project templates, config files, icons

Skill Creation Lifecycle

Phase 1: Understanding (Token Audit)

• Define concrete use cases
• Identify repetitive patterns
• Calculate token budget per agent

Phase 2: Planning (Resource Strategy)

• Core workflow → SKILL.md
• Complex examples → references/
• Repeated code → scripts/
• Templates → assets/

Phase 3: Implementation (Compression)

• Write imperative guidelines
• Compress examples to essentials
• Test context window fit

Phase 4: Validation (Token Testing)

• Verify loading efficiency
• Test across different agents
• Measure token consumption

Validation Checklist

Before finalizing, verify:

• [ ] SKILL.md ≤100 lines (ideal: 40-60)
• [ ] No inline code >10 lines
• [ ] No repeated frontmatter content
• [ ] Anti-patterns use strict format (see below)
• [ ] Complex examples in references/
• [ ] Tables >8 rows moved to references/
• [ ] No description redundancy after Priority

Anti-Patterns (Token Wasters)

• Verbose Explanations: "This is important because..." → Delete
• Redundant Context: Same info in multiple places
• Large Inline Code: Move code >10 lines to references/
• Conversational Style: "Let's see how to..." → "Do this:"
• Over-Engineering: Complex structure for simple skills
• Redundant Descriptions: Do not repeat frontmatter description after ## Priority
• Oversized Skills: SKILL.md >100 lines → Extract to references/
• Nested Formatting: Avoid Bold: \More Bold\ - causes visual noise
• Verbose Anti-Patterns: See strict format below

Anti-Pattern Format (Strict)

Format: No X: Do Y[, not Z]. [Optional context, max 15 words total]

Examples:

❌ Verbose (24 words):

- **No Manual Emit**: `**Avoid .then()**: Do not call emit() inside Future.then; always use await or emit.forEach.`

✅ Compressed (11 words):

- **No .then()**: Use `await` or `emit.forEach()` to emit states.

❌ Verbose (18 words):

- **No UI Logic**: `**Logic in Builder**: Do not perform calculations or data formatting inside BlocBuilder.`

✅ Compressed (9 words):

- **No Logic in Builder**: Perform calculations in BLoC, not UI.

Progressive Disclosure Checklist

Extract to references/ when:

• [ ] Code examples >10 lines
• [ ] Tables >8 rows
• [ ] Explanatory sections >10 lines
• [ ] Multiple code variants/alternatives
• [ ] Detailed performance benchmarks
• [ ] Step-by-step tutorials

Reference & Examples

Use the enhanced template below to generate new skills:

references/TEMPLATE.md

For comprehensive lifecycle guidance:

references/lifecycle.md

For resource organization patterns:

references/resource-organization.md