Agent Skill Registry

Agent Skill Registry

An open registry of reusable AI agent skills and capability definitions.

Terminology Note

For cognitive runtime terminology, we use:

• COGIT = capability
• SYLLOG = skill

In this repository implementation, we keep the canonical technical terms capability/capabilities and skill/skills (directory structure, schemas, tooling, catalogs, and validation contracts) to preserve architecture and compatibility.

Quick Start

pip install -r requirements.txt
python tools/validate_registry.py
python tools/generate_catalog.py

See the companion runtime at agent-skills for execution.

License

Apache 2.0 — see [LICENSE](LICENSE).

---

The registry provides a standardized, declarative way to define:

• primitive capabilities
• composable skills (workflows)
• shared vocabulary
• machine-readable catalogs

It acts as the source of truth for agent workflows that can be executed by compatible runtimes.

------------------------------------------------------------------------

Why this exists

AI agents increasingly rely on structured tools and workflows.

However, most implementations today are:

• tightly coupled to a specific framework
• implemented imperatively in code
• difficult to reuse across systems
• inconsistent in naming and structure

The Agent Skill Registry addresses this by providing:

• a common vocabulary
• a declarative workflow model
• a shared registry of reusable skills
• a machine-readable catalog for runtimes

The goal is to make agent capabilities discoverable, composable, and reusable.

------------------------------------------------------------------------

Core Concepts

The registry defines two fundamental building blocks.

Capabilities

Capabilities represent primitive operations.

They define a contract describing what an operation does, including:

• inputs
• outputs
• execution properties
• optional metadata

Examples:

reasoning.content.summarize\ web.page.fetch\ pdf.document.read\ audio.speech.transcribe\ code.diff.extract

Capabilities are not implementations.

They define what a runtime must implement, not how.

------------------------------------------------------------------------

Skills

Skills are composable workflows built from capabilities.

A skill defines:

• inputs
• outputs
• steps
• capability usage
• optional nested skill usage

Example skill:

web.fetch-summary

Workflow:

web.page.fetch → web.page.extract → reasoning.content.summarize

Skills allow building reusable agent behavior without writing imperative code.

------------------------------------------------------------------------

Registry Structure

agent-skill-registry\ │\ ├─ capabilities/\ │ Capability definitions\ │\ ├─ skills/\ │ Reusable workflows\ │\ ├─ catalog/\ │ Generated machine-readable catalogs\ │\ ├─ tools/\ │ Registry tooling\ │\ └─ docs/\ Specifications and language documentation

------------------------------------------------------------------------

Vocabulary

The registry enforces a controlled vocabulary to maintain consistency.

Capability identifiers follow the pattern:

domain.noun.verb

Examples:

perception.keyword.extract\ image.caption.generate\ data.schema.validate\ code.diff.extract

The vocabulary is defined in:

vocabulary.json

This ensures:

• consistent naming
• predictable semantics
• long-term maintainability

------------------------------------------------------------------------

Skills as Dataflow

Skills are declarative workflows.

Each step references a capability or another skill.

Example:

steps:

• id: fetch uses: web.page.fetch input: url: inputs.url output: content:

vars.page

• id: extract uses: web.page.extract input: content: vars.page output:

text: vars.text

• id: summarize uses: reasoning.content.summarize input: text: vars.text output:

summary: outputs.summary

Execution semantics:

inputs → steps → outputs

No imperative logic is embedded in the skill definition.

------------------------------------------------------------------------

Generated Catalog

The registry generates machine-readable catalogs used by runtimes.

catalog/capabilities.json\ catalog/skills.json\ catalog/graph.json\ catalog/stats.json

These provide:

• skill discovery
• dependency graphs
• usage statistics
• capability relationships

Catalogs are generated using:

tools/generate_catalog.py

------------------------------------------------------------------------

Validation

All registry content is validated using:

tools/validate_registry.py

Validation checks:

• schema correctness
• vocabulary compliance
• capability references
• skill dependency cycles
• identifier correctness

Run validation:

python tools/validate_registry.py

------------------------------------------------------------------------

Statistics

Registry statistics are generated automatically.

python tools/registry_stats.py

This produces:

catalog/stats.json

Including:

• capability usage
• unused primitives
• skill counts by domain
• metadata coverage

------------------------------------------------------------------------

Contributing

Contributions are welcome.

You may contribute:

• new capabilities
• new skills
• improvements to metadata
• documentation updates

Typical workflow:

1. Add capability or skill\
2. Run validator\
3. Regenerate catalog\
4. Submit pull request

Commands:

python tools/validateregistry.py\ python tools/generatecatalog.py\ python tools/registrystats.py\ python tools/governanceguardrails.py\ python tools/capabilitygovernanceguardrails.py\ python tools/enforcecapabilitysunset.py

------------------------------------------------------------------------

Design Principles

The registry follows several core principles.

Declarative

Skills describe what happens, not how.

Runtime-agnostic

The registry does not define execution engines.

Different runtimes may implement capabilities differently.

Composable

Skills can reuse capabilities and other skills.

Vocabulary-controlled

Naming follows a strict vocabulary to avoid fragmentation.

Open and extensible

The registry is designed to grow through community contributions.

------------------------------------------------------------------------

Relationship with Runtimes

This repository does not execute skills.

It defines the language and registry.

Execution is handled by compatible runtimes.

A runtime typically performs:

skill → step resolution → capability provider → execution

------------------------------------------------------------------------

Current Registry Scope

Current registry includes:

• 159 capabilities
• 37 skills
• validation tooling
• dependency graph generation
• registry statistics

This represents the first usable registry version.

------------------------------------------------------------------------

Documentation

Additional documentation:

docs/LANGUAGE.md\ docs/CAPABILITIES.md\ docs/SKILLFORMAT.md\ docs/GOVERNANCE.md\ docs/SKILLADMISSIONPOLICY.md\ docs/SEMANTICFAMILYMAP.md\ docs/CAPABILITYADMISSIONPOLICY.md\ docs/CAPABILITYCOMPATIBILITYPOLICY.md\ docs/CAPABILITYSUNSETPOLICY.md\ docs/VOCABULARYBUSINESSWORKFLOWCOVERAGE.md docs/CANONICAL_METRICS.md

Governance artifact:

catalog/governanceguardrails.json\ catalog/capabilitygovernance_guardrails.json

------------------------------------------------------------------------

Vision

The long-term goal is to create a shared ecosystem of agent skills that can be:

• discovered
• reused
• composed
• executed across runtimes

A common language for AI agent workflows.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gfernandf
• Source: gfernandf/agent-skill-registry
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.