🧾 Agentspecs

Declarative YAML specifications for AI agents, MCP servers, skills and more...

What Is Agentspecs?

Agentspecs is the source of truth for runtime catalogs compiled into Python and TypeScript.

The repository currently defines these spec families:

• Agent specs
• Team specs
• MCP server specs
• Skill specs
• Tool specs
• Environment variable specs
• Model specs
• Memory specs
• Guardrail specs
• Eval specs
• Trigger specs
• Output specs
• Notification specs

Key Properties

• Single Source of Truth: YAML files are the authoritative specification
• Declarative: Define what the system should do, not implementation details
• Composable: Specs reference each other by stable IDs
• Validated: JSON Schema ensures consistency and correctness
• Extensible: Easy to add new fields or specification types
• Human-Readable: YAML format is easy to read and edit

Versioning

All specs are versioned and include:

• id
• version (currently 0.0.1)

Cross-spec references should use id:version format (for example tavily:0.0.1).

Generated catalogs are keyed by unversioned id only (e.g. tavily). The get_* / get*Spec accessor functions accept both bare ids and versioned refs (tavily:0.0.1), stripping the version suffix automatically. Iterating catalog values returns each spec exactly once.

Directory Structure

agentspecs/
├── agents/
├── teams/
├── mcp-servers/
├── skills/
├── tools/
├── envvars/
├── models/
├── memory/
├── guardrails/
├── evals/
├── triggers/
├── outputs/
└── notifications/

Writing Specs

1. Create or update a YAML file in the relevant folder.
2. Always set id and version.
3. Prefer explicit versioned references (id:version) for linked specs.
4. Keep IDs stable and bump version for breaking changes.

Documentation

📄️ Agentspecs

Declarative YAML specifications for AI agents, MCP servers, skills and more...

📄️ Agents

Agent specifications define runtime behavior, capabilities, and UX defaults for individual agents.

📄️ MCP Servers

MCP (Model Context Protocol) server specifications define how agents connect to external tools and services.

📄️ Skills

Skill specifications define reusable capabilities that agents can use, implemented as Python modules.

📄️ Env Vars

Environment variable specifications define configuration values required by MCP servers and skills.

📄️ Models

Model specifications define the AI models available to agents. Each specification captures the model's identity, provider, required credentials, and whether it is the default model used when no explicit model is configured.

📄️ Tools

Tool specs define runtime-callable tools and their implementation bindings.

📄️ Teams

Team specs define multi-agent orchestration behavior.

📄️ Memory

Memory specs define selectable memory backends for agents.

📄️ Guardrails

Guardrail specs define policy and permission envelopes for agents.

📄️ Evals

Eval specs define reusable benchmark/evaluation suites.

📄️ Triggers

Trigger specs define reusable run triggers (for example once, schedule, event).

📄️ Outputs

Output specs define standardized output channel/templates for agent results.

📄️ Notifications

Notification specs define reusable notification channels and field templates.

Notes

• Use kebab-case IDs for most specs.
• Use UPPER_SNAKE_CASE IDs for env vars.
• Keep references explicit and versioned.

License

Copyright (c) 2025-2026 Datalayer, Inc.
Distributed under the terms of the Modified BSD License.