--- adr_number: 28 title: Agent Skills Standard (AgentSkills.io) status_history: - - '2026-02-17' - Proposed - Jeffrey Phillips Freeman - - '2026-02-17' - Accepted - Jeffrey Phillips Freeman tier: 4 authors: - Jeffrey Phillips Freeman superseded_by: null related_adrs: - number: 10 title: Actor and Agent Architecture relationship: Agent Skills appear as tool nodes in actor graphs - number: 11 title: Tool System relationship: Agent Skills are a tool source integrated into the Tool Registry - number: 12 title: Skill System relationship: Agent Skills are exposed and composed within skills - number: 15 title: Sandbox and Checkpoint relationship: Sub-tool-calls within skill execution are individually checkpointed - number: 25 title: Observability and Logging relationship: Multi-step skill execution requires structured tracing - number: 29 title: Model Context Protocol (MCP) Adoption relationship: Agent Skills commonly orchestrate MCP tools within workflows - number: 30 title: Skill Abstraction Definition relationship: Agent Skills are one of the four tool sources unified under the skill abstraction acceptance: votes_for: - voter: Jeffrey Phillips Freeman comment: AgentSkills.io adoption enables a portable skill ecosystem that works across agent frameworks votes_against: [] abstentions: [] --- ## Context CleverAgents needs a portable way to package instruction-driven workflows that go beyond single tool calls. An agent following a deployment checklist, for example, must orchestrate multiple MCP tools, make decisions based on intermediate results, and follow domain-specific best practices — something a single schema-driven tool call cannot express. These workflows should be shareable across teams, compatible with different agent runtimes, and efficient to load (only paying token cost when actually used). A standard format reduces fragmentation and enables a broader ecosystem of reusable skills. ## Decision Drivers - Multi-step instruction-driven workflows (e.g., deployment checklists) cannot be expressed as single schema-driven tool calls and need a packaging format - Skills must be portable across teams and compatible with different agent runtimes to avoid vendor lock-in - Token cost must be minimized at startup; full instructions should load only when the skill is actually invoked (progressive disclosure) - Agent Skills must compose naturally with MCP tools, built-in tools, and other tool sources within actor graphs - A standard format reduces ecosystem fragmentation and enables community sharing of reusable skill definitions ## Decision CleverAgents adopts the **Agent Skills standard** from [https://AgentSkills.io](https://AgentSkills.io). Skills are authored as `SKILL.md` files with optional `scripts/`, `references/`, and `assets/` directories, and are ingested as a tool source (`agent_skill`) with progressive disclosure. ## Design ### Discovery and Registration - Skill folders are discovered via paths configured in skill YAML (`agent_skills` section). - `SKILL.md` frontmatter provides metadata: name, description, tags. - Each Agent Skill is registered as a tool record with source `agent_skill` in the Tool Registry. - Name collisions with existing tools or validations are rejected at registration time. ### Progressive Disclosure | Tier | What loads | When | Token cost | |------|-----------|------|------------| | **Metadata** | `name` + `description` from SKILL.md frontmatter | Tool registration / actor activation | ~50–100 tokens per skill | | **Instructions** | Full SKILL.md Markdown body | When the LLM determines the task matches (activate phase) | Recommended < 5,000 tokens | | **Resources** | `scripts/`, `references/`, `assets/` | On demand during execution | Variable | This three-tier model means an actor can have dozens of Agent Skills available while only paying the metadata token cost at startup. Full instructions load only when relevant. ### Execution Model - Agent Skills are **instruction-driven**: the LLM actor reads the SKILL.md instructions and follows the prescribed procedure. - During execution, the agent may invoke any other tool in its assigned skill set — MCP tools, built-in tools, or other Agent Skills. - Scripts provided with the skill are never auto-executed; they must be invoked via explicit tool calls (e.g., a `shell` or `python` tool). - Each sub-tool-call within the skill's execution is individually checkpointed, enabling fine-grained rollback. ### Actor Graph Integration - Agent Skills are exposed through skill YAML and flattened into the actor's tool set during skill resolution. - Inside actor graphs, Agent Skills appear as **tool nodes** — identical in shape to MCP tool nodes or built-in tool nodes. - When the actor runtime activates an Agent Skill tool node, it loads the SKILL.md instructions into the LLM context and the agent follows the procedure. - A single Agent Skill tool node execution may generate multiple downstream tool calls (including calls to MCP tools), all tracked in the plan's change set. ### Composing MCP Tools and Agent Skills A common and powerful pattern is an Agent Skill that teaches the agent a workflow involving multiple MCP tools: ``` Agent Skill Tool: "local/deploy-staging" SKILL.md instructions: 1. Run tests using the built-in shell tool 2. Create a PR using the GitHub MCP tool (create_pull_request) 3. Wait for CI using the GitHub MCP tool (get_check_runs) 4. Deploy using the AWS MCP tool (ecs_update_service) 5. Verify deployment using the HTTP MCP tool (fetch_url) ``` This composition is a key design principle: Agent Skills extend the agent's *knowledge* (multi-step procedures, domain best practices), while MCP tools extend its *toolset* (callable functions). The two are complementary and coexist naturally within the same skill. ## Constraints - Skill discovery must be read-only and side-effect free. - Full instruction loading must follow progressive disclosure rules — SKILL.md body must not load until the activate phase. - Agent Skills must integrate with the Tool and Skill registries without name collisions. - Skill execution must respect sandbox and checkpoint policies for all tool calls made during the procedure. - Scripts bundled with a skill must never be auto-executed. ## Consequences ### Positive - Portable, reusable workflows with minimal vendor lock-in — any AgentSkills.io-compatible runtime can consume the same SKILL.md files. - Reduced prompt duplication through standardized packaging. - Efficient context usage through progressive disclosure (metadata-only at startup). - Natural composition with MCP tools within actor graphs. ### Negative - Instruction-driven execution can be less deterministic than single-call schema-driven tools. - Debugging multi-step skill execution requires tracing through multiple tool calls, demanding stronger observability (ADR-025). ### Risks - Poorly authored SKILL.md files (verbose instructions, unclear procedures) could waste context budget or confuse the agent. - Over-reliance on instruction-driven skills could hide important decision points from the decision tree. ## Alternatives Considered **Proprietary skill format** — Faster to implement but locks users into a non-standard ecosystem and prevents sharing with the broader agent community. Rejected. **Inline prompts only** — Simple but leads to prompt duplication, inconsistent practices across actors, and no progressive disclosure. Rejected. **MCP-only tooling** — MCP tools are schema-driven and cannot express multi-step procedures with conditional logic. They are complementary, not a replacement. Rejected as a sole tool source. ## Compliance - **Discovery tests**: Verify that Agent Skills are discovered and registered without side effects. - **Progressive disclosure tests**: Ensure metadata, instructions, and resources load at the correct lifecycle stages and not earlier. - **Registry integration tests**: Validate naming, source tagging (`agent_skill`), and skill-tool composition behavior. - **Sandbox tests**: Confirm that all tool calls made during skill execution respect sandbox and checkpoint requirements. - **Actor graph tests**: Verify that Agent Skill tool nodes activate correctly in actor graphs, load instructions, and produce tracked change sets.