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**

```ts
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

```text
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)

1. **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)

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

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

4. **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`:

1. **Frontmatter (Mandatory)**: Metadata for triggering (100 words max)

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

2. **Priority**: P0 (Critical), P1 (Standard), or P2 (Optional)
3. **Structure**: ASCII tree of expected file layout
4. **Guidelines**: Bullet points of "Do this" (imperative)
5. **Anti-Patterns**: Bullet points of "Don't do this"
6. **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)**

1. Define concrete use cases
2. Identify repetitive patterns
3. Calculate token budget per agent

### **Phase 2: Planning (Resource Strategy)**

1. Core workflow → SKILL.md
2. Complex examples → references/
3. Repeated code → scripts/
4. Templates → assets/

### **Phase 3: Implementation (Compression)**

1. Write imperative guidelines
2. Compress examples to essentials
3. Test context window fit

### **Phase 4: Validation (Token Testing)**

1. Verify loading efficiency
2. Test across different agents
3. 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**:

```markdown
❌ 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](references/TEMPLATE.md)

For comprehensive lifecycle guidance:
[references/lifecycle.md](references/lifecycle.md)

For resource organization patterns:
[references/resource-organization.md](references/resource-organization.md)