skill-conductor

Skill Conductor

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

One master discipline to govern skill creation and optimization, rooted in the 10 canonical authoring principles.

Core Invariants & The 10 Canonical Authoring Principles

Pre-flight verification: Check dependencies and environment before executing workflows.
No process in descriptions: Descriptions define triggering boundaries (Use when..., Do NOT use for...), never workflow recipes.
Map of Content (MOC): SKILL.md is a clear architectural map (< 500 lines) pointing to modular references.
Fresh practitioner empathy: Explain the rationale behind steps so agents understand context.
Training Within Industry (TWI): Structure critical instructions as Action, Key Point, and Why.
Blind agent testability: Ensure instructions are unambiguous when executed without prior conversation history.
Inline risk checklists: Place verification checklists directly at high-risk seams.
One term per concept: Use consistent domain terminology throughout.
Zero secrets / environment cleanliness: Never hardcode credentials, tokens, or absolute user home paths.
Match form to failure: Counter specific failure modes with targeted structural constraints and anti-rationalization tables.

Mode	Trigger / Context	Key Output
1. CREATE	"build a skill", "new skill for..."	Full lifecycle: intent → architecture → scaffold → write → eval
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", quality audit	11-point quality gate assessment
5. OPTIMIZE	"improve triggering", "optimize description"	Automated description optimization with train/test splits
6. PACKAGE	"package for distribution"	Validation + bundle into release artifact

Action: Extract 2–3 concrete user scenarios and establish positive and negative trigger boundaries.
Key Point: Specify exact phrases users say and adjacent domains the skill must reject.
Why: Clear boundaries prevent undertriggering and false-positive overtriggering.

Action: Select the architectural pattern (sequential, iterative, context-aware) and structure files.
Key Point: Keep SKILL.md concise (< 500 lines) and push heavy schemas or tables into references.
Why: Bloated instruction files exhaust attention budgets and degrade execution quality.

Action: Draft YAML frontmatter with kebab-case name and trigger-rich description, followed by MOC, TWI steps, and guardrails.
Inline Checklist:
- Frontmatter name matches directory name
- Description is $\le 1024$ characters and contains no process steps
- Negative triggers specified (Do NOT use for...)
- Anti-rationalization table included
- No hardcoded tokens, passwords, or machine-specific paths

Action: Evaluate across Discovery, Clarity, Structure, Robustness, Completeness.
Key Point: Pass every critical gate check before declaring release readiness.
Why: Multi-dimensional evaluation catches hidden failure modes before distribution.

Tempting Rationalization	Binding Rule	Engineering Rationale
"Putting steps in the description helps the model."	Forbidden: zero process in description.	Models follow description steps and skip the comprehensive body instructions.
"The skill is small, so negative triggers are unneeded."	Mandatory negative triggers in description.	Without negative boundaries, skills trigger falsely on loosely related queries.
"One big 1200-line markdown file is easier to manage."	Progressive disclosure: SKILL.md < 500 lines.	Overloaded contexts dilute attention and lead to instruction-skipping.
"We can skip testing if the markdown looks clean."	Trigger evaluation on positive and negative test cases.	Clean prose can still fail in actual agent routing.