The Skill Colony

A shared, evolving library of agent capabilities that grows through use.

Terminology

SkDD uses a small vocabulary consistently. Anchor links here when you use these words elsewhere in the docs or in a skill.

Skill — a directory containing a SKILL.md plus optional scripts/, references/, and assets/. The smallest unit of reusable agent procedure. See the Agent Skills specification.
Colony — a discoverable collection of skills with a registry, update protocol, and lifecycle. Can span one project or many.
Registry — the .skills-registry.md file (and optional .skills-registry.json mirror) that lists a colony’s skills with their metadata. Always lives at the project root unless the harness’s spec says otherwise.
Canonical skills directory — the skills/ directory at the project root where user-project skills actually live. Single source of truth. Edited directly by agents and humans.
Harness mirror — a harness-expected skills directory (.claude/skills, .codex/skills, .cursor/skills, .github/skills, etc.) that points at the canonical skills/ directory. On Unix it’s a symlink; on Windows it’s a file copy tracked in .skdd-sync.json. Managed by skdd link — never edit directly. The mirror exists so each harness can discover skills at its conventional path without N copies drifting in parallel.
Harness — the agent runtime that loads and executes skills (Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode, Goose, Amp, etc.). SkDD is harness-agnostic; configuration lives in docs/configuration.md.
Forge — the act of creating a new skill from an observed pattern. Trigger: 2-3 repeats of the same work, or an explicit request. Executed by the skillforge meta-skill.
Evolve — the act of updating an existing skill in place, usually to add an edge case, refine a step, or fix a script. Always prefer evolving an existing skill over forging a similar new one.
Compose — the act of one skill referencing another (<skill:deploy-preview> in the body, or metadata.requires: [api-endpoint] in the frontmatter) so agents can chain skills without duplicating their steps.
Archive — the act of retiring a skill that has decayed (unused past the staleness threshold) or been superseded. Reversible — see colony/evolution.md#archiving.
Skillforge — the meta-skill at skillforge/SKILL.md. Its single job is to guide an agent through the forge-a-new-skill flow.

What is a Skill Colony?

A skill colony is a discoverable, mutable collection of SKILL.md files — spanning one project or many — that agents read, fork, update, and retire as they work. It has three moving parts: a registry (what skills exist and where), an update protocol (who can change a skill and how), and a lifecycle (how skills enter, mature, and leave the colony). Everything else is convention.

The behaviour to keep in mind when designing or reviewing a colony:

Born when an agent notices a repeatable pattern and forges a new skill.
Grow when agents encounter edge cases and update the skill in place.
Reproduce when skills are forked across projects or colonies.
Compete when multiple skills solve the same problem — usage stats decide which one sticks.
Decay when skills go unused past the staleness threshold (see Archiving).

Colony vs. Library

Aspect	Skill Library	Skill Colony
Creation	Human authors skills	Agents forge skills during work
Maintenance	Human updates manually	Agents evolve skills through use
Discovery	Explicit import/reference	Agents search and match by description
Sharing	Copy-paste between projects	Fork, adapt, contribute back
Quality	Review-gated	Usage-weighted (popular skills survive)

Colony Architecture

flowchart TB
    subgraph Registry[Colony Registry &mdash; shared index of skills]
        direction LR
        PA["Project A<br/>skills/<br/>• deploy<br/>• scaffold<br/>• review"]
        PB["Project B<br/>skills/<br/>• deploy*<br/>• scaffold*<br/>• monitor"]
        PC["Project C<br/>skills/<br/>• review<br/>• scaffold*<br/>• deploy*"]
    end

    PA -->|fork| PB
    PB -->|evolve| PC
    PA -->|share| PC
    PC -.->|upstream fix| PA

    classDef project fill:#0f172a,stroke:#38bdf8,stroke-width:2px,color:#f8fafc;
    class PA,PB,PC project;

* = forked from another project. Arrows represent fork / evolve / share / upstream-fix flows — the colony is a graph of projects exchanging skills, not a tree.

Colony Lifecycle

Phase 1: Genesis

An agent is working on a task and notices friction:

"I've scaffolded 3 API endpoints this session,
each time doing the same steps. This should be a skill."

The agent invokes skillforge and creates .skills/api-endpoint/SKILL.md.

The same agent (or another) uses the skill and hits an edge case:

"The api-endpoint skill doesn't handle authentication middleware.
Let me update it."

The skill evolves. The SKILL.md gets a new section. Maybe a script gets added.

Phase 3: Colony Spread

Another project needs API endpoint scaffolding. The agent discovers the skill via the colony registry:

"Found api-endpoint skill from project-alpha.
Forking and adapting for this project's conventions."

The skill is forked. The fork diverges (different auth patterns, different frameworks). Both versions are valid.

Phase 4: Natural Selection

Over time, some skills get used constantly. Others rot. The colony registry tracks usage:

api-endpoint        ████████████  (used 47 times across 5 projects)
deploy-preview      ██████████    (used 31 times across 3 projects)
xml-parser          █             (used once, 4 months ago)

Low-usage skills can be archived. High-usage skills can be promoted to “core” status.

Registry Format

The colony registry is a simple markdown file that lives at the colony level:

## Available Skills

| Skill | Source | Last Used | Uses | Description |
|-------|--------|-----------|------|-------------|
| api-endpoint | local | 2026-02-28 | 12 | Scaffold REST endpoints with validation |
| deploy-preview | forked:project-alpha | 2026-02-27 | 8 | Deploy preview branches to staging |
| component-scaffold | local | 2026-02-25 | 15 | Create React components with tests |
| bug-triage | forked:ops-team | 2026-02-20 | 5 | Triage bug reports into actionable issues |

Agents read this file at session start to know what’s available. They update it when skills are used, created, or evolved.

Discovery Mechanisms

How does an agent in Project C find a skill from Project A?

Option 1: Explicit registry (simplest)

A shared .skills-registry.md that lists skills across projects. Works for small teams.

Option 2: Git-based discovery

Skills live in a central repo (like this one). Projects fork what they need. Updates flow through PRs.

Agents publish skills to a shared endpoint. Other agents query by description similarity. This is the most autonomous but requires infrastructure.

Recommended starting point: Option 2

Fork skills from a central repo. Evolve locally. Contribute improvements back via PR. Simple, auditable, human-reviewable.

Anti-Patterns

Over-forging

Creating a skill for every single task. A skill should be reused at least 3 times before it earns its place.

Skill sprawl

Too many overlapping skills with no curation. The registry should be reviewed periodically (by humans or agents).

Frozen skills

Skills that were forged once and never updated. If a skill hasn’t been touched in 90 days and isn’t being used, archive it.

Monolith skills

Skills that try to do too much. If a SKILL.md is over 300 lines, it should probably be split into composed skills.