ADR-0044: Skills — declarative agent capabilities as prompt modules

• Status: Accepted
• Date: 2026-06-15
• Deciders: @karasu, with colleagues
• Supersedes: —
• Superseded by: —
• Relates to: ADR-0022 (per-agent configuration), ADR-0024 (context budget management), ADR-0037 (compound prompts), ADR-0015 (federated config, project silos), ADR-0043 (MCP tools — skills complement tools)

Context

kaged's agent model has three ways to give an agent capabilities:

1. Tools — code-backed functions the agent calls (file.read, search.grep, code.lsp, MCP tools, plugin tools). Discrete, parameterised, returning structured results. The agent calls them explicitly.
2. System prompts — the agent's identity, rules, and domain knowledge. Loaded from markdown files. Continuous context, always present.
3. Subagents — delegated agents with their own prompts, models, and cages. The parent dispatches a task; the child returns a result.

There is a gap between these three. Consider what an operator wants when they say "this agent should know how to do code review" or "this agent should follow the project's deployment runbook." Today:

• Putting the full review methodology or deployment runbook into the system prompt works but bloats the context window for every turn — even turns where the agent isn't reviewing or deploying. ADR-0024's compaction mitigates this, but the prompt was loaded in the first place.
• Creating a subagent works for delegation ("review this PR") but is heavyweight — it's a separate agent with its own model, cage, and lifecycle. Not every capability needs to be a separate agent.
• Writing a tool doesn't fit — the capability isn't a discrete function with parameters and a return value. It's a methodology, a set of heuristics, a decision tree. "How to review code" is not a function you call; it's knowledge the agent applies while using other tools.

Skills fill this gap. A skill is a declarative agent capability defined as a structured prompt module that is injected into the agent's context on demand. Skills are composable, project-portable, and context-budget-aware.

The concept draws from the convergent "Agent Skills" pattern that has emerged across the coding-agent ecosystem — markdown files with structured frontmatter that encapsulate domain expertise as reusable, injectable knowledge blocks, distinct from both tools (which are code) and prompts (which are identity). This is a de facto standard shape; kaged's version is grounded in its existing architecture: skills are markdown files with YAML frontmatter, referenced from the project DSL, and resolved through the same project:/ and config:/ URI system as prompts.

The constraint set:

• Skills are prompt-based, not code. A skill does not execute code or call tools on its own. It provides structured instructions, heuristics, checklists, decision trees, or domain knowledge that the agent applies while using its existing tools.
• Skills are composable and orthogonal. An agent can have multiple skills. Skills should not conflict with each other. An agent with code-review and git-workflow skills should be able to apply both when reviewing a branch.
• Skills are context-budget-aware. Always-on skills consume context window budget on every turn. On-demand skills let the agent load heavy reference material (runbooks, API docs, troubleshooting trees) only when needed. This interacts with ADR-0024 (compaction).
• Skills are project-portable (ADR-0011). Skills are project content — they travel with the project. No secrets, no operator-local details.
• Skills are federated (ADR-0015). Skills can be shared across projects via config:/ URIs — an operator's personal skill library lives in their config directory.
• Skills are not subagents. A skill does not have its own model, cage, or lifecycle. It is injected context, not a separate reasoning entity.

Decision

kaged introduces skills as a fourth agent-capability surface alongside tools, prompts, and subagents. A skill is a structured markdown module — instructions, heuristics, checklists, or domain knowledge — that is injected into an agent's context. Skills are declared per-agent in the project DSL, resolved via the existing URI prefix system, and activated either always-on (injected at session start) or on-demand (injected when the agent calls a lightweight skill.use tool). A skill namespace is reserved for the on-demand activation tool and the skill:// internal URL scheme.

1. Skill file format

A skill is a markdown file named SKILL.md inside a skill directory. The directory may contain additional reference files (diagrams, examples, templates) that the agent accesses via the skill:// URL scheme.

Directory layout:

<skills-root>/
  ├─ code-review/
  │   ├─ SKILL.md                    ← skill definition
  │   ├─ checklist.md                ← reference file
  │   └─ examples/
  │       └─ good-review.md          ← reference file
  ├─ git-workflow/
  │   └─ SKILL.md
  └─ deploy-runbook/
      ├─ SKILL.md
      └─ rollback-procedure.md       ← reference file

• Each skill lives in its own directory: <skills-root>/<skill-name>/SKILL.md.
• The directory name is the default skill name (used when frontmatter name is absent).
• Additional files in the directory are skill resources, accessible via skill:// URLs.
• Skills are discovered one level under skills/ — nested subdirectories within a skill directory are not scanned for additional skills.

SKILL.md frontmatter:

---
name: code-review
description: "Systematic code review methodology — check for correctness, security, performance, and style."
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: false
---

Unknown frontmatter fields are preserved but not interpreted.

Body: Markdown. The skill content — instructions, methodology, checklists, decision trees, domain knowledge. Follows the same rules as system prompts (UTF-8, markdown, no code execution). The body is injected into the agent's context verbatim when the skill is activated. Frontmatter is stripped before injection.

2. DSL surface

Skills are declared per-agent via a new skills: block on AgentSpec:

primary:
  model: smart-generalist
  system_prompt: project:/prompts/primary.md
  cage: disabled
  skills:
    code-review:
      source: project:/skills/code-review/SKILL.md
      mode: on-demand
    git-workflow:
      source: config:/skills/git-workflow/SKILL.md
      mode: always
    deploy-runbook:
      source: project:/skills/deploy-runbook/SKILL.md
      mode: on-demand

  subagents:
    reviewer:
      model: low-cost-coder
      system_prompt: project:/prompts/reviewer.md
      cage:
        fs: [{ mode: ro, path: ./src }]
        net: { allow: [] }
        state: ephemeral
      skills:
        code-review:
          source: project:/skills/code-review/SKILL.md
          mode: always

• Keys are skill slot names — the name the agent sees in the catalog and the skill.use enum. Pattern: ^[a-z][a-z0-9-]{0,62}[a-z0-9]$.
• source (string, required) — URI-prefixed path to the SKILL.md file. Accepts project:/ and config:/ per ADR-0015. Same path rules as system_prompt (no .. escape, no naked paths). File existence checked at project-load time.
• mode (enum, default on-demand) — always or on-demand. Overrides the file's alwaysApply frontmatter.
• Max skills per agent: 16.
• Nullification: setting a key to null in project.local.yaml removes the skill (ADR-0015).

3. Activation modes

always — injected at session start

The skill body is concatenated into the agent's system prompt at session start. It is always present in the agent's context for the duration of the session.

• Use case: skills the agent should always apply — coding standards, project conventions, a domain knowledge base that informs every turn.
• Context cost: the skill's full body occupies context window budget on every turn. Multiple always skills compound. Subject to compaction (ADR-0024).
• Implementation: the harness concatenates always skill bodies after the agent's system_prompt content, separated by skill delimiters. The agent sees:

[system_prompt content]

<skill name="git-workflow">
[skill body]
</skill>

This is an extension of ADR-0037 (compound prompts) — skills are additional prompt segments with structural delimiters.

on-demand — injected when the agent activates the skill

The skill is NOT in the agent's context at session start. Instead, the agent sees a skill.use tool with the skill's name and description in a catalog. When the agent calls skill.use({ name: "code-review" }), the skill body is injected as a tool result. From that point forward, the skill content is in the agent's context.

• Use case: skills the agent applies selectively — deployment runbooks, specific review methodologies, troubleshooting procedures.
• Context cost: zero until activated, then the skill's full body is in context for the remainder of the session (or until compaction summarises it).
• Tool surface: on-demand skills are presented to the agent as a single skill.use tool with an enum-restricted name parameter:

{
  "name": "skill.use",
  "description": "Activate a skill — injects domain knowledge, methodology, or instructions into your context.",
  "parameters": {
    "type": "object",
    "required": ["name"],
    "properties": {
      "name": {
        "type": "string",
        "enum": ["code-review", "deploy-runbook"]
      }
    }
  }
}

The tool returns the skill body as text with a metadata footer:

[skill body — frontmatter stripped]

---
Skill: project:/skills/code-review/SKILL.md

4. Skill catalog

At session start, the harness resolves all skills for each agent. For on-demand skills (and non-hidden always-on skills), it builds a skill catalog — a concise listing injected as a system-level block at the start of the conversation:

## Available skills

The following skills are available. Activate a skill by calling skill.use with its name.

- **code-review**: Systematic code review methodology — check for correctness, security, performance, and style.
- **deploy-runbook**: Step-by-step deployment procedure for this project.

This catalog is lightweight (names + descriptions only) and does not consume significant context. It tells the agent what skills exist without loading their full bodies. Skills with hide: true are omitted from this catalog.

If the agent has no on-demand skills, the catalog is omitted entirely and no skill.use tool is registered.

5. skill:// URL scheme

Skills expose an internal URL scheme that lets agents access skill resources (reference files, examples, templates) from any file-reading tool:

• skill://<name> — resolves to the skill's SKILL.md file (with frontmatter stripped).
• skill://<name>/<relative-path> — resolves to a file within the skill's directory.

Resolution guards:

• Skill name must match exactly.
• Relative paths are URL-decoded.
• Absolute paths rejected.
• .. traversal rejected.
• Resolved path must remain within the skill's base directory.
• Missing files return an explicit error.

This lets an agent read reference material within a skill — for example, file.read("skill://code-review/examples/good-review.md") — using the same file tools it already has.

6. globs — context-aware skill suggestions

When a skill declares globs: ["**/*.ts", "**/*.tsx"], the harness tracks file operations. When the agent reads or writes a file matching a skill's globs, the skill is flagged as potentially relevant. The harness injects a lightweight hint:

[The file you're working with matches the code-review skill's globs. Consider activating it with skill.use if relevant.]

This is not auto-activation — the agent decides. The hint appears at most once per skill per session. Globs use standard glob syntax (same as search.glob).

7. Discovery and loading

Skills are loaded from the paths declared in the agent's skills: block. The loading process:

1. Read — the harness reads each SKILL.md file from the declared source path.
2. Parse — YAML frontmatter is extracted; body is separated.
3. Validate — name (or directory name fallback) must match the slot key. description must be present and ≤ 280 chars.
4. Deduplicate — if two sources resolve to the same file (via realpath), the duplicate is skipped silently.
5. Order — skills are ordered alphabetically by slot name for deterministic prompt construction.

Load failures (file missing, parse error, validation failure) emit a warning and skip the skill — the session continues with remaining skills.

8. Namespace and tool registry

• skill namespace is reserved per ADR-0033 amendment. Tools: skill.use (on-demand activation).
• If an agent has no on-demand skills, the skill.use tool is not registered. The tool only appears when at least one on-demand skill is declared.
• If an agent has only always-on skills, there is no skill.* tool at all — the skills are pure context injection.
• The skill.use tool is not root-only. Any agent with on-demand skills can activate them.

9. Relationship to existing concepts

Decision rule:

• If it's about who the agent is → system prompt.
• If it's about what the agent knows → skill.
• If it's about what the agent can do → tool.
• If it's about delegating work → subagent.

10. Federation and sharing

Skills follow the same federation model as prompts (ADR-0015):

• project:/skills/... — project-local skills. Travel with the project. The canonical home for project-specific methodologies.
• config:/skills/... — operator-level skills. Personal skill library, available from any project. The operator builds a library of reusable skills (code review, git workflow, debugging methodology) and references them from projects.

A project-local skill with the same slot name as a config-level skill (via project.local.yaml) overrides the config-level one. This is standard ADR-0015 merge semantics.

Consequences

What this commits us to

• skill namespace reserved. ADR-0033 is amended: skill joins the reserved namespace list.
• skills: block on AgentSpec. The DSL schema gains a per-agent skills: block. Each entry has source (URI path) and mode (always | on-demand).
• Skill file parsing. The harness gains a skill file loader: reads SKILL.md + YAML frontmatter, validates name and description, extracts body, resolves directory resources.
• skill.use tool. A new built-in tool for on-demand skill activation. Registered per-agent only when the agent has on-demand skills.
• skill:// URL scheme. File tools resolve skill:// URLs to skill directory contents. Path-traversal guards enforced.
• Skill catalog injection. For on-demand skills, a lightweight catalog is injected at session start.
• Skill content injection. For always-on skills, content is concatenated into the system prompt at session start. For on-demand skills, content is injected as a tool result when activated.
• Globs tracking. The harness tracks file operations against skill glob patterns and injects hints.
• Interaction with compaction (ADR-0024). Skill content in context is subject to compaction like any other content.

What this forecloses

• Skills cannot execute code. A skill is prompt content, not a program.
• Skills cannot call other skills. A skill is passive context. Composition is by the agent applying multiple skills' instructions.
• Skills cannot have their own tools or cages. A skill inherits the agent's tools, cage, and permissions.
• No nested skill discovery. Skills are discovered one level under the skills root. A directory within a skill directory is a resource, not another skill.

What becomes easier

• Reusable domain expertise. An operator writes a code-review methodology once and applies it to any agent in any project via config:/skills/code-review/SKILL.md.
• Context budget management. On-demand skills let agents load heavy reference material only when needed.
• Composable agent capabilities. An agent can have multiple skills without refactoring its system prompt or creating subagents.
• Project-portable expertise. Skills travel with the project — a project that includes a deployment runbook skill is self-documenting.
• Reference material access. Skills can carry their own reference files (examples, templates, diagrams) accessible via skill:// URLs.

What becomes harder

• Context budget reasoning. Operators must reason about how much context skills consume and whether to use always vs on-demand.
• Skill content quality. A poorly-written skill degrades agent performance. Skills are prompt engineering — the platform provides the delivery mechanism, not the quality guarantee.
• Skill conflict detection. Two skills that give contradictory instructions create ambiguity. The platform does not detect this.
• Prompt security. Skills are additional injected text. A malicious skill could inject adversarial instructions. This is the same threat model as system prompts — skills expand the existing surface.

Alternatives considered

Alternative A — Use compound prompts (ADR-0037) instead of a new skill concept

Why tempting: ADR-0037 already lets an agent have multiple prompt files concatenated into the system prompt. A "skill" is just another prompt file in the array.

Why rejected: Compound prompts are always-on and always consume context. There is no on-demand activation — the agent cannot choose to load a prompt segment when it needs it. A deployment runbook in a compound prompt occupies context on every turn. Skills add selective activation, reference file access (skill://), structured metadata for catalog generation, and glob-based relevance hints. These require a distinct concept, not a bare file path in a string[].

Alternative B — Skills as subagents with shared context

Why tempting: A subagent already has a prompt, tools, and a model.

Why rejected: Subagents are separate reasoning entities. They do not share the parent's context. A code-review skill applied as a subagent means the review happens in a separate context, without the full conversation history. Skills inject knowledge into the current agent's context.

Alternative C — Skills as tools that return their own content

Why tempting: Present each skill as a tool that returns the skill's markdown content.

Why rejected: This is functionally what on-demand skills are, but collapsing skills into tools loses the structural distinction: always-on capability (tools cannot be "always on"), system-prompt integration (tools return results, not system-level context), catalog/discovery surface, and reference file access. The skill namespace provides clean separation.

Alternative D — Defer skills entirely

Why tempting: System prompts + compound prompts + subagents already cover many use cases.

Why rejected: The gap is real. Operators today either bloat system prompts with domain knowledge or create heavyweight subagents for capabilities that are really just "inject this knowledge." The implementation cost is modest (a file loader, a DSL field, a tool, a URL scheme) compared to the capability gained.

Open questions

1. Skill inheritance. Should subagents inherit skills from their parent (like compaction)? Lean: purely per-agent — each agent declares its own skills.
2. Skill interdependencies. Should a skill declare "requires skill X"? Lean: no for v1. Skills are independent.
3. Skill marketplace. Beyond config:/ (operator-local library), should kaged support a skill registry? Lean: not in scope. Skills are markdown files — shareable via any file-sharing mechanism.
4. Dynamic skill loading. Can skills be added or removed mid-session? Lean: no for v1. Skills are resolved at session start. Mid-session changes require a session restart.

Phasing

Phase 1 (MVP)

• SKILL.md file format with frontmatter (name, description).
• skills: block on AgentSpec in the DSL.
• always mode (system-prompt concatenation).
• on-demand mode (skill.use tool).
• Skill catalog injection.
• skill:// URL scheme for reference file access.
• Federation via project:/ and config:/.

Phase 2

• globs frontmatter — context-aware skill suggestions.
• hide frontmatter — hidden skills.
• alwaysApply frontmatter — file-level default mode.
• Skill activation metrics via observability (ADR-0013).

Phase 3

• Skill versioning and compatibility checks.
• Mid-session skill hot-reload.
• Skill conflict detection (syntactic analysis of overlapping instructions).

Spec amendments required

Existing ADRs amended

• ADR-0033 — The reserved namespace list gains skill. The namespace directory gains a row: skill domain, "Declarative agent capabilities (prompt modules)", tool: skill.use.

References

• ADR-0022 — per-agent configuration model
• ADR-0024 — context compaction
• ADR-0037 — compound prompts
• ADR-0015 — federated config
• ADR-0033 — tool namespace convention
• ADR-0043 — MCP tools
• Original discussion: design conversation with colleagues, 2026-06-15

Amendments

Amendment: 2026-06-15 — Standard-format compatibility: glob-based discovery, on-demand-only, path hints replace skill://

Context. After acceptance but before implementation, design review against the standardised Agent Skills format (used across Cursor, Cline, Claude Code, and others) revealed that several ADR-0044 design choices created unnecessary divergence from the ecosystem standard without providing compensating value. The standard format is simple: a folder with a SKILL.md (frontmatter with name and description), optional supporting files (scripts/, references/, assets/), and progressive disclosure (discovery → activation → execution). The standard format does not define any URL scheme — it assumes agents access skill files via normal filesystem paths. This amendment aligns kaged's skill implementation with the standard.

Changes:

1. DSL surface: glob array replaces per-skill declarations

The skills: block on AgentSpec changes from a Record<string, SkillDecl> (with source and mode per skill) to a glob filter array:

primary:
  model: smart-generalist
  skills: ["*"]                        # default — all discovered skills
  # or:
  skills: ["code-review", "deploy-*"]  # only matching skills (glob patterns)

• Type: string[], optional. Omitted = ["*"] (all discovered skills).
• If any patterns are specified, the ["*"] default is dropped — only matching skills are included.
• Patterns match against folder names in the skills directory using standard glob syntax.
• No source field — discovery is directory-based, not per-skill explicit declaration.
• No mode field — all skills are on-demand (see change 3).
• The SkillDecl schema (source, mode) is dropped entirely.

2. Discovery: single directory, folder-name identity

Skills are discovered by scanning for */SKILL.md under a single directory within the project: .kaged/skills/.

.kaged/skills/
  ├─ code-review/
  │   ├─ SKILL.md
  │   ├─ checklist.md
  │   └─ scripts/
  │       └─ lint.sh
  ├─ deploy-runbook/
  │   ├─ SKILL.md
  │   └─ rollback.md
  └─ git-workflow/
      └─ SKILL.md

• Directory: .kaged/skills/<skill-name>/SKILL.md
• The folder name is the skill identity (used in the glob filter, the skill.use enum, and the activation result). No separate name declaration needed unless the frontmatter overrides it.
• Skills are always within project bounds. config:/skills/ resolves to .kaged/skills/ — there is no skill federation that escapes the project directory.
• Discovery happens at session start. Skills are resolved once and held for the session duration.

3. always mode dropped — on-demand only

The always activation mode (system-prompt concatenation at session start) is dropped. All skills are on-demand via the skill.use tool.

• The standard format's progressive disclosure model is purely on-demand. No standard-format skill expects to be auto-injected.
• Operators who need always-on context already have compound prompts (ADR-0037) — the system_prompt field accepts an array of paths. Always-on skills were redundant with this existing mechanism.
• alwaysApply frontmatter field is parsed but not interpreted.

4. skill:// URL scheme dropped — path hints + normal filesystem access

The skill:// internal URL scheme is dropped entirely. Instead, the skill.use activation result includes a path hint telling the agent where the skill's files are on disk:

<skill_content name="pdf-processing">
# PDF Processing

[SKILL.md body — frontmatter stripped]

Skill directory: .kaged/skills/pdf-processing
Relative paths in this skill are relative to the skill directory.

<skill_resources>
  <file>scripts/extract.py</file>
  <file>scripts/merge.py</file>
  <file>references/pdf-spec-summary.md</file>
</skill_resources>
</skill_content>

• The <skill_resources> block is auto-generated by listing the skill directory's contents at activation time.
• The agent accesses skill files using its existing tools with normal project-relative paths: shell.bash("python .kaged/skills/pdf-processing/scripts/extract.py"), file.read(".kaged/skills/pdf-processing/references/pdf-spec-summary.md").
• The cage controls access as it does for any other path. If the agent has shell access, it can run bundled scripts. If it doesn't, it can't. This is operator choice, not skill-level policy.
• No special-casing of file tools for skill paths. No URL resolution layer.

5. Catalog lives in the tool description, not the system prompt

The skill catalog (names + descriptions) is not injected as a separate block in the system prompt. Instead, it is embedded directly in the skill.use tool's description field:

{
  "name": "skill.use",
  "description": "Activate a skill — load domain knowledge, methodology, or instructions into your context.\n\nAvailable skills:\n\n- **code-review**: Systematic code review methodology...\n- **deploy-runbook**: Step-by-step deployment procedure...",
  "parameters": {
    "type": "object",
    "required": ["skill"],
    "properties": {
      "skill": {
        "type": "string",
        "enum": ["code-review", "deploy-runbook"]
      }
    }
  }
}

The LLM always sees tool definitions. The catalog travels with the tool. No additional system-prompt injection needed.

6. Frontmatter simplified

Only name and description from the frontmatter are interpreted, matching the standard format's required fields:

7. What remains unchanged

• skill namespace is reserved (ADR-0033). skill.use is the on-demand activation tool.
• skill.use is dynamically registered per-agent only when the agent has discovered skills.
• The activation result format (<skill_content> wrapper) follows the standard format's recommendation.
• Load failures (file missing, parse error, validation failure) emit a warning and skip the skill.
• Deduplication and alphabetical ordering by skill name.

Phasing updated

Phase 1 (MVP) — revised:

• SKILL.md file format with frontmatter (name, description).
• skills: glob array on AgentSpec in the DSL.
• Directory-based discovery (.kaged/skills/*/SKILL.md).
• On-demand activation via skill.use tool (catalog in tool description).
• Path hint + <skill_resources> in activation result.
• Standard-format compatibility — skills authored for Cursor/Cline/etc. work without modification.

Phase 2 — revised:

• globs frontmatter — context-aware skill suggestions.
• hide frontmatter — hidden skills excluded from catalog.
• Skill activation metrics via observability (ADR-0013).

Phase 3 — unchanged:

• Skill versioning and compatibility checks.
• Mid-session skill hot-reload.
• Skill conflict detection.

Removed from all phases:

• always mode (system-prompt concatenation) — use compound prompts (ADR-0037).
• skill:// URL scheme — use path hints + normal filesystem access.
• source/mode DSL fields — replaced by glob filter + directory discovery.
• Federation beyond project bounds — skills are project-local.

Future: UI for skill management. The UI should provide a file-management interface for adding, editing, and organising skills in .kaged/skills/. Skills are just files — the UI surface is straightforward file management, not a custom data model.

Spec amendments revised