Skill Create Flow

Build a new skill using a repeatable, high-signal workflow that separates methodology discovery from packaging**—without requiring any other skills to be installed or invoked.

Best for

This workflow excels at creating procedural agent skills where the value comes from following a structured methodology rather than raw knowledge retrieval.

Ideal skill types:

• Methodology-based: Debugging, code reviews, writing specs, systematic problem-solving
• Decision-heavy: Architecture decisions, UX design, business strategy, negotiation
• Multi-step workflows: Defined sequence of operations with clear deliverables
• Quality-focused: Where “excellent vs mediocre” output is distinguishable

Less ideal for:

• Pure reference/lookup skills (use knowledge retrieval instead)
• Simple one-shot commands (use direct tool invocation instead)
• Skills requiring external dependencies (this flow produces standalone skills)

Scope & Outputs

You are producing a new skill folder (with its own SKILL.md and optional bundled resources). This flow helps you:

• Narrow the intent until “excellent vs mediocre” is judgeable.
• Extract expert frameworks (when needed).
• Generate a production-ready, testable skill spec and artifacts.

Target artifacts (recommended)

• SKILL.md
• examples/ (1 tiny example)
• tests/ (3–5 eval prompts or scenarios)
• index_entry.json (if you maintain a skill index)
• CHANGELOG.md (optional but helpful for iteration)

Decision Rules (Pick the Track)

Track A — Non-technical / judgment-heavy (default if unsure)

Examples: writing, sales, hiring, product decisions, strategy, negotiation.

Use the full flow below (steps 1–6).

Track B — Technical / objective correctness dominates

Examples: code generation patterns, CLI automation, infrastructure scripts, data pipelines.

Usually shorten Step 2 (“expert frameworks”) and spend more time on Step 5 (“validation”).

Workflow (Standalone)

Step 1 — Lock the intent (narrowing)

Converge from broad → specific using this 5-layer funnel:

1. Domain: what domain is the skill for?
2. Context (5W1H): who/what/where/when/why/how constraints.
3. Comparative choice: pick the closest of 2–3 similar scenarios.
4. Boundaries (via negativa): confirm what is explicitly excluded.
5. Concrete anchor: one real recent case with inputs + desired output.

Deliverable from Step 1

• A 5–10 line “skill brief”:
  • target user + context
  • inputs the user will provide
  • outputs the skill must produce
  • what’s explicitly out of scope
  • quality bar (“excellent output looks like…”)

Step 2 — Extract expert frameworks (masters-level)

Produce:

• 1–3 core frameworks/checklists experts use in this exact scenario.
• Common failure modes + counterexamples.
• Minimal decision rules (when to do A vs B; when to stop; when to ask for more info).

Stop condition

• You can explain the method in a way that is: specific, testable, and not generic advice.

Step 3 — Draft the trigger contract (frontmatter)

Write a frontmatter description that triggers reliably:

• Include 3–6 concrete “when to use” phrases users will actually type.
• Include exclusions if you keep getting false triggers.
• Avoid “does everything”.

Template

---
name: <skill-name>
description: <What it does>. Use when <trigger 1>, <trigger 2>, or <trigger 3>. Avoid when <non-goal>.
---

Step 4 — Write SKILL.md (lean + procedural)

Keep SKILL.md short and procedural:

• Decision rules first.
• Output contract (what files/sections are produced) is explicit.
• Put long templates into references/ if they exceed ~100 lines.

Minimum recommended sections:

• Scope & boundaries
• Inputs (what the user must provide)
• Procedure (step-by-step)
• Decision rules & failure handling
• Output contract
• Test prompts (what you will validate with)

Step 5 — Create supporting artifacts (examples/evals/index/changelog)

A) Tiny example (examples/<name>-example.txt)

• ≤30 lines; show the most common invocation and expected output shape.

B) Evals / test prompts (tests/evals_<name>.yaml) Include 3–5 scenarios:

• happy path
• missing input
• edge case
• out-of-scope
• safety/constraint case (if relevant)

Minimal template:

cases:
  - name: happy_path
    prompt: |
      <a realistic user request that should trigger the skill>
    expect:
      - <must-have output property 1>
      - <must-have output property 2>

C) Index entry (index_entry.json) (only if you keep an index)

{
  "slug": "<skill-name>",
  "name": "<Human title>",
  "summary": "<=160 chars>",
  "entry": "skills/<skill-name>/SKILL.md"
}

D) CHANGELOG.md (optional) Use it if you expect iteration; otherwise skip.

Step 6 — Validate via simulations

Dry-run the new skill against your test prompts:

• Does it trigger when it should?
• Does it avoid false triggers?
• Does it produce the promised output contract?

If it fails, iterate:

• tighten frontmatter description
• move long content into references
• add/adjust decision rules

Prompt Templates

Template 1 — Step 1 (narrowing)

“I want a skill for: . Help me narrow it using this 5-layer funnel: domain → 5W1H → pick closest scenario → boundaries → one real recent case. Ask only the minimum questions (1–3 at a time).”

Template 2 — Step 2 (expert frameworks)

“For the exact scenario we narrowed to, give me 1–3 expert-level frameworks/checklists, decision rules, and common failure modes. Keep it specific and testable (no generic advice).”

Template 3 — Step 4/5 (write artifacts)

“Using the skill brief + frameworks, draft:

1. SKILL.md (lean + procedural),
2. 1 tiny example,
3. 3–5 eval prompts,
4. optional index entry + changelog. Keep templates short; push long templates into references/.”

Notes (Keep It Lean)

• Prefer decision rules over long explanation.
• Prefer one tiny example over many medium ones.
• If you feel tempted to add a long “how skills work” section, don’t—keep the flow operational.