ワンクリックで
skill-builder
// Scaffold or absorb new SKILL.md files against the unified AgentOps template. Triggers: "create a skill", "scaffold skill", "absorb external skill", "new skill".
// Scaffold or absorb new SKILL.md files against the unified AgentOps template. Triggers: "create a skill", "scaffold skill", "absorb external skill", "new skill".
Review completed work and learn.
Make an out-of-session Claude (Managed Agent or Agent SDK loop) AgentOps-native — via skills + the ao CLI + CI, not hooks.
Make an out-of-session agent AgentOps-native via skills + ao CLI + CI, not hooks.
Explain AgentOps workflows.
Explain AgentOps workflows.
Run autonomous improvement loops.
| name | skill-builder |
| description | Scaffold or absorb new SKILL.md files against the unified AgentOps template. Triggers: "create a skill", "scaffold skill", "absorb external skill", "new skill". |
| practices | ["code-complete","pragmatic-programmer","design-patterns"] |
| hexagonal_role | supporting |
| consumes | [] |
| produces | ["converted-skill"] |
| context_rel | [{"kind":"customer-of","with":"automation-shape-routing"},{"kind":"supplier-to","with":"skill-auditor"}] |
| skill_api_version | 1 |
| context | {"window":"fork","intent":{"mode":"questions"},"sections":{"exclude":["HISTORY"]},"intel_scope":"topic"} |
| metadata | {"tier":"meta","dependencies":["skill-auditor","converter"],"stability":"experimental"} |
| output_contract | skills/skill-builder/schemas/build-report.json |
Materializes a new skill against the unified template at references/skill-template.md (extracted from anthropics/financial-services). Runs skill-auditor on the new skill as a self-check before declaring success.
If unsure whether the work should be a skill, a Workflow, or an NTM swarm, run
/automation-shape-routingfirst — it is the front door that decides the shape and hands off to the right builder.
references/skill-template.md. Do not invent ad-hoc structures. Why: skill-auditor validates against this template; drift creates auditor false-fails./skill-auditor against the new skill directory. A FAIL verdict aborts the build. Why: PR-002 (external validation gate) — the builder must not declare its own work complete.from-scratch, from-template, and absorb-external modes must produce both skills/<name>/SKILL.md AND skills-codex/<name>/SKILL.md + skills-codex/<name>/prompt.md. Why: finding 2026-05-03-codex-skill-shape-is-dual-file — codex SKILL.md uses slim frontmatter (no skill_api_version); prompt.md is mandatory; audit-codex-parity.sh is a content scanner that won't catch frontmatter drift.references/ for overflow. Why: finding f-2026-05-01-025 — every Skill() invocation reloads 5-15KB; multi-lifecycle sessions compound to 150-200KB+ pure scaffolding.| Mode | Status | Description |
|---|---|---|
from-scratch | stable | Interactive scaffold from canonical template. Produces full skill skeleton + scripts/validate.sh + codex parity. |
from-template | stable | --like <existing-skill> copies structure from a sibling skill, swaps domain-specific sections. |
absorb-external | stable | Reads external SKILL.md (e.g., from ~/dev/financial-services/.../<skill>/SKILL.md), wraps in AgentOps frontmatter, invokes /converter for codex parity. |
from-pattern | alpha (passthrough) | Delegates to ao flywheel close-loop. Outputs land at .agents/knowledge/promoted/ per flywheel rules — they are NOT yet shaped as SKILL.md drafts. v2 will add skill-specific synthesis. Use from-scratch or absorb-external for SKILL.md output today. |
scripts/build.sh reads $1 and routes:
build.sh from-scratch <new-skill-name> # → init.sh --interactive
build.sh from-template <new-skill-name> --like council
build.sh absorb-external <new-skill-name> --from /path/to/SKILL.md
build.sh from-pattern # → ao flywheel close-loop
Checkpoint: Confirm with user the new skill's metadata.tier and metadata.dependencies before generation.
scripts/init.sh reads references/skill-template.md (the canonical template section) and renders a SKILL.md skeleton with frontmatter pre-filled. For from-template, structure is copied from the source skill; section bodies are blanked and replaced with template stubs.
For absorb-external, the external SKILL.md's content (Constraints / Workflow / Output / Quality sections) is preserved verbatim where possible; AgentOps' structured frontmatter is added on top; the external description is reformatted to satisfy description-has-triggers.
Checkpoint: /heal-skill --check skills/<new-name> returns clean.
scripts/init.sh invokes /converter skills/<new-name> codex to produce skills-codex/<new-name>/{SKILL.md,prompt.md}. Then trims skill_api_version from the codex SKILL.md (converter may preserve it). Asserts prompt.md exists.
Checkpoint: bash scripts/audit-codex-parity.sh returns clean AND grep -q "^skill_api_version:" skills-codex/<name>/SKILL.md returns nothing.
The build script tail invokes /skill-auditor on skills/<new-name>. WARN is acceptable for v1 skills (e.g., experimental stability). FAIL aborts.
Checkpoint: audit_pass=true in build report.
For AgentOps skill upgrades, use the productization score as a patch selector,
not as a replacement for skill-auditor:
python3 skills/skill-auditor/scripts/score_agentops_skill.py skills/<name> --markdown
Choose the smallest patch that improves the score while preserving the canonical template and Codex parity constraints.
Format: JSON conforming to schemas/build-report.json written to stdout; markdown audit report written to .agents/audits/<skill>-build.md.
Files created (from-scratch mode):
skills/<name>/
├── SKILL.md (≤250 lines, full template spine)
├── scripts/
│ └── validate.sh (self-validation per AgentOps convention)
└── references/ (only if expected to exceed 400 lines)
skills-codex/<name>/
├── SKILL.md (slim frontmatter — no skill_api_version)
└── prompt.md (~10-20 line Execution Profile)
skill-auditor PASS or WARN (not FAIL)references/)schemas/build-report.jsonfrom-pattern mode prominently marked alpha/passthrough in user outputCreate a new skill from scratch:
/skill-builder from-scratch hello-world
# → interactive prompt: tier? deps? primary deliverable?
# → writes skills/hello-world/SKILL.md + skills-codex/hello-world/{SKILL.md,prompt.md}
# → runs /skill-auditor on the new skill
Clone structure from an existing skill:
/skill-builder from-template my-new-skill --like council
# → mirrors council's section spine; substitutes new metadata
Absorb a skill from anthropics/financial-services:
/skill-builder absorb-external dcf-helper \
--from ~/dev/financial-services/plugins/vertical-plugins/financial-analysis/skills/dcf-model/SKILL.md
# → preserves Constraints/Workflow/Output content, wraps in AgentOps frontmatter
| Problem | Cause | Solution |
|---|---|---|
| Self-audit FAIL | Generated SKILL.md missing required Pass-2 check | Re-run with --verbose; inspect which check failed; usually output-spec-explicit or trigger-clarity |
| Codex parity drift | /converter preserved skill_api_version | init.sh runs sed -i '/^skill_api_version:/d' skills-codex/<name>/SKILL.md; verify with grep |
| SKILL.md > 250 lines | Mode generated too much inline content | Move section bodies to references/<topic>.md; reference inline as [text](references/<topic>.md) |
from-pattern produces no SKILL.md | Expected behavior — passthrough only in v1 | Use from-scratch or absorb-external if you need a SKILL.md draft |