/skill-conductor

name: skill-conductor
description: >
  Create, edit, evaluate, and package agent skills. Use when building a new
  skill from scratch, improving an existing skill, fixing a skill that never
  triggers or fires unreliably, running evals to test a skill, benchmarking
  skill performance, optimizing a skill's description, reviewing third-party
  skills for quality, or packaging skills for distribution — even if the user
  doesn't explicitly say "skill" (e.g. "teach Claude to do X", "make the
  agent always follow Y"). Not for using skills or general coding
  tasks.

Skill Conductor

Full lifecycle management for agent skills: **draft → test → review → improve → repeat**.

One skill to rule them all — from architecture to packaging. The core loop is always the same: write something, test it, see what fails, fix it, test again.

Runtime requirements (pre-flight)

Before any mode that touches scripts (CREATE, IMPROVE, VALIDATE, OPTIMIZE, PACKAGE), run the pre-flight block → **`references/runtime-setup.md`** (checks `uv`, sets `UV_BIN`/`SKILL_CONDUCTOR_DIR`, verifies LLM access). If `uv` is absent, stop and tell the user.

How to communicate

Read context cues. If the user is a skill author iterating on their own work, be direct and technical. If they're new to skills, explain the _why_ behind each step — not just what to do, but why it matters. Default to conversational, not robotic.

• Explain trade-offs when there's a real choice to make
• Use concrete examples over abstract rules
• When something fails, explain the root cause, not just the fix
• Imperative voice in instructions: "Extract the data", not "You should extract"

Modes

Detect mode from context. If ambiguous, ask.

| Mode | When | What happens | | ----------- | ------------------------------------------------ | --------------------------------------------------------------- | | 1. CREATE | "build a skill", "new skill for..." | Full lifecycle: intent → architecture → scaffold → write → test | | 2. IMPROVE | "fix this skill", "it doesn't trigger" | Diagnose → eval loop → gated self-update → iterate | | 3. VALIDATE | "test this skill", "run evals" | Structural checks + trigger testing + BinEval scoring | | 4. REVIEW | "review this skill", third-party assessment | 11-point quality gate, quick and focused | | 5. OPTIMIZE | "improve triggering", "description optimization" | Automated description optimization with train/test split | | 6. PACKAGE | "package for distribution" | Validate + bundle into .skill file |

---

Mode 1: CREATE

Step 1: Capture Intent

Before writing anything, extract 2–3 concrete scenarios.

Ask:

• "What specific task should this skill handle?"
• "What would a user say to trigger it?"
• "What should NOT trigger it?"

Don't move on until you have a clear picture of what the skill does, for whom, and when. This prevents the most common failure: a skill that does _something_ but triggers for the wrong things.

Step 2: Baseline (TDD RED)

Before writing the skill, verify the agent fails without it:

1. Take one scenario from Step 1 2. Run it in a clean session without the skill 3. Document what went wrong — what the agent guessed, what it missed

If the agent already handles it perfectly, the skill is unnecessary. This sounds obvious, but it's the most skipped step and the most valuable one.

Step 3: Architecture

Choose a primary pattern from `references/patterns.md` (can combine):

| Pattern | Use when | | ----------------------- | ---------------------------------------- | | Sequential workflow | clear step-by-step process | | Iterative refinement | output improves with cycles | | Context-aware selection | same goal, different tools by context | | Domain intelligence | specialized knowledge beyond tool access | | Multi-MCP coordination | workflow spans multiple services |

Choose degrees of freedom — this determines how much control vs. flexibility the skill gives the agent:

| Freedom | When | Example | | ------------------- | ------------------------------------------- | ----------------------- | | Low (scripts) | fragile, error-prone, must be exact | PDF rotation, API calls | | Medium (pseudocode) | preferred pattern exists, some variation ok | data processing | | High (text) | multiple valid approaches, judgment needed | design decisions |

**Freedom test:** ask "if the agent makes a mistake here, what is the consequence?" High consequence → low freedom (an exact script it must not modify). Low consequence → high freedom (prose, let it judge). Calibrate per step, not per skill — one skill can hold both.

**Golden rule: read `references/sop-practices.md` before authoring or reviewing ANY skill.** It holds the canonical **10 authoring principles** (universal): pre-flight, no-process-in-description, MOC (SKILL.md = map, not prose), fresh-practitioner author, TWI "why", blind-agent test, inline checklists, one-term-per-concept, cut-the-fat (env/keys OUT of SKILL.md), match-the-form-to-the-failure. For **procedural** skills (business process with branching: request, quote, onboarding, escalation) the same file also has the deep SOP methodology — format selection, 7-step process, procedural checklist.

Step 4: Scaffold

uv run scripts/init_skill.py <skill-name> --path <output-dir> [--resources scripts,references,assets]

Or create manually:

skill-name/
├── SKILL.md          # required — the brain
├── scripts/          # deterministic operations (executed, not loaded)
├── references/       # detailed docs (load