Skills System

Skills are how this harness teaches an agent what it knows, what it can do, and when to do it. They're plain Markdown files — humans write them, agents read them, the harness loads them in three tiers to keep the token budget under control. This is the most Claude-Code-inspired part of the codebase.

The mental model

Think of a skill as a "job description" the agent receives at runtime. The job description says: here's your role, here are the tools you can use, here's how to think about typical tasks, and here are the deeper references if you need them. The harness can have dozens of skill files on disk. A single-skill agent has one skill "in role" at any given turn; a multi-skill agent merges instructions and tools from several skills simultaneously.

The three tiers — progressive disclosure

An LLM has a finite context window. If you eagerly load every detail of every skill at startup, you blow the budget before the first user message lands. The harness solves this the same way Claude Code does: skills are loaded in three tiers, only as deeply as needed.

Anatomy of a SKILL.md file

Skills live under skills/ at the repo root (configured via AppConfig.AI.Skills.BasePath). Each skill is a single Markdown file with two parts: a block of structured metadata at the top, and human-readable instructions below.

Here's what a real SKILL.md looks like:

---
id: research
name: Research Agent
description: Finds and synthesizes information from documents and the web.
category: information-gathering
tags: [research, search, summarize]
allowed-tools:
  - file_system
  - document_search
version: 1.0.0
model-override: gpt-4o    # optional override of AppConfig default
skill_type: research
---

# Research Agent

## Role
You are a thorough research assistant. When given a question, you:
1. Identify what is and isn't known.
2. Use the document_search tool to gather sources.
3. Synthesize findings with citations.

## Behavioral guidelines
- Always cite sources by URL or document ID.
- Prefer primary sources over summaries.
- If sources conflict, surface the conflict rather than picking one.
...

The frontmatter is the Tier-1 metadata: id, name, description, category, tags are the index card; allowed-tools declares the tool surface. The parser (SkillMetadataParser) reads a fixed set of keys — category, tags, version, model-override, agent-id, allowed-tools, prerequisites, completion_tool, skill_type — anything else lands in a generic Metadata bag. The Markdown body is the Tier-2 content — the agent's instructions for this role. Tier-3 resources aren't listed in frontmatter at all: they're discovered from the skill folder's references/, templates/, and scripts/ subdirectories.

The SkillDefinition domain type

When the loader parses a SKILL.md, it produces a SkillDefinition:

public class SkillDefinition
{
    // Level 1 — Index Card (always loaded)
    public string Id { get; set; } = string.Empty;
    public string Name { get; set; } = string.Empty;
    public string Description { get; set; } = string.Empty;

    // Level 2 — Folder (on demand)
    public string? Instructions { get; set; } = string.Empty;   // Markdown body

    // Categorization + runtime config
    public string? Version { get; set; }
    public string? Category { get; set; }
    public string? SkillType { get; set; }                      // from skill_type
    public IList<string> Tags { get; set; } = new List<string>();
    public IList<string>? AllowedTools { get; set; }
    public string? ModelOverride { get; set; }                  // from model-override
    public string? AgentId { get; set; }                        // from agent-id
    public string? PluginSource { get; set; }                   // plugin ID, if Injected

    // Prerequisite ordering
    public IList<string> Prerequisites { get; set; } = new List<string>();
    public string? CompletionTool { get; set; }                 // from completion_tool

    // Level 3 — Filing Cabinet (discovered from subfolders)
    public IList<SkillResource> Templates  { get; set; } = new List<SkillResource>();
    public IList<SkillResource> References { get; set; } = new List<SkillResource>();
    public IList<SkillResource> Scripts    { get; set; } = new List<SkillResource>();

    // Computed — NOT settable
    public bool IsPluginSkill => !string.IsNullOrEmpty(PluginSource);
    public SkillMode Mode => IsPluginSkill && !HasToolDeclarations && !HasToolRestrictions
        ? SkillMode.Injected : SkillMode.Managed;
    // ... Author, License, StateConfiguration, DecisionFramework, etc.
}

Notice this is a plain mutable class — get; set; properties and IList<> collections, rather than the immutable records used almost everywhere else in this codebase. That is deliberate: the parser fills it in field by field as it reads down the SKILL.md, so it needs somewhere to accumulate.

The one thing you can't set is Mode: it's a computed property derived from IsPluginSkill plus whether the skill declares any tools. The PluginSource and Prerequisites properties are covered in the sections below.

The richer tools: block

allowed-tools: is a bare name list — enough when a skill just needs a tool available. A skill that needs to say more about how it uses a tool — required operations, a fallback if the tool is unavailable, or that a tool must be called at most once per conversation — declares a structured tools: block instead. Each entry parses into a Domain.AI.Tools.ToolDeclaration:

---
id: diagnostics
name: Diagnostic Agent
tools:
  - name: start_diagnostic_session
    operations: [open, close]
    optional: false
    call-once-per-conversation: true    # refused durably on a second call — see below
    description: Opens the stateful session a diagnostic conversation runs inside.
  - name: github_repos
    optional: true
    fallback: file_system
    description: Looks up related issues when available.
---

• name — the tool name (keyed-DI key, or an MCP server name in Managed mode). An entry with no name is dropped, not loaded nameless.
• operations — the specific operations this skill uses; empty means all are allowed.
• optional — whether the skill can function without this tool. Absent means required: ToolChainBuilder throws at resolution rather than silently proceeding without a tool the skill depends on.
• fallback — another tool name to substitute, or the literal manual for "a human does it instead."
• call-once-per-conversation — when true, the admission chain's ICallOnceGate refuses a second call to this tool within the same conversation, durably — surviving across turns, across separate runs continuing the same conversation, and across hosts. Absent (or false) is the default: an ordinary, repeatable tool. Enforcement itself is a separate host opt-in — see Autonomy & Governance — so a skill can declare a tool call-once well before a host chooses to enforce it.

How a skill becomes an agent

The runtime journey of a skill, end-to-end:

1. Discovery at startup

   SkillMetadataParser parses each SKILL.md frontmatter into a SkillDefinition, and SkillMetadataRegistry (behind ISkillMetadataRegistry) holds them, keyed by id. Only the Tier-1 metadata is eagerly in memory — the Markdown body is held lazily.

2. Selection and assembly per turn

   When ExecuteAgentTurnCommandHandler runs, it looks up the agent's skill references. For a single-skill agent, one skill is selected. For a multi-skill agent, AgentExecutionContextFactory merges instructions and combines tool lists from all referenced skills into one unified AgentExecutionContext. If any skill has prerequisites, the factory enforces ordering — prerequisite skills must be marked complete (via their CompletionTool) before dependent skills activate.

3. Tier-2 promotion

   The selected skill's full instructions (Markdown body) are loaded and stitched into the system prompt. Now the agent knows how to play this role.

4. Tool resolution

   For each entry in allowed-tools, the harness resolves a keyed singleton from DI — sp.GetRequiredKeyedService<ITool>("file_system") — then converts it to an AITool and attaches it to the agent. See Tools & Keyed DI.

5. Tier-3 access at runtime

   A resource under the skill folder's references/ subdirectory isn't read until the agent's file_system tool actually opens it. The path is exposed via the tool, not preloaded into the prompt.

Skill modes — Managed vs Injected

Not all skills originate inside the harness. The SkillMode enum distinguishes two patterns:

Injected skills always set PluginSource to the owning plugin's ID. The harness still applies plugin-boundary governance (AllowedTools / DeniedTools) even when tools are passed through — see Observability & Safety.

Prerequisites and completion tracking

In a multi-skill agent, some skills depend on the output of others. A "data gathering" skill should finish before an "analysis" skill starts. The harness supports this with two properties:

• Prerequisites — a list of skill IDs that must complete before this skill activates.
• CompletionTool — the tool name whose invocation marks this skill as complete. When the agent calls this tool, the harness records the skill as done, unlocking any dependents.

---
id: analysis
name: Analysis Agent
prerequisites: [data-gathering]    # must complete first
completion_tool: submit_report     # calling this marks analysis as done
allowed-tools:
  - submit_report
  - file_system
---

Multi-skill agents

An agent's AGENT.md can reference multiple skills in its skills: list. At context assembly time, AgentExecutionContextFactory merges instructions from all referenced skills and combines their tool lists into a single AgentExecutionContext.

---
skills:
  - data-gathering      # prerequisite — runs first
  - analysis            # depends on data-gathering
  - code-reviewer       # independent — can run anytime
---

The factory handles each skill according to its SkillMode: Managed skills get explicit tool resolution; Injected skills get pass-through MCP tools. Prerequisites are enforced across the merged set. The result is one agent with the combined capabilities of all its skills.

The context budget tracker

While all of the above is happening, IContextBudgetTracker is keeping score. For the current turn, it tracks how many tokens have been committed to each of four things:

• the system prompt
• the skill content that has been loaded
• the tool schemas
• the conversation history

Those four compete for the same finite budget. As it starts to run out, the assembler stops promoting full Tier-2 skill content and serves only the short Tier-1 descriptions instead — the agent still knows the skill exists, it just no longer carries the full text.

Adding a new skill

The end-to-end recipe — covered in more detail on Extending the Harness:

1. Create a folder under skills/<your-skill-id>/.
2. Add a SKILL.md with frontmatter (id, name, description, allowed-tools) and a Markdown body with the instructions.
3. Add any Tier-3 references under references/, templates/, or scripts/ in that folder.
4. Make sure every tool in allowed-tools is registered in DI under that key.
5. (Optionally) reference the skill from an AGENT.md so an orchestrator can route to it.

You don't need to redeploy or recompile. No restart needed — the harness watches skill paths for changes by default (AI:Skills:WatchForChanges) and picks up an added, edited, or removed SKILL.md automatically within ChangeDebounceMilliseconds (500ms default). If WatchForChanges is disabled, restart the host or call the operator refresh endpoint (POST /api/skill-registry/refresh) to confirm immediately.

Skill amendments and learnings

Skills aren't static. A SkillAmendment is a short, plain-language note attached to one skill — what was learned, and what triggered it. Unlike a SKILL.md change, an amendment doesn't need a host restart: AgentExecutionContextFactory loads a skill's amendments from the knowledge graph, entirely independent of the file-based skill loader, whenever that skill's agent is (re)built — immediately for any brand-new conversation, and for an already-open one once its cached agent is rebuilt, the same cadence the rest of that agent's static instructions already follow. It is not re-checked on every turn of an ongoing conversation.

The harness also tracks, automatically, whether each skill succeeds — broken down by what kind of request it was handling — so the data needed to decide "this skill needs an amendment" is being collected on every turn. Turning that track record into a written amendment is currently a manual step: nothing in the harness yet decides on its own when a pattern is strong enough to act on.

Where to go from here