skill-builder

Files (5)

• SKILL.md
• demo_spec.json
• skill_builder.py
• spec_template.json · templates/
• test_skill_builder.py · tests/

SKILL.md (first lines)

# 🦖 Skill Builder

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

1. **Spec-driven scaffolding**: Read a JSON (or YAML with pyyaml) spec file and generate a complete skill directory.
2. **Interactive mode**: Prompt for skill details when no spec file is provided (`--interactive`).
3. **Validation**: Check any existing `SKILL.md` against the CONTRIBUTING.md checklist (`--validate-only`).
4. **Auto-registration**: Update `skills/catalog.json` and patch `clawbio.py`'s `SKILLS` dict when run from inside the ClawBio repo.
5. **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:

1. **Load spec**: Read JSON/YAML spec file, or collect fields interactively if `--interactive`
2. **Validate spec**: Check required fields (name, description, author); apply defaults for optional fields
3. **Generate files**: Create `SKILL.md`, `<name>.py`, `tests/test_<name>.py`, `examples/example_spec.json`
4. **Update registry**: If repo root found, append entry to `catalog.json` and patch the `SKILLS` dict in `clawbio/cli.py` (falls back to `clawbio.py` in older checkouts)
5. **Report**: Print a summary of generated files and next steps

## CLI Reference

```bash
# 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

```bash
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):
```json
{
  "name": "my-skill",
  "description": "What this skill does",
  "author": "Your Name"
}
```

Full spec with all optional fields:
```json
{
  "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

1. **Parse spec**: Load JSON (stdlib) or YAML (pyyaml if available); fall back to interactive prompts
2. **Normalise name**: Enforce lowercase-hyphen naming (`vcf-annotator`, not `VCF_Annotator`)
3. **Fill defaults**: domain → "bioinformatics", version → "0.1.0", capabilities/triggers → generic placeholders
4. **Render SKILL.md**: Fill YAML frontmatter + all 13 required body sections from template
5. **Render Python skeleton**: argparse wired with `--input`/`--output`/`--demo`; output boilerplate creates `report.md`, `result.json`, reproducibility bundle
6. **Render test skeleton**: pytest fixture + 4 standard tests (demo, report, result.json, reproducibility bundle)
7. **Validate**: Run the 13-item CONTRIBUTING checklist against the generated SKILL.md before writing
8. **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"

From ClawBio/ClawBio, MIT.

More from ClawBio/ClawBio