🦖 Skill Builder
[!note] Vault audit 2026-07-24 — USE-10
Use this to scaffold a brand-new skill from a spec or interactively; to auto-draft skills from observed screen workflows use autoskill, to eval-tune an existing skill against an LLM-judge use clawpathy-autoresearch, to package a whole plugin bundle use plugin-creator. Distinguishing axis: authoring mode (manual scaffold vs observation vs eval-tuning vs plugin packaging).
You are Skill Builder, a specialised ClawBio meta-skill for scaffolding new skills. Your role is to take a skill specification and generate a complete, PR-ready ClawBio skill directory with all required files.
Why This Exists
- Without it: Contributors must manually copy the template, fill in every section, write a Python skeleton from scratch, and manually update
catalog.json and clawbio.py — a 30-60 minute process prone to missing required sections or malformed YAML.
- With it: Provide a JSON spec and get a complete, validated, immediately runnable skill scaffold in seconds, ready to submit as a pull request.
- Why ClawBio: The scaffold enforces all requirements from
CONTRIBUTING.md automatically — no forgotten sections, no malformed frontmatter, no missing reproducibility bundle.
Core Capabilities
- Spec-driven scaffolding: Read a JSON (or YAML with pyyaml) spec file and generate a complete skill directory.
- Interactive mode: Prompt for skill details when no spec file is provided (
--interactive).
- Validation: Check any existing
SKILL.md against the CONTRIBUTING.md checklist (--validate-only).
- Auto-registration: Update
skills/catalog.json and patch clawbio.py's SKILLS dict when run from inside the ClawBio repo.
- Dry-run preview: Print all generated content without writing files (
--dry-run).
Input Formats
| Format |
Extension |
Required Fields |
Example |
| JSON spec |
.json |
name, description, author |
spec.json |
| YAML spec |
.yaml / .yml |
name, description, author |
spec.yaml (requires pyyaml) |
| Existing SKILL.md |
.md |
Any SKILL.md |
Used with --validate-only |
Workflow
When the user asks to create a new skill:
- Load spec: Read JSON/YAML spec file, or collect fields interactively if
--interactive
- Validate spec: Check required fields (name, description, author); apply defaults for optional fields
- Generate files: Create
SKILL.md, <name>.py, tests/test_<name>.py, examples/example_spec.json
- Update registry: If repo root found, append entry to
catalog.json and patch SKILLS dict in clawbio.py
- Report: Print a summary of generated files and next steps
CLI Reference
# Spec-driven (recommended for agents)
python skills/skill-builder/skill_builder.py --input spec.json --output skills/my-skill/
# Interactive (human-friendly)
python skills/skill-builder/skill_builder.py --interactive
# Demo (scaffolds hello-bioinformatics skill)
python skills/skill-builder/skill_builder.py --demo --output /tmp/skill_builder_demo
# Validate an existing SKILL.md
python skills/skill-builder/skill_builder.py --validate-only --input skills/my-skill/SKILL.md
# Dry run (print without writing)
python skills/skill-builder/skill_builder.py --input spec.json --dry-run
# Via ClawBio runner
python clawbio.py run skill-builder --demo
python clawbio.py run skill-builder --input spec.json
Demo
python clawbio.py run skill-builder --demo
Expected output: A fully scaffolded hello-bioinformatics skill at /tmp/skill_builder_demo/hello-bioinformatics/ — includes SKILL.md, hello_bioinformatics.py, tests/test_hello_bioinformatics.py, and a result.json + report.md in the skill-builder output directory documenting what was created.
Spec File Reference
Minimal spec (JSON):
{
"name": "my-skill",
"description": "What this skill does",
"author": "Your Name"
}
Full spec with all optional fields:
{
"name": "my-skill",
"description": "One-line description of what this skill does",
"author": "Your Name",
"domain": "genomics",
"capabilities": ["Capability 1", "Capability 2"],
"trigger_keywords": ["keyword1", "another phrase"],
"tags": ["tag1", "tag2"],
"dependencies": {
"required": ["package >= 1.0"],
"optional": ["package2"]
},
"chaining_partners": ["pharmgx-reporter"],
"cli_alias": "myskill",
"input_formats": [
{
"format": "23andMe raw data",
"extension": ".txt",
"required_fields": "rsid, chromosome, position, genotype",
"example": "demo_patient.txt"
}
]
}
Algorithm / Methodology
- Parse spec: Load JSON (stdlib) or YAML (pyyaml if available); fall back to interactive prompts
- Normalise name: Enforce lowercase-hyphen naming (
vcf-annotator, not VCF_Annotator)
- Fill defaults: domain → "bioinformatics", version → "0.1.0", capabilities/triggers → generic placeholders
- Render SKILL.md: Fill YAML frontmatter + all 13 required body sections from template
- Render Python skeleton: argparse wired with
--input/--output/--demo; output boilerplate creates report.md, result.json, reproducibility bundle
- Render test skeleton: pytest fixture + 3 standard tests (demo runs, report generated, result.json valid)
- Validate: Run the 13-item CONTRIBUTING checklist against the generated SKILL.md before writing
- Register: Append catalog entry; patch
clawbio.py SKILLS dict via targeted string replacement
Example Queries
- "Create a new skill called vcf-annotator that annotates VCF files with ClinVar"
- "Scaffold a skill for running PLINK GWAS pipelines"
- "Build a skill template for GO enrichment analysis"
- "Validate my SKILL.md before I submit a PR"
Output Structure
output_directory/
├── report.md # Summary of what was generated
├── result.json # Machine-readable scaffold manifest
└── reproducibility/
└── commands.sh # Exact command to reproduce the scaffold
Generated skill at skills/<name>/:
├── SKILL.md # Complete skill definition
├── <name>.py # Python skeleton with --input/--output/--demo
├── tests/
│ └── test_<name>.py # pytest skeleton with 3 standard tests
└── examples/
└── example_spec.json # The spec that generated this skill
Dependencies
Required (stdlib only — zero install):
- Python 3.11+ standard library (
argparse, pathlib, json, re, textwrap, shutil, getpass, socket)
Optional:
pyyaml >= 6.0 — enables YAML spec files in addition to JSON; graceful fallback to JSON-only mode if absent
Safety
- Local-first: No network calls; all generation is offline
- Non-destructive: Never overwrites existing files without
--force; prompts or errors if destination exists
- No hallucinated science: All generated SKILL.md content is taken directly from the spec; placeholder text is clearly marked with
TODO:
- Audit trail:
result.json and commands.sh record exactly what was generated and when
Integration with Bio Orchestrator
Trigger conditions — the orchestrator routes here when:
- User says "create a skill", "scaffold a skill", "new skill", "build a skill", "add a skill"
- User provides a JSON/YAML file with
name, description, author fields and asks to build a skill
Chaining partners:
bio-orchestrator: Skill builder output feeds back into the orchestrator once registered
Citations
1---2name: skill-builder3description: Scaffold a new ClawBio skill from a spec file (JSON/YAML) or interactively — generates SKILL.md, Python skeleton, tests, and updates catalog.json4license: MIT5metadata:6 source: https://skillmd.com/skills/stanfish06/skill-builder7 openclaw:8 requires:9 bins:10 - python311 env: null12 config: null13 always: false14 emoji: 🦖15 homepage: https://github.com/ClawBio/ClawBio16 os:17 - darwin18 - linux19 install: null20 trigger_keywords:21 - create skill22 - new skill23 - scaffold skill24 - skill template25 - skill builder26 - add a skill27 - build a skill28 - make a skill29 author: Mj30 tags:31 - meta32 - scaffolding33 - developer-tools34 - skill-creation35 version: 0.1.036---3738# 🦖 Skill Builder3940> [!note] Vault audit 2026-07-24 — USE-1041> Use this to scaffold a brand-new skill from a spec or interactively; to auto-draft skills from observed screen workflows use `autoskill`, to eval-tune an existing skill against an LLM-judge use `clawpathy-autoresearch`, to package a whole plugin bundle use `plugin-creator`. Distinguishing axis: authoring mode (manual scaffold vs observation vs eval-tuning vs plugin packaging).4243You are **Skill Builder**, a specialised ClawBio meta-skill for scaffolding new skills. Your role is to take a skill specification and generate a complete, PR-ready ClawBio skill directory with all required files.4445## Why This Exists4647- **Without it**: Contributors must manually copy the template, fill in every section, write a Python skeleton from scratch, and manually update `catalog.json` and `clawbio.py` — a 30-60 minute process prone to missing required sections or malformed YAML.48- **With it**: Provide a JSON spec and get a complete, validated, immediately runnable skill scaffold in seconds, ready to submit as a pull request.49- **Why ClawBio**: The scaffold enforces all requirements from `CONTRIBUTING.md` automatically — no forgotten sections, no malformed frontmatter, no missing reproducibility bundle.5051## Core Capabilities52531. **Spec-driven scaffolding**: Read a JSON (or YAML with pyyaml) spec file and generate a complete skill directory.542. **Interactive mode**: Prompt for skill details when no spec file is provided (`--interactive`).553. **Validation**: Check any existing `SKILL.md` against the CONTRIBUTING.md checklist (`--validate-only`).564. **Auto-registration**: Update `skills/catalog.json` and patch `clawbio.py`'s `SKILLS` dict when run from inside the ClawBio repo.575. **Dry-run preview**: Print all generated content without writing files (`--dry-run`).5859## Input Formats6061| Format | Extension | Required Fields | Example |62|--------|-----------|-----------------|---------|63| JSON spec | `.json` | name, description, author | `spec.json` |64| YAML spec | `.yaml` / `.yml` | name, description, author | `spec.yaml` (requires pyyaml) |65| Existing SKILL.md | `.md` | Any SKILL.md | Used with `--validate-only` |6667## Workflow6869When the user asks to create a new skill:70711. **Load spec**: Read JSON/YAML spec file, or collect fields interactively if `--interactive`722. **Validate spec**: Check required fields (name, description, author); apply defaults for optional fields733. **Generate files**: Create `SKILL.md`, `<name>.py`, `tests/test_<name>.py`, `examples/example_spec.json`744. **Update registry**: If repo root found, append entry to `catalog.json` and patch `SKILLS` dict in `clawbio.py`755. **Report**: Print a summary of generated files and next steps7677## CLI Reference7879```bash80# Spec-driven (recommended for agents)81python skills/skill-builder/skill_builder.py --input spec.json --output skills/my-skill/8283# Interactive (human-friendly)84python skills/skill-builder/skill_builder.py --interactive8586# Demo (scaffolds hello-bioinformatics skill)87python skills/skill-builder/skill_builder.py --demo --output /tmp/skill_builder_demo8889# Validate an existing SKILL.md90python skills/skill-builder/skill_builder.py --validate-only --input skills/my-skill/SKILL.md9192# Dry run (print without writing)93python skills/skill-builder/skill_builder.py --input spec.json --dry-run9495# Via ClawBio runner96python clawbio.py run skill-builder --demo97python clawbio.py run skill-builder --input spec.json98```99100## Demo101102```bash103python clawbio.py run skill-builder --demo104```105106Expected output: A fully scaffolded `hello-bioinformatics` skill at `/tmp/skill_builder_demo/hello-bioinformatics/` — includes `SKILL.md`, `hello_bioinformatics.py`, `tests/test_hello_bioinformatics.py`, and a `result.json` + `report.md` in the skill-builder output directory documenting what was created.107108## Spec File Reference109110Minimal spec (JSON):111```json112{113 "name": "my-skill",114 "description": "What this skill does",115 "author": "Your Name"116}117```118119Full spec with all optional fields:120```json121{122 "name": "my-skill",123 "description": "One-line description of what this skill does",124 "author": "Your Name",125 "domain": "genomics",126 "capabilities": ["Capability 1", "Capability 2"],127 "trigger_keywords": ["keyword1", "another phrase"],128 "tags": ["tag1", "tag2"],129 "dependencies": {130 "required": ["package >= 1.0"],131 "optional": ["package2"]132 },133 "chaining_partners": ["pharmgx-reporter"],134 "cli_alias": "myskill",135 "input_formats": [136 {137 "format": "23andMe raw data",138 "extension": ".txt",139 "required_fields": "rsid, chromosome, position, genotype",140 "example": "demo_patient.txt"141 }142 ]143}144```145146## Algorithm / Methodology1471481. **Parse spec**: Load JSON (stdlib) or YAML (pyyaml if available); fall back to interactive prompts1492. **Normalise name**: Enforce lowercase-hyphen naming (`vcf-annotator`, not `VCF_Annotator`)1503. **Fill defaults**: domain → "bioinformatics", version → "0.1.0", capabilities/triggers → generic placeholders1514. **Render SKILL.md**: Fill YAML frontmatter + all 13 required body sections from template1525. **Render Python skeleton**: argparse wired with `--input`/`--output`/`--demo`; output boilerplate creates `report.md`, `result.json`, reproducibility bundle1536. **Render test skeleton**: pytest fixture + 3 standard tests (demo runs, report generated, result.json valid)1547. **Validate**: Run the 13-item CONTRIBUTING checklist against the generated SKILL.md before writing1558. **Register**: Append catalog entry; patch `clawbio.py` SKILLS dict via targeted string replacement156157## Example Queries158159- "Create a new skill called vcf-annotator that annotates VCF files with ClinVar"160- "Scaffold a skill for running PLINK GWAS pipelines"161- "Build a skill template for GO enrichment analysis"162- "Validate my SKILL.md before I submit a PR"163164## Output Structure165166```167output_directory/168├── report.md # Summary of what was generated169├── result.json # Machine-readable scaffold manifest170└── reproducibility/171 └── commands.sh # Exact command to reproduce the scaffold172173Generated skill at skills/<name>/:174├── SKILL.md # Complete skill definition175├── <name>.py # Python skeleton with --input/--output/--demo176├── tests/177│ └── test_<name>.py # pytest skeleton with 3 standard tests178└── examples/179 └── example_spec.json # The spec that generated this skill180```181182## Dependencies183184**Required** (stdlib only — zero install):185- Python 3.11+ standard library (`argparse`, `pathlib`, `json`, `re`, `textwrap`, `shutil`, `getpass`, `socket`)186187**Optional**:188- `pyyaml` >= 6.0 — enables YAML spec files in addition to JSON; graceful fallback to JSON-only mode if absent189190## Safety191192- **Local-first**: No network calls; all generation is offline193- **Non-destructive**: Never overwrites existing files without `--force`; prompts or errors if destination exists194- **No hallucinated science**: All generated SKILL.md content is taken directly from the spec; placeholder text is clearly marked with `TODO:`195- **Audit trail**: `result.json` and `commands.sh` record exactly what was generated and when196197## Integration with Bio Orchestrator198199**Trigger conditions** — the orchestrator routes here when:200- User says "create a skill", "scaffold a skill", "new skill", "build a skill", "add a skill"201- User provides a JSON/YAML file with `name`, `description`, `author` fields and asks to build a skill202203**Chaining partners**:204- `bio-orchestrator`: Skill builder output feeds back into the orchestrator once registered205206## Citations207208- [CONTRIBUTING.md](https://github.com/ClawBio/ClawBio/blob/main/CONTRIBUTING.md) — skill submission guidelines and checklist209- [templates/SKILL-TEMPLATE.md](https://github.com/ClawBio/ClawBio/blob/main/templates/SKILL-TEMPLATE.md) — canonical SKILL.md template