convez.ai
SkillAutomaçãoAvançado
zakelfassi

Skills-Driven Development (SkDD)

zakelfassi/skills-driven-development

Agentes que criam e evoluem skills reutilizáveis enquanto trabalham

Ver no GitHub
BomPluginScore · de 0 a 100

Metodologia 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-development

1 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

Estrelas
18
Forks
1
Acompanhando
1
Saúde
100%
Último commit
há 1 semana
Versão
v1.2.0
Issues abertas
0
Contribuidores
4

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:

ColonyPersonaSkillsWhat it demonstrates
examples/webapp-starterReact + TypeScript + Express web app4Component scaffolding, API endpoints, deploy previews, bug triage
examples/cli-toolCross-platform CLI (shipctl)5Release pipelines, build matrices, flag management, man pages, breaking-change audits
examples/data-pipelinePython ETL + ML project5Dataset 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).

HarnessProject dirGlobal dirMirrorGuide
Claude Code.claude/skills~/.claude/skillssymlink / copydocs
OpenAI Codex.codex/skills~/.codex/skillssymlink / copydocs
Cursor.cursor/skills~/.cursor/skillssymlink / copydocs
GitHub Copilot.github/skills~/.copilot/skillssymlink / copydocs
Gemini CLI.gemini/skills~/.gemini/skillssymlink / copydocs
OpenCode.opencode/skills~/.config/opencode/skillssymlink / copydocs
Goose.goose/skills~/.agents/skillssymlink / copydocs
Amp.amp/skills~/.config/agents/skillssymlink / copydocs
Factory Droid.factory/skills~/.factory/skillssymlink / copydocs

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

PathWhat 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 SpecSkDD 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

  1. Forge, don't front-load. Let agents create skills when they notice patterns during real work.
  2. Small skills, composed loosely. Each skill does one thing well; complexity emerges from composition, not monoliths.
  3. Skills are living documents. A skill that was forged 3 months ago and never updated is dead weight — evolve it.
  4. The colony is the product. Individual skills are useful; a discoverable, composable colony is transformative.
  5. Human-readable, machine-executable. Markdown humans can read and review; structured so agents can parse and follow without intervention.

Community


Inspiration & Prior Art

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados