Agent Capability Registry
An agent capability registry is the catalog of actions, patterns, and source artifacts an agent can use, install, learn from, or promote: tools, MCP servers, skills, CLIs, runtimes, remote agents, templates, workflows, automations, examples, and policy metadata.
Why it matters
Agents fail when capability discovery is ad hoc. They either cannot find the right tool, over-expose every tool, or use a capability that is technically available but inappropriate for the task. A registry makes capability selection explicit and governable.
The MCP Registry is the clearest protocol-level example: it stores metadata for public MCP servers, including package/remote execution information and capabilities. But the registry is discovery, not trust. Kevin's stack needs a broader local concept that includes MCP servers, skills, CLIs, browser tools, model/runtime choices, source artifacts, templates, workflow patterns, and approval policy. Source: MCP Registry docs, https://modelcontextprotocol.io/registry/about, 2026-06-18
The registry should not require a capability to be installable. A reusable article, design technique, starter template, eval rubric, browser verification loop, or recurring source-ingest pattern can change agent behavior as much as a package. Those capabilities promote into different surfaces: skill files, wiki pages, trigger evals, automations, source-compile rules, or compact routing docs. Source: User request, 2026-06-25
Full Corpus Workflow and Capability Program defines the lifecycle semantics the registry was previously missing. Discovery, decision, presence, configuration, authentication, health, workflow binding, authority, and freshness are independent axes. A package can be installed but inactive; a design pattern can be adopted without being installable; a healthy tool can remain trial-only; and a saved repository can remain reference evidence indefinitely.
Registry vs router vs policy
| Layer | Question | Kevin example |
|---|---|---|
| Registry | What capabilities exist, how are they invoked, who owns them, and what do they require? | skills/**/SKILL.md, MCP Registry, Agent Machines web/data/*.json |
| Router | Which capability should this task use first? | Capability Routing Map, Skill Resolver |
| Policy | Is this capability allowed here, with these credentials and side effects? | tool permissions, MCP allowlists, approval gates |
| Action surface | What should an agent run first for a concrete intent? | Actionable Tools Index |
Do not collapse these layers. A registry without routing is a warehouse. A router without a registry is vibes. Policy without either becomes a bureaucratic prompt blob. An action surface without the other three becomes a stale shortcut menu, which is how agents end up confidently reaching for last month's shiny wrench.
Minimum useful schema
| Field | Purpose |
|---|---|
| Name and slug | Stable identity for linking, install, audit, and deprecation |
| Capability class | Tool, skill, CLI, MCP server, remote agent, model, runtime, substrate, preset, template, pattern, automation |
| Source class | Registry, docs, changelog, repo, X bookmark, article, transcript, design folder, product demo |
| Invocation surface | Function schema, CLI command, MCP endpoint, API route, A2A agent card, skill trigger |
| Auth requirements | Tokens, OAuth scopes, local session, BYOK, org credentials |
| Permission tier | Read-only, write, destructive, external spend, private data, production |
| Install/boot instructions | Packages, env vars, setup commands, sandbox requirements |
| Input/output contract | JSON schema, file artifacts, streaming events, token limits |
| Routing hints | Best tasks, anti-tasks, fallback, preferred harness |
| Promotion target | Skill, tool page, design page, workflow, architecture note, automation, trigger eval, source-compile rule |
| Evidence artifacts | Original post, article, repo, demo, screenshot, video, comments, example output |
| Evaluation metadata | Known tests, benchmarks, smoke checks, failure modes |
| Owner and freshness | Maintainer, last verified date, deprecation path |
IRL comparison
| Registry shape | What it gets right | Missing piece |
|---|---|---|
| MCP Registry | Public metadata for MCP servers and install/config discovery | It does not approve trust or quality for Kevin's environment |
| Skills.sh - Agent Skills Registry | Reusable agent procedures distributed as files | Needs local audit, dedupe, and resolver integration |
| Package registries | Versioning and installation at ecosystem scale | Usually unaware of agent safety, task fit, or token cost |
| Agent2Agent (A2A) agent cards | Discovery of remote agent capabilities and modalities | Delegation policy and outcome evaluation still live locally |
| Agent Machines loadout/registry | Product-level bundle of skills, MCPs, service routes, runtimes, and presets | Must keep counts generated and avoid stale marketing constants |
| Source/artifact registries | Finds patterns in posts, comments, docs, demos, transcripts, and design folders | Needs promotion rules so useful artifacts become durable behavior |
State of the art direction
- Public registries standardize metadata.
- Local control planes decide trust, auth, and approval.
- Runtimes expose smaller typed tool surfaces instead of huge undifferentiated lists.
- Skills become installable capabilities, not just prompt snippets.
- Capability metadata starts to include evals, examples, and failure modes.
- Remote agents become discoverable capabilities through A2A-like descriptors, not only tools.
Kevin rule
Before adding a new capability, check whether an existing registry layer already owns it:
- Executable procedure: add or update
skills/**/SKILL.md. - Capability facts and tradeoffs: add or update
wiki/tools/orwiki/concepts/. - Visual/interface technique: add or update
wiki/design/orwiki/style/. - Repeated operational cadence: add or update
automations/and Operational Heartbeat routing. - Source-ingest behavior: add or update Source Compile Workflow or capture rules.
- First-action routing: update Skill Resolver or Capability Routing Map.
- Install/discovery inventory: update the relevant MCP/skill/loadout registry.
- Safety/governance: add permission tier, auth notes, and verification.
If the same tool appears twice, decide whether it is a valid skill/tool mirror before merging.
Harvest layer
Kevin's local capability registry now has a repeatable harvest path: npm run harvest:capabilities snapshots skills.sh, the official MCP Registry, Smithery, the curated CLI seed catalog, and the capability class / non-registry source matrix into raw/registries/agent-capabilities/YYYY-MM-DD/. The snapshots are discovery inventory, not approval. Promotion still happens through Capability Harvest Pattern, npm run promote:capabilities, Skill Resolver, Capability Routing Map, Active Stack (What to Actually Use), trigger evals, and local policy. For SaaS/infra CLIs, Cloud, Data, and Service Skills and Service CLI Coverage are the current horizontal promotion layer. For non-installable patterns, the promotion layer is the natural owning surface: skill, page, automation, test, capture rule, or routing update. Source: User request, 2026-06-22; User request, 2026-06-25
External catalog adapter contract
Broad catalogs enter the registry through a source-specific snapshot adapter, not by copying their recommendations into the active stack. There are two projection modes:
- Enumerated discovery emits source revision/hash, stable candidate identity, category, labels, official/source links when present, and enough line-level provenance to diff a future snapshot.
- Guarded manifest emits only revision, content-addressed file metadata, categories/risk lanes, counts, and diffs. Candidate projection stays off when a catalog is mixed-risk, rights-unclear, or too broad to make a bulk recommendation surface responsible.
In both modes catalog labels remain source assertions: “open source,” “free,” “native,” “safe,” “starred,” and “App Store” still require current first-party checks for the selected candidate. Popularity may increase review priority; it cannot grant trust, installation permission, or workflow binding.
Awesome-Mac is the first concrete adapter:
npm run harvest:mac-apps
It snapshots 1,257 candidates across 25 sections and 60 category paths into
raw/registries/macos-apps/<date>/awesome-mac.json, preserving 656 open-source,
786 free/personal-free, 190 App Store, and 19 native labels as discovery
metadata. Its catalog license surfaces currently conflict—LICENSE and GitHub
say CC0-1.0, README says CC BY 4.0, and package metadata says CC-BY-SA-4.0—so
none of those licenses are inherited by listed applications. Selection still
requires dedupe, official-source/license/maintenance verification, a bounded
trial, doctor, and named workflow binding. Source: jaywcjlove/awesome-mac
bab7c005f1b9b6f0ed12529f23c2b3f19c69f415, captured 2026-08-11
FMHY is the first guarded-manifest adapter:
npm run harvest:fmhy
The current snapshot retains 85 catalog pages and 101 supporting notes from
fmhy/edit@72ea2b5 as paths, Git blob hashes, sizes, and review lanes while
projecting no candidate URLs. Seven media-heavy pages are high-risk; every
other page remains review-first rather than being called safe. The main FMHY,
catalog, and bookmark repositories declare no detected license, and the
catalog mixes legitimate tools with piracy/unauthorized-access material. A
named legitimate job may open one relevant slice and verify targets directly;
the system never bulk-imports the catalog or uses it to facilitate unauthorized
access. Source: FMHY; local guarded-catalog snapshot, 2026-08-11
Concept Position
| Field | Value |
|---|---|
| Concept family | Agent harness and runtime primitives |
| Concept owned | An agent capability registry is the catalog of actions, patterns, and source artifacts an agent can use, install, learn from, or promote: t... |
| Category map | Concept System Map |
Timeline
- 2026-08-11 | Split external catalogs into enumerated-discovery and
guarded-manifest modes; added
npm run harvest:fmhywith four contract tests so a high-signal mixed-risk source stays retained and diffable without becoming bulk recommendation or install authority. Source: X/@ihtesham2005;fmhy/edit@72ea2b5; local harvest receipt - 2026-08-11 | Added the external-catalog adapter contract and a tested
Awesome-Mac snapshot command, preserving all 1,257 categorized candidates
while preventing popularity, labels, sponsor placement, or conflicting
catalog licenses from becoming install authority. Source: X/@XAMTO_AI;
jaywcjlove/awesome-mac; local harvest receipt - 2026-07-15 | Linked the registry to the full-corpus workflow/capability program and separated discovered, reference, candidate, installed, configured, authorized, healthy, workflow-bound, active, replaced, and retired states. Source: User request and local corpus census, 2026-07-15
- 2026-07-01 | Concepts category refresh added this page to the Agent harness and runtime primitives family, linked it to Concept System Map, and kept it standalone because it owns this reusable mental model: An agent capability registry is the catalog of actions, patterns, and source artifacts an agent can use, install, learn from, or promote: t... Source: User request, 2026-07-01
- 2026-07-01 | Added Actionable Tools Index as the action-surface layer: registry = what exists, router = what wins, policy = what is allowed, action index = what an agent should run first for a concrete intent. Source: User request, 2026-07-01
- 2026-06-25 | Expanded the registry definition to include non-installable capabilities such as source artifacts, templates, design techniques, eval/review patterns, automations, and source-compile rules. Source: User request, 2026-06-25
- 2026-06-22 | Added a promotion-audit layer and the service CLI registry/coverage pages so harvested SaaS/infra candidates become routed intelligence without blind MCP installation. Source: User request, 2026-06-22
- 2026-06-22 | Added the capability harvest layer: dated raw snapshots for skills.sh, MCP registries, Smithery, and CLI seeds, with promotion kept separate from discovery. Source: User request, 2026-06-22
- 2026-06-18 | Created to explain the shared primitive behind MCP Registry, skills.sh, SKILL-RESOLVER, and Agent Machines loadouts. Source: whole-wiki graph audit, 2026-06-18