Agent Skill Creator Standard

Priority: P0 (CRITICAL)

Strict guidelines for High-Density Agent Skills. Maximize info/token ratio.

Core Principles (Token Economy First ⚡)

• Progressive Loading: Load only essential content initially.

• Lazy References: Move detailed examples to references/ .

• Imperative Compression: Use verbs, abbreviations, bullet points.

• Context Limits: Cursor(~100k), Claude(~200k), Windsurf(~32k).

Three-Level Loading System

• Metadata: Triggers → AGENTS.md index (Proactive Activation)

• SKILL.md: Body < 100 lines → Core guidelines (When triggered)

• Resources: references/ , scripts/ , assets/ → Deep knowledge (On-demand)

Writing Rules

• Imperative: Start with verbs. "Use BLoC" not "You should use BLoC".

• Token Economy: Skip articles. Use standard abbreviations. Bullets > paragraphs.

• Structure:

• Mandatory Frontmatter (YAML: name, description, metadata labels & triggers).

• Priority: P0 (Critical), P1 (Standard), P2 (Optional).

• Guidelines: Imperative Do's.

• Anti-Patterns: Strict format Don'ts.

• References: Links to lazy-loaded files.

Strict Size Limits

Element Limit Action if Exceeded

SKILL.md total 100 lines Extract to references/

Inline code block 10 lines Extract to references/

Anti-pattern item 15 words Compress to imperative

Tables 8 rows Extract to references/

Strict Formatting Rules

• Anti-Patterns: No X: Do Y[, not Z]. [Context <= 15 words]

• Example: No Logic in Builder: Perform calculations in BLoC, not UI.

• No Redundancy: Do not repeat frontmatter descriptions.

• Oversized Skills: If SKILL.md >100 lines, extract step-by-step guides and complex scenarios to references/ .

• Nested Formatting: Avoid Bold:
  More Bold``.

Test, Measure & Iterate

After writing a skill draft, validate it before shipping:

• Write eval cases: Create evals/evals.json with 2–3 realistic prompts (see testing.md).

• Design trigger queries: Generate 8–10 should-trigger and 8–10 should-not-trigger queries to measure description accuracy.

• Optimize description: Make it "pushy" — list explicit trigger contexts, not just what it does.

• Catch regressions: Snapshot the skill before editing; compare before/after outputs for existing test cases.

• Iterate: Re-run evals after each change; stop when trigger rate ≥ 80% on held-out queries.

See Testing, Trigger Rate & Regression Guide for eval schema, query design rules, and regression protocol.

Resources & Deep Knowledge

• Resource Organization & Directory Structure

• Skill Creation Lifecycle

• Anti-Patterns Details

• Creation Template

• Testing, Trigger Rate & Regression Guide