Skill Builder

Calibration: Tier 2, Opus-primary. See repository README for model compatibility.

Version 3.0: Methodology + tooling release. D9 expanded into D9a/D9b/D9c sub-levels (empirical Tier A / empirical Tier B / analytical floor). Adds Description Refinement Loop methodology (manual or automated via scripts/description_optimizer.py). Adds Tier A/B/C environment-adaptive degradation. Adds executable layer (scripts/, agents/, eval-viewer/) ported from upstream Anthropic skill-creator with content-class-policy adaptation. v2.1 build methodology preserved verbatim where unchanged.

Build, review, revise, test, and optimize root.node Skills in the SKILL.md format for the Anthropic Agent Skills ecosystem. This Skill carries the complete build methodology — Agent Skills spec, conversion rules, progressive disclosure patterns, pre-build gates, the 9-dimension quality gate (with sub-level evidence tiers), behavioral iteration, description optimization, and blind version comparison.

Skills are built from design specifications produced during methodology design work. The design spec is the input. This Skill's job is gate-checking, construction, validation, iteration, optimization, and publication-readiness.

Platform terminology note: This Skill retains root.node terminology (Block, Block Library, Domain Pack, Compiler, Optimizer) by design. Unlike most rootnode Skills that strip internal language, this Skill operates ON root.node Skills as its subject matter — the conversion rules, concept mapping, and build pipeline reference root.node concepts by name because those are what gets built.

Important

Description fields are everything. Claude decides whether to load a Skill based almost entirely on the description in YAML frontmatter. A perfect methodology behind a vague description never activates. Test every description: would Claude pick this Skill, and only this Skill, alongside 50 others?

Preserve depth, adapt format. The methodology is the differentiator. Every Skill retains substantive instructions, reasoning patterns, and quality criteria from source material. What changes is packaging — frontmatter, progressive disclosure structure, activation descriptions — not intellectual content.

Spec compliance is non-negotiable. Every Skill conforms to the Agent Skills specification. Name in kebab-case (max 64 chars), description ≤ 1024 chars (verify YAML-parsed length, not raw text), no XML angle brackets in frontmatter, no README.md inside skill folders, SKILL.md body under 500 lines / ~5000 tokens.

Standalone-first composition. Every Skill delivers complete value when installed alone. Cross-Skill references are soft pointers ("for deeper specialization, see X if available"). Prefer a few hundred tokens of duplicated guidance over a dependency that breaks a Skill when installed alone.

Pre-build gates run first. Before parsing any design spec, walk the three pre-build gates explicitly. A Skill that should have been a hook, a template, or an extension of an existing Skill is worse than no Skill at all — it ships, looks reasonable, and silently fails to deliver value.

The deliverable is a packaged zip plus separated audit artifacts. Build the deployable as {skill-name}.zip containing the Skill folder structure. Audit artifacts (placement note, promotion provenance, AP-warning summary) ship as separate files OUTSIDE the zip — they document the build event, not runtime behavior.

Routing surfaces over procedural depth in SKILL.md. Each new workflow section in SKILL.md names the workflow, identifies tier routing, and points to a reference. Procedural depth lives in references. The 500-line ceiling is a design-time forcing function, not a compression-time problem.

Tier-aware verdicts. When validation dimensions invoke empirical workflows (D9 sub-levels, description refinement, version comparison), the build environment determines which tier applies. Record the tier explicitly in the build summary; do not claim Tier A evidence when Tier A infrastructure was unavailable.

Complete file output. Always output the complete file. Never diffs, patches, or partial sections.

Reasoning discipline

Before declaring a Skill ready to ship, walk through the nine-dimension quality gate explicitly. State each check, cite the specific evidence (character counts, section structure, activation triggers, cross-Skill references, AP catches, layer leaks, applied D9 sub-level), then apply the pass/fail verdict. Do not compress this sequence into a summary judgment.

If the build scope is unclear (new build vs. review vs. revision vs. iterate vs. optimize description vs. compare versions), confirm scope with the user before proceeding. Do not proceed on inferred assumptions.

Pre-Build Gates

Before parsing any design spec or building any Skill files, walk three gates explicitly. Each gate has a specific decision and a specific halt condition. Pass all three before proceeding to "Build New Skill."

Gate 1 — Decomposition check

Where does this work fit in the 7-layer Claude Code mechanism framework? The mechanisms are CLAUDE.md (always-loaded standing context), .claude/rules/ (path-scoped on-demand rules), Skills (multi-step procedures), subagents (focused specialists with isolated context), hooks (lifecycle guarantees), MCP (external data/APIs), settings (trust/permission boundaries). For full framework guidance, read references/decomposition-framework.md.

If the work fits "Skills" cleanly: proceed to Gate 2. If the work fits a different mechanism: redirect with brief explanation. Do NOT build a Skill that should have been a hook, a rule, CLAUDE.md content, etc.

Gate 2 — Warrant check

Has the work pattern surfaced 3+ times in real use, with traceable evidence?

If yes: proceed to Gate 3. If no (1-2 occurrences, speculative future need): recommend building a paste-and-edit template first. Use the user's project prefix convention ({code}_template_{descriptor}.md). Document explicit promotion criteria inline. For full warrant guidance, read references/warrant-check-criteria.md.

Exception: when the user provides a process-abstraction handoff brief from rootnode-repo-hygiene (or another upstream Skill), the brief is the warrant evidence. Gate 2 passes automatically.

Gate 3 — Ecosystem fit check

Where does this Skill belong in the rootnode runtime tooling map? Check (1) CP-side or CC-side surface; (2) which existing rootnode Skills it composes with; (3) clear gap or duplicate of existing capability.

If clear gap: proceed to "Build New Skill." Surface the placement decision and suggested entry for the runtime tooling catalog (root_AGENT_ENVIRONMENT_ARCHITECTURE.md §6) in the build summary.

If duplication detected: surface to user. Ask whether to extend the existing Skill instead. Building a duplicate creates routing collisions. For full ecosystem guidance, read references/ecosystem-placement-decision.md.

Build New Skill

When the three pre-build gates have passed and a design specification is present in context:

Step 1 — Parse the design spec. Identify the methodology (what the Skill does), the reference file structure, the description field draft, the internal language adaptation notes, the composition testing cases, and any architectural decisions already made.

Step 2 — Build SKILL.md. Implement the methodology from the design spec. Apply conversion rules (see references/conversion-guide.md): strip root.node internal language per adaptation notes, inline relevant behavioral countermeasures, convert quality gates to actionable verification steps. Structure: identity paragraph, Important/Critical section, core instructions, examples, When to Use section, Troubleshooting section. Verify body under 500 lines. Verify description under 1024 characters with trigger phrases and negative triggers.

Step 2a — Description field construction. The d