skill-creator

Files (45)

• LICENSE.txt
• SKILL.md
• analyzer.md · agents/
• comparator.md · agents/
• grader.md · agents/
• eval_review.html · assets/
• README.md · docs/
• generate_review.py · eval-viewer/
• viewer.html · eval-viewer/
• category-playbook.md · references/
• cross-gate-tradeoffs.md · references/
• delegation-conversion.md · references/
• dependency-preflight.md · references/
• description-guide.md · references/
• description-optimization.md · references/
• environment-modes.md · references/
• eval-loop.md · references/
• exemplars.md · references/
• frontmatter-rules.md · references/
• human-review-audit.md · references/
• human-review.md · references/
• improving-existing.md · references/
• intent-interview.md · references/
• iteration.md · references/
• predictability-audit.md · references/
• predictability-rubric.md · references/
• readme-template.md · references/
• report-template.md · references/
• retrofit-loop.md · references/
• run-stats.md · references/
• schemas.md · references/
• skill-standard.md · references/
• subagent-patterns.md · references/
• validation-prompts.md · references/
• writing-guide.md · references/
• __init__.py · scripts/
• aggregate_benchmark.py · scripts/
• generate_report.py · scripts/
• improve_description.py · scripts/
• init_skill.py · scripts/
• package_skill.py · scripts/
• quick_validate.py · scripts/
• run_eval.py · scripts/
• run_loop.py · scripts/
• utils.py · scripts/

SKILL.md (first lines)

# Skill Creator

A skill for creating new skills and iteratively improving them. The agent's context budget is the primary constraint, so this SKILL.md links out to focused reference files.

The core loop:

1. Decide what the skill should do and how it should do it
2. Write a draft
3. Run test prompts against claude-with-access-to-the-skill
4. Evaluate results with the user (qualitative review via `eval-viewer/generate_review.py`, plus quantitative evals)
5. Revise the skill based on feedback and benchmarks
6. Repeat until satisfied; expand the test set and try again at scale

Identify where the user is in this loop and jump in there. New skill from scratch → start at step 1. Existing draft → jump to step 3 or 4. User wants to vibe-iterate without formal evals → support that. After the skill stabilizes, optionally run the description improver to optimize triggering.

## Two entry paths

The skill supports two distinct workflows. **Identify which one the user is on before you do anything else** — they don't share a starting step.

- **Path A — Create a new skill from scratch.** The user wants to capture a workflow, codify a pattern, or build a new capability. Start at **"Creating a skill"** below (Capture Intent → Interview → Write SKILL.md → Test → Eval).
- **Path B — Improve an existing skill.** The user points to a skill that already exists and wants it brought up to standard, fixed, optimized, or iterated based on eval feedback. **Do not start with Capture Intent** — the intent is already encoded in the existing SKILL.md. Start at **"Improving an existing skill"** below.

If the request is ambiguous ("can you look at this skill?"), assume **Path B** and confirm before interviewing as if it were new. Path B also fires when `/skill-creator` is invoked on a skill directory or file.

Both paths share the mandatory rules below: **Repo Sync Before Edits**, **Dependency Preflight**, **Version Management**, **YAML Frontmatter Safety**, and **Frontmatter Audit on Review/Evaluation**. Both close with the **Run stats** block. Both paths end at the same skill standard.

## The skill standard (both paths)

One bar for a created skill and an updated one — `references/skill-standard.md` holds the detail:

- **Gate 1 — must-pass floor.** `quick_validate.py` clean, the Frontmatter Audit, body under 500 lines and 3000 words, a negative-trigger clause, version and author, the README notice, script errors, dependency preflight when another skill is invoked, and the five human-review checks.
- **Gate 2 — asm-eval floor.** `overallScore > 85` AND `min(categories) >= 8`.

PASS only when both gates pass; anything else after the loop caps is a BLOCKER naming each failing check. Without `asm` on PATH, Gate 2 is **not measured** and the run never reports PASS. The predictability rubric stays advisory on both paths.

## Step Completion Reports

After each major step, print a compact status block — `√` pass, `×` fail, `—` context, a `Criteria` line, and a `Result: PASS | FAIL | PARTIAL` line — with checks tied to commands, file states, or counts. The block format and the per-phase checks (Intent Capture, Skill Writing, Testing, Iteration, Closing check) are in `references/writing-guide.md` → _Step Completion Reports_.

## Run stats (mandatory)

Every run that creates or updates a skill closes its summary with a run-stats block — the last thing printed, after the final Step Completion Report. It reports what the run **cost**, and nothing the run already reported.

Capture `run_started_epoch` **once**, in the same shell as the skill's first command — `cmd; ec=$?; date +%s >&2; exit "$ec"` — reading the epoch off stderr so stdout and the exit code stay intact. Set it there, not later: without the anchor `elapsed` prints `n/a`, and the block still has to print on an early stop.

```
  ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
  Run stats   elapsed 6m 04s · tokens 128,400 · cost $0.42
              agents 3 · skills 1 · tool calls 47
```

Fields are fixed and in this order — never reordered, renamed, or added to: `elapsed`, `tokens`, `cost`, `agents`, `skills`, `tool calls`. Per-field formatting: `references/run-stats.md`.

- **`tokens` and `cost` are omitted entirely when the host reported no figure** — no dangling `·`, no placeholder. Never estimate one, and never reconstruct one from host transcripts or logs.
- **`elapsed`, `agents`, `skills`, and `tool calls` always print.** A value that cannot be determined prints the literal `n/a`; `0` is a determined value and is correct where it is true (a run that spawned no subagents prints `agents 0`).
- A missing optional figure never suppresses the rest of the block.

Print it on **every** path that finishes a create or update — Path A, Subpath B1, Subpath B2, and Subpath B3 — and at **every** terminal outcome: a PASS, a BLOCKER, the Phase 0 early exit, a failed prerequisite, an aborted run. Only a run that produced no output at all has no block.

## Communicating with the user

Users span a wide range of technical familiarity. Match jargon to context cues — terms like "JSON" or "assertion" need evidence the user knows them; briefly define terms when in doubt.

---

## Mandatory Rule for Repo-Mutating Skills

When creating or updating any skill that changes files in a git repository (code, docs, config, commits, publishing), include this rule in that skill's SKILL.md:

- Add a **"Repo Sync Before Edits (mandatory)"** section near the top requiring `branch="$(git rev-parse --abbrev-ref HEAD)"; git fetch origin && git pull --rebase origin "$branch"` before modifications.
- If the working tree is dirty: stash, sync, then pop.
- If `origin` is missing or conflicts occur: stop and ask the user before continuing.

Do not ship repo-mutating skills without this pre-sync guardrail.

## Mandatory Rule for Skills That Invoke Other Skills

Establish, for every skill you author or retrofit, whether it invokes, delegates to, or reads **another skill**. Ask it in the interview — _Does this skill invoke other skills?_ is Capture Intent question 6 — and confirm the answer against the draft: prose naming `/another-skill`, or a read under `~/.claude/skills/`, is a dependency even when the author said there were none.

- **It does** → declare each optional dependency in the frontmatter `dependencies` list and ship a `## Dependency Preflight (mandatory)` section above the first step that changes anything. The main agent acquires only a dependency whose branch it reaches with `asm deps acquire ... --session <caller-session-id>`, uses the returned path directly, and releases the session in caller-owned `finally`/shutdown handling.
- **It does not** → add nothing. No empty preflight section, no "no dependencies" placeholder.

Read `references/dependency-preflight.md` for the copyable template and the on-miss behavior. The skill standard's Gate 1 checks this same rule on both paths, so a skill that ships without a required gate fails its closing check.

## Frontmatter rules (mandatory)

Read `references/frontmatter-rules.md` for the full mandatory rules:

- **Version Management** — set `metadata.version: 1.0.0` on creation; bump patch/minor/major on every edit.
- **YAML Frontmatter Safety** — double-quote any string value containing YAML-special characters (full list in the reference).
- **Frontmatter Audit on Review/Evaluation** — required-field check, name/dir match, allowed top-level keys, `metadata.version`, `metadata.author`, YAML safety, and consistency with `docs/README.md`. Run `python scripts/quick_validate.py <skill-path>` first; it catches mechanical issues without LLM reasoning.

These rules apply on every write. Always confirm them before saving.

## Creating a skill

### Capture Intent

Read `references/intent-interview.md` and work it top to bottom. It carries:

- **The gate** — a skill earns its place only when the workflow is repeated, non-obvious, and stable. Recommend against creating it otherwise; the user can override.
- **The seven interview questions** — purpose, triggers, the expected output format, test cases, subagents (including per-step context delegation), skill dependencies, and model-invoked vs. user-invoked (`/skill-name` is orchestration the user runs deliberately — a pipeline, or an expensive or destructive action they confirm first).
- **Interview and research** — edge cases, example files, success criteria, available MCPs.
- **Branch mapping before drafting** — name the distinct modes the skill runs in, so branch-specific material is disclosed only on the branch that uses it.

Extract what the conversation already answers before asking the user anything; they fill the gaps and confirm.

### Write the SKILL.md

Before drafting, skim `references/exemplars.md` and imitate the archetype closest to this skill — workflow, knowledge, or orchestrator. Then, based on the user interview, fill in:

- **name**: 1-64 chars, lowercase letters/digits/hyphens, no consecutive hyphens, exactly matches parent directory. Enforced by `scripts/quick_validate.py`.
- **description**: When to trigger and what it does. Primary triggering mechanism. Single line, no newlines. Claude tends to _undertrigger_ — make descriptions a little "pushy", with negative triggers.
- **effort** (optional): `low | medium | high | xhigh | max`. Defaults to `high`.
- **metadata.version**: Semver string (see frontmatter rules).
- **compatibility**: Required tools or dependencies (rare).

#### Writing a good description

From luongnv89/asm, MIT.

More from luongnv89/asm