jersonboydmilan/agent-skills-compendium

---

A structured intelligence layer for building, understanding, and deploying AI agent capabilities.

This is a capability registry, not a prompt library. The distinction it is built on:

• 🔧 A tool is something an agent can use — a browser, a SQL client, a deployment system.
• 🧠 A skill is something an agent knows how to accomplish — with a trigger, inputs, a procedure, validation criteria, failure modes and an escalation path.

A skill may invoke several tools to produce a validated outcome.

🧭 Contents

📐 Where this sits

┌───────────────────────────────┐
│          AI MODELS            │
│    Intelligence / Reasoning   │
└───────────────┬───────────────┘
                ↓
┌───────────────────────────────┐
│        TOOL PROTOCOLS         │
│     Connectivity / Access     │   MCP, function calling, HTTP
└───────────────┬───────────────┘
                ↓
┌───────────────────────────────┐
│             TOOLS             │
│      APIs / Data / Systems    │
└───────────────┬───────────────┘
                ↓
╔═══════════════════════════════╗
║    AGENT SKILLS COMPENDIUM    ║
║                               ║
║  Taxonomy                     ║
║  Ontology                     ║
║  Specification                ║
║  Composition                  ║
║  Evaluation                   ║
║  Governance                   ║
╚═══════════════╤═══════════════╝
                ↓
┌───────────────────────────────┐
│           WORKFLOWS           │
│      Skill Composition        │
└───────────────┬───────────────┘
                ↓
┌───────────────────────────────┐
│            AGENTS             │
│     Autonomous Execution      │
└───────────────────────────────┘

🚫 What this is not

Not a prompt library. A prompt produces a result once. A skill declares a trigger, typed inputs, a procedure, validation criteria, failure modes and an escalation path — and can therefore be tested, governed and composed.

Not a tool protocol. MCP and equivalents answer how an agent reaches a system. A skill answers what it is trying to accomplish and how it knows it succeeded. They compose; neither replaces the other.

Not a replacement for SKILL.md. That is a packaging format. A definition here renders into it — npm run export:skills produces all 76 as SKILL.md packages.

Not a runtime. The definitions are data. Enforcement of the governance model belongs to whatever executes them, deliberately, so the definitions stay portable. The agent fleet is not a counter-example: it rehearses definitions against themselves, with no tool access and no side effects, which is precisely the line a runtime would have to cross.

Not a finished standard. An open reference framework at v0.3, stable enough to build against and expected to move.

See docs/INTEROPERABILITY.md for the full position.

✍️ Authorship

Created and originally architected by Jerson Boyd Milan

The Agent Skills Compendium was initiated and developed as a structured framework for defining, organizing, discovering, and composing reusable capabilities for AI agents.

Website: https://jersonboydmilan.com/

Copyright © 2026 Jerson Boyd Milan. See COPYRIGHT.md, AUTHORS.md and PROVENANCE.md.

Licensed under the MIT License. Every skill definition also carries license: MIT in its own metadata, so a definition extracted from the registry travels with its license attached.

📦 What is here

Every skill answers ten questions completely: what it does, when to use it, what it needs, what tools it may use, how it executes, how it validates the result, what goes wrong, when it should escalate, what it produces, and which skills it connects to.

⚡ Running it

git clone https://github.com/jersonboydmilan/Agent-Skills-Compendium.git
cd Agent-Skills-Compendium
npm install
npm run dev          # http://localhost:3000

Requires Node 20 or newer. There is no database, no API key and no environment file — the registry is YAML on disk, read at request time.

Five minutes well spent, once it is up:

Other scripts:

npm run build             # production build; prerenders every skill, category and layer route
npm run check             # typecheck + lint + content validation + tests
npm run typecheck         # tsc --noEmit
npm run lint              # eslint, flat config
npm run validate:content  # schema + referential integrity across the whole registry
npm test                  # node --test over the search, relation, export and registry logic

validate:content is the gate. It enforces the canonical schema on every YAML file, checks that filenames match slugs, that ids are unique, that every category, layer and tool exists, and that every skill-to-skill relationship resolves to a real skill. It exits non-zero on any error.

npm test runs on Node’s built-in test runner, so the suite adds no test dependency to the project. It covers search scoring and facet filtering, relationship resolution and execution ordering, YAML/JSON export round-tripping, and the integrity of the published registry — every category, layer and tool reference, every relationship edge, and slug uniqueness.

🏛️ Architecture

content/                     the registry — this is the product
  layers.yaml                5 architectural layers
  categories.yaml            20 categories
  tools.yaml                 49 normalised tools
  skills/.yaml         one skill per file, `skill:` root

src/lib/
  schema.ts                  THE canonical Agent Skill Specification (zod)
  repository.ts              SkillRepository — the read contract every backend implements
  content-store.ts           file-backed implementation; cached per process in production
  search.ts                  fuzzy scoring + facet filtering, shared by UI and API
  relations.ts               related groups, inverse edges, prerequisite closure, ordering
  export.ts                  YAML / JSON serialisation
  api.ts                     response envelopes, cache headers, query-parameter parsing
  api-spec.ts                the route list /api-reference renders from
  analytics.ts               typed event surface (skill_view, skill_search, skill_copy, …)

src/app/                     routes; every page is a server component reading the repository
src/app/api/                 the machine interface
tests/                       node --test suites over the lib layer and the registry

🔄 Swapping the storage backend

Nothing outside src/lib/content-store.ts knows the registry lives on disk. Pages and API routes depend on the SkillRepository interface only. Moving to Postgres, a KV store or a remote registry means implementing that interface and exporting a different repository — no page, component or route changes.

🔌 Machine interface

GET /api/skills                              filterable; add ?view=full for whole definitions
GET /api/skills/:slug
GET /api/skills/:slug/related                resolved edges, including inverse dependents
GET /api/skills/:slug/export?format=yaml     also json; add &download=1 for a file
GET /api/categories                          with live skill counts
GET /api/layers                              with live skill counts
GET /api/schema                              the canonical JSON Schema
GET /api/search?q=                           matches skills, categories and layers

POST /api/fleet                              deploy a fleet of agents against an objective
GET  /api/fleet/:id                          status, aggregate and feed
GET  /api/fleet/:id/agents                   the roster, filterable and paged
GET  /api/fleet/:id/agents/:agentId          one agent's whole run
GET  /api/fleet/:id/stream                   server-sent events while it runs
POST /api/fleet/:id/control                  pause, resume, abort, approve

The registry routes are cacheable and static. The /api/fleet routes are live state held in process memory, so they are never cached and do not survive a restart.

The /api/skills route accepts the same query parameters as the /skills page — q, category, layer, complexity, maturity, risk, tag, speed, share — so a URL a person is looking at and a URL an agent fetches describe the same result set.

Filters with a closed vocabulary (layer, complexity, maturity, risk, speed, share) answer a misspelled value with 400 and the accepted values, rather than an empty list that reads as “no such skill”. Unknown slugs return 404 with { error }. Every response is public, CORS-open and cacheable, and needs no authentication.

/api/schema serves the same generated JSON Schema that lives in schema/, so a definition can be validated without cloning the repository:

curl /api/skills/source-credibility-assessment/export?format=json > skill.json
curl /api/schema > skill.schema.json
npx ajv validate -s skill.schema.json -d skill.json

YAML export is round-trippable: the exported document has the same shape as the source file and re-validates against the schema unchanged.

🎬 Examples

What a definition actually looks like

An excerpt from content/skills/source-credibility-assessment.yaml. The parts that make it a skill rather than a prompt are the ones most registries leave out — decision rules, validation, failure modes with mitigations, and escalation.

skill:
  name: Source Credibility Assessment
  layer: L2
  purpose: >-
    Retrieval systems rank by relevance, not by trustworthiness, so an agent that
    treats retrieval order as credibility order will confidently repeat a
    marketing page or a content farm.
  trigger: >-
    Before any retrieved source is used to support a claim in a deliverable, and
    whenever two sources disagree.

  decision_rules:
    - condition: The publisher sells the thing the claim endorses
      action: Cap trust at low and label the claim vendor-sourced.
    - condition: No author, no date and no citations are present
      action: Reject the source for material claims regardless of apparent plausibility.

  validation:
    - check: The verdict is stated relative to the specific claim, not to the publication in general.
    - check: Every deduction in the rationale names an observable property of the source.

  failure_modes:
    - failure: Circular corroboration from three restatements of one origin.
      mitigation: Resolve the origin chain first; deduplicate by origin before counting.

  escalation:
    - condition: The only available sources for a material claim all score low.
      action: Report the claim as unestablished and escalate the sourcing gap rather than lowering the bar.

  risk_level: low
  required_permissions: [web.read]
  restricted_actions: [Bypassing paywalls, Circumventing access controls to inspect a source]

Ten more fields are omitted here — inputs, tools, the procedure, outputs, worked examples and the relationship graph. The full file is 150 lines, and every one of the 76 is specified to the same depth.

Ask the registry a question

curl -s 'localhost:3000/api/skills?layer=L5&risk=high' | jq '{count, total, skills: [.skills[].slug]}'

{
  "count": 5,
  "total": 76,
  "skills": [
    "agent-role-design",
    "autonomy-staging",
    "dry-run-rehearsal",
    "llm-judge-calibration",
    "release-readiness-check"
  ]
}

A misspelled facet value answers with 400 and the vocabulary, rather than an empty list that reads as “no such skill”:

curl -s 'localhost:3000/api/skills?risk=hgih'
# {"error":"Unknown risk value \"hgih\". Accepted: low, medium, high, critical."}

Follow the graph

Every skill declares prerequisites, complements and successors, and the API resolves the inverse edges too — so you can ask what depends on a skill, not only what it depends on.

curl -s localhost:3000/api/skills/prompt-injection-defense/related \
  | jq '[.groups[] | {relation, skills: [.skills[].slug]}]'

[
  {
    "relation": "complementary",
    "skills": ["tool-permission-scoping", "agent-red-teaming", "secure-code-review"]
  },
  {
    "relation": "successors",
    "skills": ["agent-red-teaming", "autonomy-staging"]
  },
  {
    "relation": "related",
    "skills": ["source-credibility-assessment", "memory-hygiene"]
  }
]

Drive an agent from a definition

The definitions are data, so this is the whole integration. Nothing here is Compendium-specific beyond the two URLs.

const REGISTRY = "http://localhost:3000";

// 1. Find candidates for the situation the agent is actually in.
const { skills } = await fetch(
  `${REGISTRY}/api/skills?q=untrusted+content&layer=L5`,
).then((r) => r.json());

// 2. Pull the full definition of the one you picked.
const { skill } = await fetch(`${REGISTRY}/api/skills/${skills[0].slug}`).then((r) =>
  r.json(),
);

// 3. Honour the governance surface before anything executes. The registry states
//    what a skill may not do; enforcing it is the runtime's job, deliberately.
if (!hasPermissions(skill.required_permissions)) {
  return escalate(skill.escalation);
}

// 4. The procedure is the plan. `validation` is the exit test — a run that cannot
//    satisfy every check has not succeeded, whatever the model reports.
for (const step of skill.procedure) await run(step);
return skill.validation.every(check);

Compose a workflow

Selection and workflow name live in the query string, so a composition is a link:

/compose?skills=source-credibility-assessment,evidence-synthesis,competitive-intelligence-report

The composer resolves prerequisites, orders the chain so nothing runs before its precondition, aggregates the permissions and tools the whole workflow needs, reports the highest risk level in it, and exports the result as an agent specification. It plans; it does not execute.

Export the registry into your own agent

npm run export:skills     # dist/skills///SKILL.md — all 76

---
name: source-credibility-assessment
description: Classify a source by class, independence, incentive and recency, and
  assign a defensible trust score before its content is used.
version: 1.1.0
category: research_intelligence
layer: L2
risk: low
license: MIT
---

# Source Credibility Assessment

Each definition carries license: MIT in its own metadata, so a skill extracted from the registry travels with its license attached. YAML export is round-trippable: the exported document has the same shape as the source file and re-validates against the schema unchanged.

🛰️ Agent fleet

Deploy hundreds of agents against one objective and watch every one of them. Each agent carries a skill set drawn from the registry — a primary skill, its prerequisite closure in dependency order, and its complements — so a fleet is the registry put under load.

It is a rehearsal, not an execution. No model is called and no tool is invoked. Each agent is played out against the definitions it carries:

So a fleet is only ever as good as the definitions it runs — which is the point. A skill whose failure modes are imaginary produces imaginary failures, and three hundred agents is a fast way to see which definitions are carrying their weight.

Clicking any agent opens its whole run: the skill set, every step, each failure mode it hit beside the mitigation its own definition prescribes, the validation checks that decided the outcome, and the permissions, tools and restricted actions it carries.

The approval gate is the governance model, enforced. approvalThreshold holds every agent at or above a risk level before it runs; the fleet runs everything below the line, then pauses and says it is waiting on a person. An agent’s risk is the highest in its whole skill set, not just its primary skill.

curl -X POST localhost:3000/api/fleet -H 'content-type: application/json' \
  -d '{"objective":"Harden the agent surface","size":120,"strategy":"spread","approvalThreshold":"high","seed":1}'

The same seed and registry replay the same fleet — same agents, same failures, same outcome — so two rehearsals are comparable and any difference between them is the registry’s. Fleets live in process memory and do not survive a restart.

docs/FLEET.md has the roster strategies, the determinism guarantee, the live-update protocol and the limits.

➕ Adding a skill

1. Copy an existing definition (every skill page exposes its YAML).
2. Write it to content/skills/.yaml. The filename must match the slug.
3. Run npm run validate:content.
4. Version it. New skills start at 1.0.0. A procedure change is a minor bump; a change to inputs, outputs or validation is a major bump, because it breaks consumers.

docs/SKILL_AUTHORING.md is the practical guide — what each field is for, the failure each admission rule prevents, worked ✅/❌ pairs for the fields that get sent back in review, and a complete minimal skill that validates as written. The same standard is rendered at /contribute in the running application.

The one question that decides admission: can you state how the skill knows it succeeded? If not, it is a prompt.

🙌 Contributing

The most valuable contribution is not a new skill — it is a correction to an existing one from someone who does the work. A failure mode that is not real, a validation check that cannot be checked, a procedure that is not how it is actually done: those pull requests are the ones that make the registry worth consuming.

Everything runs locally with npm install && npm run dev — no database, no API key, no environment file. npm run check is exactly what CI runs.

🗒️ Notes on the current build

• Typography uses system font stacks rather than a webfont, so the build has no network dependency. Swapping in a licensed face is a change to --font-sans / --font-mono in src/app/globals.css.
• Analytics events are queued on window.__skillCompendiumEvents for a collector to drain. No vendor is wired up.
• The composer is client-side and produces a workflow specification; it does not execute anything. Execution is deliberately out of scope for v1 but nothing in the data model blocks it. Its selection and workflow name live in the query string, so a composition survives a refresh and can be shared as a link — /compose?skills=,.
• Content is parsed once per process in production and re-read per request in development, so editing a YAML file shows up on the next reload without restarting the server.
• Colour tokens in src/app/globals.css are held to WCAG AA (4.5:1) against every surface they are used on, in both the light and dark palettes.

🖥️ Interface

🔍 Registry

Search and seven filter facets over the whole registry — architectural layer, category, complexity, maturity, build speed, shareability and risk level. Facet counts are live, and options that would return nothing are disabled rather than hidden. Filter state is held in the URL, so a filtered view is shareable and survives a refresh. Below the lg breakpoint the facets collapse behind a disclosure carrying the active count, so results stay at the top of a phone screen.

📄 Skill detail

Every skill renders its full specification: purpose, trigger, typed inputs, tools, procedure, decision rules, outputs, validation, failure modes, escalation, worked examples, relationships and the governance surface (risk level, required permissions, restricted actions).

🧩 Composer

Select skills and the composer resolves their prerequisites, orders them for execution, aggregates required permissions and tools, reports the highest risk level in the chain, and exports the result as an agent specification.

🧱 Frameworks

Beyond the registry itself, three framework layers make the definitions testable, governable and portable:

Generated artifacts are never hand-maintained:

npm run generate:schema   # schema/ from src/lib/schema.ts, self-tests on all 76 skills
npm run export:skills     # dist/skills/**/SKILL.md packages

📄 Project documents

---

⭐ Star History

---