Skip to content

README.md

Latest commit

 

History

History
366 lines (231 loc) · 7.37 KB

README.md

File metadata and controls

366 lines (231 loc) · 7.37 KB

Agent Skill Registry

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

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.

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:

text.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 → text.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:

text.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: text.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/validate_registry.py
python tools/generate_catalog.py
python tools/registry_stats.py
python tools/governance_guardrails.py
python tools/capability_governance_guardrails.py
python tools/enforce_capability_sunset.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:

  • 111 capabilities
  • 35 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/SKILL_FORMAT.md
docs/GOVERNANCE.md
docs/SKILL_ADMISSION_POLICY.md
docs/SEMANTIC_FAMILY_MAP.md
docs/CAPABILITY_ADMISSION_POLICY.md
docs/CAPABILITY_COMPATIBILITY_POLICY.md
docs/CAPABILITY_SUNSET_POLICY.md
docs/VOCABULARY_BUSINESS_WORKFLOW_COVERAGE.md docs/CANONICAL_METRICS.md

Governance artifact:

catalog/governance_guardrails.json
catalog/capability_governance_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.