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

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. 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	Actor and Agent Architecture	Agent Skills appear as tool nodes in actor graphs
ADR-011	Tool System	Agent Skills are a tool source integrated into the Tool Registry
ADR-012	Skill System	Agent Skills are exposed and composed within skills
ADR-015	Sandbox and Checkpoint	Sub-tool-calls within skill execution are individually checkpointed
ADR-025	Observability and Logging	Multi-step skill execution requires structured tracing
ADR-029	Model Context Protocol (MCP) Adoption	Agent Skills commonly orchestrate MCP tools within workflows
ADR-030	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