# ADR-028: Agent Skills Standard (AgentSkills.io)

**Status:** Proposed  
**Date:** 2026-02-17  
**Supersedes:** None  
**Author(s):** CleverAgents Team  
**Approver(s):**

## 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

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.

## Related ADRs

| ADR | Title | Relationship |
|-----|-------|-------------|
| [ADR-010](ADR-010-actor-and-agent-architecture.md) | Actor and Agent Architecture | Agent Skills appear as tool nodes in actor graphs |
| [ADR-011](ADR-011-tool-system.md) | Tool System | Agent Skills are a tool source integrated into the Tool Registry |
| [ADR-012](ADR-012-skill-system.md) | Skill System | Agent Skills are exposed and composed within skills |
| [ADR-015](ADR-015-sandbox-and-checkpoint.md) | Sandbox and Checkpoint | Sub-tool-calls within skill execution are individually checkpointed |
| [ADR-025](ADR-025-observability-and-logging.md) | Observability and Logging | Multi-step skill execution requires structured tracing |
| [ADR-029](ADR-029-model-context-protocol.md) | Model Context Protocol (MCP) Adoption | Agent Skills commonly orchestrate MCP tools within workflows |
| [ADR-030](ADR-030-skill-abstraction-definition.md) | Skill Abstraction Definition | Agent Skills are one of the four tool sources unified under the skill abstraction |

## Acceptance

### Votes For

| Voter | Comment |
|-------|---------|

**Total: 0**

### Votes Against

| Voter | Comment |
|-------|---------|

**Total: 0**

### Abstentions

| Voter | Comment |
|-------|---------|

**Total: 0**
