cleveragents-core/docs/adr/ADR-028-agent-skills-standard.md

---
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 <Jeffrey.Freeman@CleverThis.com>
    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.