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

adr_number, title, status_history, tier, authors, superseded_by, related_adrs, acceptance

adr_number	title	status_history	tier	authors	superseded_by	related_adrs	acceptance
28	Agent Skills Standard (AgentSkills.io)	2026-02-17 Proposed Jeffrey Phillips Freeman 2026-02-17 Accepted Jeffrey Phillips Freeman	4	Jeffrey Phillips Freeman	null	number title relationship 10 Actor and Agent Architecture Agent Skills appear as tool nodes in actor graphs number title relationship 11 Tool System Agent Skills are a tool source integrated into the Tool Registry number title relationship 12 Skill System Agent Skills are exposed and composed within skills number title relationship 15 Sandbox and Checkpoint Sub-tool-calls within skill execution are individually checkpointed number title relationship 25 Observability and Logging Multi-step skill execution requires structured tracing number title relationship 29 Model Context Protocol (MCP) Adoption Agent Skills commonly orchestrate MCP tools within workflows number title relationship 30 Skill Abstraction Definition Agent Skills are one of the four tool sources unified under the skill abstraction	votes_for votes_against abstentions voter comment Jeffrey Phillips Freeman <Jeffrey.Freeman@CleverThis.com> AgentSkills.io adoption enables a portable skill ecosystem that works across agent frameworks

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