Skills-Driven Development

skdd — init → forge → doctor

$ skdd init --harness=claudeskdd init — Claude Code (canonical)project: ~/democanonical: skills/mirror: .claude/skillsinstruction file: CLAUDE.md✓ created skills/skillforge/✓ wrote skills/skillforge/SKILL.md (stub — replace with the full version when ready)✓ created .skills-registry.md✓ created CLAUDE.md with skills blockLinking harness mirrorskdd link — symlink modecanonical: skills/mirrors: .claude/skills✓ .claude/skills → skills (created symlink)✓ State written to .skdd-sync.jsonNext steps1. Pull the full skillforge instead of the stub: curl -fsSL https://raw.githubusercontent.com/zakelfassi/skills-driven-development/main/skillforge/SKILL.md -o skills/skillforge/SKILL.md2. Open this project with Claude Code and ask: "What skills are available?"3. Forge your first skill: "Forge a skill for <your repeated task>."4. See docs/configuration.md for per-harness details.$ skdd forge release-notes --non-interactive --from-description "Summarise merged PRs and generate a user-facing CHANGELOG entry for each release"✓ forged skills/release-notes/SKILL.md✓ registered release-notes in .skills-registry.mdrefreshed .claude/skills mirror$ skdd doctorskdd doctorproject: ~/democanonical: skills/Colony ! no .colony.json manifest → Hand-write .colony.json (schema: docs/spec/colony-v1.json) to make the colony discoverable by marketplaces.Skills ✓ 2 skill(s) found in skills/Validation ! 1 spec warning(s) across 2 skill(s) → Run 'skdd validate' for per-skill details.Registry ! 1 skill(s) on disk missing from registry: skillforge → Re-run 'skdd forge' for each, or add them to .skills-registry.md by hand.Mirrors ✓ 1 mirror(s) in sync (.claude/skills)Instructions ✓ 1 instruction file(s) reference the skills registry: CLAUDE.md

Real output from skdd — recorded, not mocked.

The one-minute pitch

A skill is a reusable, discoverable playbook — a markdown file plus optional scripts — that an agent follows to accomplish a specific, repeatable task. SkDD adds a lifecycle on top of the Agent Skills spec: forge → register → discover → evolve → archive. The skills get better the more your agents work, because your agents are the ones forging and evolving them.

Quick start

pnpm dlx @zakelfassi/skdd init --harness=claude       # or codex, cursor, copilot, gemini, opencode, goose, amp

That one command scaffolds a canonical skills/ directory, writes .skills-registry.md, appends a Skills block to your harness instruction file, and materializes a .claude/skills symlink → ../skills so the harness finds the colony at its conventional path. See Configuration for details.

One canonical colony, many harness mirrors

SkDD keeps a single source of truth — the skills/ directory at your repo root — and fans it out to each harness’s conventional path via symlinks. Edit in one place; every agent sees the change.

Examples gallery

Three reference colonies — each with real structure, a lived-in registry, and at least one executable script.

webapp-starter TypeScript + React/Express colony. 4 skills: deploy-preview (runs), api-endpoint, component-scaffold, bug-triage.

cli-tool Cross-platform CLI (shipctl) colony. 5 skills: release-cut (runs), cross-compile-matrix, flag-add, manpage-sync, breaking-change-audit.

data-pipeline Python data-engineering + ML colony. 5 skills: experiment-log (runs), dataset-onboard, pipeline-stage, data-quality-gate (forked), backfill-runbook.

Explore

Why SkDD? The pitch, the lifecycle diagram, and who it's for. Start here if you want the narrative.

Configuration Per-harness wiring: Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode, Goose, Amp.

Skill colony concept What a colony is, how it differs from a static library, and the architecture diagram.

Forging skills The skillforge meta-skill checklist and what the agent actually does when you say 'forge this.'

Specification alignment How SkDD maps onto the agentskills.io v1 spec — what's spec-native vs SkDD-added.

Harness integrations Dedicated guides for 11 harnesses: Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode, Goose, Amp, VS Code, Junie, Roo Code.

Examples gallery Three reference colonies (webapp-starter, cli-tool, data-pipeline) with real skills, registries, and executable stubs — every example passes skdd validate and skdd doctor.

Principles

1. Forge, don’t front-load — let agents create skills when they notice patterns during real work.
2. Small skills, composed loosely — complex workflows emerge from composing small skills.
3. Skills are living documents — agents should evolve them when they hit edge cases.
4. The colony is the product — invest in the registry and discovery mechanisms.
5. Human-readable, machine-executable — markdown for humans, frontmatter for agents.