Skills-Driven Development (SkDD)
zakelfassi/skills-driven-development
Agentes que criam e evoluem skills reutilizáveis enquanto trabalham
Ver no GitHubMetodologia para agentes de IA criarem, evoluírem e compartilharem skills reutilizáveis como artefatos vivos. Agents aprendem durante a execução, persistindo padrões de trabalho em arquivos SKILL.md seguindo a especificação aberta Agent Skills. Transforma conhecimento implícito em código estruturado que melhora a cada uso.
Instalação
npx convez-ai zakelfassi/skills-driven-development1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Construir bibliotecas de procedimentos que evoluem naturalmente
- Encapsular workflows repetitivos em skills descobríveis e componíveis
- Multiplicar capacidades de agentes IA através de colônias de skills colaborativas
Veredito

Framework sólido para transformar padrões ad-hoc em ativos estruturados. Endereça um problema real (memory e reusabilidade em agentes), mas exige disciplina na adoção e integração com fluxos de prompt existentes.
README
A tradução para o português deste README ainda está na fila.
What is SkDD?
Skills-Driven Development (SkDD) is a methodology where AI agents create, evolve, and share reusable skills as a natural byproduct of their work. Instead of front-loading all knowledge into prompts, agents forge skills on the fly and persist them for future reuse.
A skill is a reusable, discoverable playbook — a SKILL.md file with YAML frontmatter following the open Agent Skills specification. Structurally it's a directory with markdown instructions, optional scripts, and references. Functionally it's process memory: agents discover skills by description, follow their steps, and evolve them when they encounter edge cases.
SkDD treats skills as living artifacts — discovered, forked, evolved, and composed across projects and sessions. The goal is not a static library but a colony that gets smarter every time it's used.
Quickstart
Run these three commands in your own project (not this repo):
# 1. Scaffold the colony (adds skills/, registry, CLAUDE.md block, harness mirror)
pnpm dlx @zakelfassi/skdd init --harness=claude
# 2. Forge your first skill (natural language — agent walks the skillforge steps)
# Tell your agent: "Forge a skill for <your workflow>. Follow the skillforge steps."
# 3. Verify it persisted — open a fresh session and ask:
# "What skills are available in this project?"
See watch the loop run → for a recorded terminal walkthrough: init → forge → doctor.
The SkDD Lifecycle
flowchart LR
A[1. Agent works<br/>on a task] -->|repeated pattern?| B{{Notice}}
B -->|yes| C[2. Forge<br/>skillforge writes<br/>SKILL.md]
B -->|no| A
C --> D[3. Register<br/>in .skills-registry.md]
D -->|session N+1| E[4. Discover<br/>via description match]
E -->|in-use| F[5. Evolve<br/>add edge cases,<br/>fix scripts, split]
F --> A
E -->|unused 90d| G[6. Archive<br/>reversible]
G -.->|restore| E
classDef work fill:#1e293b,stroke:#38bdf8,stroke-width:2px,color:#f8fafc;
classDef forge fill:#b45309,stroke:#f59e0b,stroke-width:2px,color:#fef3c7;
classDef discover fill:#0c4a6e,stroke:#38bdf8,stroke-width:2px,color:#f0f9ff;
classDef archive fill:#334155,stroke:#64748b,stroke-width:2px,color:#e2e8f0;
class A work;
class C,F forge;
class D,E discover;
class G archive;
Every loop through the diagram improves the colony. Archiving is reversible; nothing is ever deleted.
Hub & Global Colony
This is the 1.0 headline.
SkDD 1.0 ships a global colony at ~/.skdd/ — one canonical place to manage skills and MCP servers across every harness on your machine.
# Initialize the global colony (links to all installed harness dirs)
skdd init --global
# See everything at a glance: skills, mirrors, MCP servers, doctor status
skdd hub
# Sync MCP server configs from ~/.skdd/mcp.json to all supported MCP hosts (7)
skdd mcp sync
# List skills across project + global colony
skdd list --global
~/.skdd/ layout:
~/.skdd/
├── skills/ # global skill colony (shared across all projects)
├── .skills-registry.md # global registry
├── .skdd-sync.json # mirror state (v2)
└── mcp.json # canonical MCP server registry
skdd hub opens an Ink TUI with four panes: skills (project + global), mirror status + link/unlink toggles, MCP server × host matrix, and a doctor report — all in one screen.
skdd mcp sync writes your ~/.skdd/mcp.json to all installed harness configs using merge-not-overwrite adapters. Supports ${VAR} environment placeholders (secrets never round-trip), per-server host allowlists, and --dry-run mode. Adapters cover all 7 MCP hosts: claude-code, claude-desktop, codex, droid, cursor, opencode, gemini. (The 9 harnesses in the support matrix include 2 that do not have an MCP config format: GitHub Copilot and Goose.)
Examples Gallery
Three reference colonies — every example passes skdd validate and skdd doctor:
| Colony | Persona | Skills | What it demonstrates |
|---|---|---|---|
examples/webapp-starter | React + TypeScript + Express web app | 4 | Component scaffolding, API endpoints, deploy previews, bug triage |
examples/cli-tool | Cross-platform CLI (shipctl) | 5 | Release pipelines, build matrices, flag management, man pages, breaking-change audits |
examples/data-pipeline | Python ETL + ML project | 5 | Dataset onboarding, pipeline scaffolding, experiment logging, data quality gates, backfills |
Each colony ships with AGENTS.md, CLAUDE.md, .skills-registry.md (including archived + forked rows), .colony.json, and at least one executable stub script. Browse the Examples gallery → for full walkthroughs.
Harness Support Matrix
SkDD works in any harness that understands the Agent Skills spec. Skills live in a single canonical skills/ directory; each harness sees them through its own mirror path (symlink on Unix, copy on Windows).
| Harness | Project dir | Global dir | Mirror | Guide |
|---|---|---|---|---|
| Claude Code | .claude/skills | ~/.claude/skills | symlink / copy | docs |
| OpenAI Codex | .codex/skills | ~/.codex/skills | symlink / copy | docs |
| Cursor | .cursor/skills | ~/.cursor/skills | symlink / copy | docs |
| GitHub Copilot | .github/skills | ~/.copilot/skills | symlink / copy | docs |
| Gemini CLI | .gemini/skills | ~/.gemini/skills | symlink / copy | docs |
| OpenCode | .opencode/skills | ~/.config/opencode/skills | symlink / copy | docs |
| Goose | .goose/skills | ~/.agents/skills | symlink / copy | docs |
| Amp | .amp/skills | ~/.config/agents/skills | symlink / copy | docs |
| Factory Droid | .factory/skills | ~/.factory/skills | symlink / copy | docs |
Use skdd init --harness=<name> for a single harness, or skdd link --harness=claude,codex,cursor to materialize mirrors for multiple harnesses at once. One skills/ directory — no duplication, no drift.
What's in This Repo
| Path | What it is |
|---|---|
cli/ | @zakelfassi/skdd — TypeScript ESM CLI (init, forge, list, show, link, doctor, import, validate, mcp, hub) |
skillforge/ | The meta-skill: agents use this to create new skills |
examples/ | Three reference colonies (webapp-starter, cli-tool, data-pipeline) — every example passes skdd validate and skdd doctor |
docs/ | Methodology: skill colony concept, forging mechanics, specification alignment, harness integration guides |
colony/ | The skill colony pattern: discovery, evolution, sharing |
plugins/skdd-claude/ | Claude Code plugin (bundled skillforge, install instructions) |
extensions/vscode/ | VS Code extension scaffold (syntax highlighting, snippets) |
site/ | Astro/Starlight documentation site |
assets/ | Brand assets: dark/light logo, wordmark, mark, OG image, BRAND.md token guide |
Spec Alignment
SkDD is fully compatible with the Agent Skills specification:
| Agent Skills Spec | SkDD Extension |
|---|---|
SKILL.md with YAML frontmatter | ✅ Same format |
scripts/, references/, assets/ | ✅ Same structure |
| Manual skill creation | ➕ Agents forge skills autonomously |
| Static skill libraries | ➕ Skills evolve through use |
| Per-project skills | ➕ Colony-level discovery + sharing + global hub |
SkDD doesn't replace the spec — it adds a lifecycle on top of it.
Principles
- Forge, don't front-load. Let agents create skills when they notice patterns during real work.
- Small skills, composed loosely. Each skill does one thing well; complexity emerges from composition, not monoliths.
- Skills are living documents. A skill that was forged 3 months ago and never updated is dead weight — evolve it.
- The colony is the product. Individual skills are useful; a discoverable, composable colony is transformative.
- Human-readable, machine-executable. Markdown humans can read and review; structured so agents can parse and follow without intervention.
Community
- Contributing: See CONTRIBUTING.md — conventional commits, PR template, issue labels.
- Code of Conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Docs site: zakelfassi.github.io/skills-driven-development
- Changelog: CHANGELOG.md
Inspiration & Prior Art
- Agent Skills Specification — The open format this builds on
- Forgeloop — Agentic build loop framework where SkDD was first implemented
- how-to-ralph-wiggum — The Ralph methodology for agent-driven development
- marge-simpson — Knowledge persistence patterns across sessions
License
MIT — see LICENSE.