COG-18: Agent Skills

Status:      Draft
Version:     0.1
Created:     2026-07-22
Authors:     Mike Anderson

Related specifications

A skill is an ordinary asset: its metadata follows COG-5: Asset Metadata and its body is content as defined by COG-6: Artifacts. The tools a skill contributes are operations (COG-7), invoked by agents (COG-11) under the capability rules of COG-13: Agent Capabilities. This document introduces no new asset type, no new authority primitive, and no new trust relationship — it specifies a discovery and loading convention over existing ones.

This standard specifies agent skills on the Covia Grid — named, discoverable bundles of instructions, context, and tools that an agent loads at run time.

Purpose

An agent's knowledge and abilities are otherwise fixed at configuration time: its system prompt, its pinned context entries, and its tool palette are all declared by its operator in advance. That produces three problems at scale:

• Context waste. Material needed for occasional work must either be pinned into every turn or omitted entirely. Pinning spends context budget on every turn for material used on one turn in fifty.
• Duplication. Agents sharing a domain restate the same procedures and tool lists in their configurations. Revising a procedure means editing every agent.
• No self-service. An agent that discovers mid-task that it needs an unfamiliar capability has no way to acquire one, even when the venue already holds a well-written description of exactly that capability.

Skills address these with progressive disclosure. A compact index — one line per skill, naming it and saying when to load it — is always in context. The full bundle loads only when the agent asks for it, and then persists for the remainder of the conversation.

The wider purpose is portability. Because a skill is an asset, a capability written once at one venue is content-addressed, verifiable, and loadable by any agent at any venue that can resolve it — the same federation properties artifacts already have, applied to agent competence.

Terminology

See COG-1: Architecture for Grid terminology and COG-5 for asset terminology.

Term	Definition
Skill	An asset referenced as a loadable bundle of instructions, context, and tools
Skill facet	The skill object in the asset's metadata, carrying the loadable extras
Body	The skill's instructions — the asset's content, resolved as for any artifact
Toolset	A skill with no content: a tool bundle plus its index line, and nothing to inject
Source	An address an agent searches for skills — a directory path or a single skill asset
Skill index	The rendered one-line-per-skill listing injected into the agent's context each turn
Load	The act of placing a skill's body, context, and tools into an agent's effective context
Loads tier	The agent's existing scoped store of loaded context entries, in which a loaded skill is one entry

Principles

• A skill is an asset. Not a new type. Skill metadata is ordinary asset metadata — name, description, content — with loadable extras under a skill facet, exactly as invocability sits under operation (COG-7). Nothing is a skill by virtue of its shape; an asset is treated as a skill because it is referenced as one.
• Progressive disclosure. The index is always present and compact; bodies and tools arrive only on demand. The cost of a skill an agent never loads is one line.
• No parallel machinery. Loading writes an ordinary entry into the agent's existing context loads tier. Persistence, budgets, inventory, eviction, and unloading are inherited unchanged.
• Live resolution. The index and every loaded body re-resolve from their sources each turn. Skills stay current; editing a skill changes the behaviour of agents already carrying it on their next turn.
• Loading grants no authority. A skill can offer an operation; it can never confer the right to invoke one. Every tool call remains capability-checked at invocation (COG-13).
• Fail-visible. Absent sources are skipped quietly. Broken ones are shown — an agent must never silently lose a capability it believes it holds.

Specification

Skill Metadata

A skill's metadata is asset metadata per COG-5:

{
  "name": "pdf-processing",
  "description": "Extract text and tables from PDF files",
  "content": {
    "contentType": "text/markdown",
    "sha256": "74f16013e2b7..."
  },
  "skill": {
    "tools": ["v/ops/file/read", "v/ops/schema/validate"],
    "context": [
      { "ref": "w/docs/pdf-rules", "label": "PDF handling rules" }
    ],
    "budget": 2000
  }
}

Field	Requirement	Role
name	RECOMMENDED	Standard asset field. Where a skill appears as a value in a directory, the key is canonical for identity and an inner name is ignored.
description	REQUIRED	The index line: what the skill does, and when to load it. It is a selection aid, never the documentation.
content	OPTIONAL	The standard content descriptor locating the body. Absent for a pure toolset.

The skill facet carries the loadable extras. All of its fields are OPTIONAL, and an empty facet is valid:

Facet field	Type	Description
tools	array of string	Operation refs added to the agent's tool palette while the skill is loaded. Same form as the agent's configured tools.
context	array	Context entries loaded alongside the body, in the agent's standard context entry grammar.
budget	integer	Default accounting budget when the skill is loaded. A loader MAY override it.

Implementations MUST reject a skill whose description is missing, and MUST report the rejection visibly (see Fail-visible behaviour). A non-string entry in skill.tools is an error at load time; a tool ref that merely fails to resolve MUST NOT fail the load — it MUST be reported to the agent so it can adapt.

The Body Is the Asset's Content

A skill's body is resolved by the venue's ordinary content resolution and decoded as UTF-8. Any content location valid for an artifact (COG-6) is valid for a skill body:

• a content-addressed blob referenced by content.sha256;
• inline content declared in the metadata itself, for small bodies — the bytes are then part of the metadata, so the asset's own identity hash (COG-5) covers them and no separate content hash is required;
• a filesystem or drive binding, pinned when a content.sha256 is also declared (hash-verified, drift fails loudly) or live when it is not.

There is deliberately no description-as-body fallback. The description is the index line; a skill with no content has no body and is a pure toolset — its skill.tools plus its index line. When a toolset is loaded, implementations SHOULD display its description in place of a body, as a rendering fallback rather than as instructions.

Markdown Skills

A skill whose content is a markdown document with YAML frontmatter — the widely used SKILL.md convention — MUST be accepted unchanged:

---
name: pdf-processing
description: Extract text and tables from PDF files
---

## PDF processing
...

Where the asset metadata does not supply name and description, they are read from the frontmatter and the body is the markdown following it. Only name and description are read; other frontmatter keys are ignored. Asset metadata always wins — frontmatter is a compatibility fallback, not an alternative source of truth.

This compatibility is deliberate: an ecosystem of hand-written skills already exists, and requiring authors to re-encode them would be a barrier with no technical benefit.

Facet Composition

Facets compose. An asset MAY carry both an operation facet and a skill facet:

{
  "name": "report-bug",
  "description": "File a well-formed bug report in the tracker",
  "content": { "contentType": "text/markdown", "sha256": "..." },
  "operation": { "adapter": "mcp:tools:call", "remoteToolName": "create_issue" },
  "skill": {}
}

When such an asset is loaded as a skill, the asset itself MUST join the tool palette, in addition to any skill.tools. The result is a self-documenting tool: the body explains, the operation executes, and both are one asset with one identity. The converse also holds — skill.tools may reference any operation in the catalogue, including bridged ones.

Sources and Addressing

An agent declares an ordered list of sources. Each is resolved positionally, not by shape:

Source form	Interpretation
A path (w/skills, v/skills, a DID-URL path)	A directory: a map whose keys are skill names and whose values are either skill metadata maps or string references followed one hop to the skill asset
An asset ref (a/<hash>)	A single skill

Skills may therefore live anywhere the Grid addresses:

Location	Example	Use
Asset store	a/<hash>	The canonical form — immutable, content-addressed, shareable across venues
Venue catalogue	v/skills/<name>	Venue-installed skills, published read-only to every caller
User workspace	w/skills/<name>	Personal skills and quick iteration

Resolution rules:

• A source that resolves to null MUST be skipped quietly. Sources are allowed to be created later.
• A source whose resolution throws MUST render one visible line in the index rather than being skipped.
• A directory value that is neither a metadata map nor a string reference MUST render a visible invalid line for that key.
• On name collision, the first source in declared order wins. This makes shadowing well-defined: a user's own w/skills/grid takes precedence over the venue's v/skills/grid.

A malformed source list — not a list, or containing a non-string entry — is a configuration error and MUST fail loudly at agent transition time rather than being masked.

The Skill Index

When an agent declares at least one source, its context MUST include, each turn, a compact index of the skills those sources offer:

[Skills]
Named skill packs you can load with skill_load({name: "..."}). Loading injects the
skill's instructions into your context (persists across turns; unload with
context_unload) and adds its tools to your palette.
- pdf-processing — Extract text and tables from PDF files
- code-review — Review code against the house style (loaded)
- broken-skill — INVALID: missing description
[skills source w/other-skills — unavailable: timeout]

• One line per skill: - <name> — <description>.
• A (loaded) marker where the skill is already in effective context.
• Resolved fresh each turn. Nothing is cached across turns.

The index is a selection surface, not documentation. Its per-skill cost bounds how many skills an agent can usefully be offered, which is why the description field is normatively a single line about what and when.

Loading

Loading is performed by a harness tool, conventionally skill_load, which takes either a name (looked up across the agent's declared sources) or a ref (a direct address, including one the agent was told about at run time and that no source lists), and an optional budget.

Loading MUST:

1. Resolve the skill, returning a diagnosable error naming the skill and the reason if it cannot.
2. Write a skill-flagged entry into the agent's innermost loads tier.
3. Resolve the skill's tools — skill.tools, plus the asset itself where it carries an operation facet — into the agent's palette, effective within the same transition.
4. Load the skill's skill.context entries alongside the body.
5. Return the body in the tool result, so the instructions are usable in the turn that requested them rather than the turn after.

The loads entry records the skill's canonical path, its budget, and its resolved tool refs. The body is not denormalised into the entry: it re-resolves each turn, so skills stay live. Tool refs are denormalised, so a change to a skill's tool list takes effect on reload while body and context changes take effect on the next turn.

Skills deduplicate by content identity, not by address. A skill's identity is the value hash of its resolved metadata (COG-5), which also covers its content binding. Loading the same skill from a second address — an asset hash and a directory entry pointing at it, or two mirrored directories — MUST be a no-op naming the existing entry, and the (loaded) marker MUST match by identity so that a skill loaded by hash still marks its directory line.

Unloading uses the agent's existing context-unload facility on the skill's path; removing the entry removes the body, the skill's context entries, and its tools from the next turn onward. Implementations SHOULD NOT introduce a separate unload verb for skills.

Discovery

Venues SHOULD expose a read-only discovery operation over skills, offering at minimum:

Command	Input	Output
list	Optional sources	The rendered index text, or null where no skills exist
read	A name or a ref	The skill in full: name, description, body where present, tools, context, and canonical path

Discovery MUST render through the same code path as the injected index, so that what a caller inspects and what an agent sees cannot drift.

The operation is available to agents, human callers, and external clients alike, which makes a venue's skill library publicly enumerable in the same way its operation catalogue is. It also lets an operator inject a skill index into an agent as ordinary context without activating loading — useful where an agent should know what exists but not be able to acquire it.

There is deliberately no skill-write surface. Skills are authored with the ordinary write and asset-store operations; a skill is data, and creating one requires exactly the authority creating any other asset requires.

Fail-visible Behaviour

Skills change what an agent believes it can do, so failures MUST be visible rather than silent:

Condition	Required behaviour
Source resolves to null	Skipped quietly (absence is normal)
Source resolution errors	One visible index line naming the source and the reason
Skill missing a description	Visible invalid index line; load refused with a diagnosable error
Loaded skill no longer resolves	Visible unavailable element in place of the body
Loaded skill no longer fits its budget	Visible notice, not a silent omission
A skill.tools ref does not resolve	Reported in the load result; the load still succeeds

Capability Model

Reading a skill is a read: implementations MUST pin the ordinary read capability for the source actually consulted — namespace read for workspace, venue, and DID paths, and asset read for content-addressed refs (COG-13).

Loading a skill confers no authority whatsoever. A skill may name operations the loading agent has no capability to invoke; those calls MUST fail at invocation exactly as they would have failed before the skill was loaded. Capability and competence are separate axes: a skill tells an agent how, never whether it may.

Federation

Because a skill is an asset, it crosses venues by the mechanisms artifacts already use (COG-6, COG-15): the ref is content-addressed, the metadata's identity hash covers the content binding, and a receiving venue verifies rather than trusts. A skill authored at one venue and loaded at another is byte-identical or it is a different skill.

Two consequences follow, and both are properties of the asset model rather than of skills:

• A skill ref may be handed between agents — including across venue boundaries — and loaded directly, without the recipient's operator having listed its source.
• The operations a skill names are resolved at the loading venue. A skill is portable; the tools it names are only as portable as the catalogue behind them, which is why unresolved tool refs are reported rather than fatal.

Security Considerations

Skill Content Is Prompt Content

A loaded skill's body enters the agent's context verbatim and its tools join the palette. A skill author is therefore trusted by the loading agent's operator to the same degree as the author of the agent's pinned context or system prompt. Operators MUST treat a skill source as a trust boundary and point agents only at sources they trust.

This is the identical trust rule that already applies to configured context, and it is not weakened by skills — but the run-time, agent-initiated nature of loading makes it easier to overlook. Implementations SHOULD make the provenance of a loaded skill inspectable, and content-addressed skill refs SHOULD be preferred where provenance matters, since a hash pins exactly what will be injected.

Loading Is Not Authorisation

The most likely misreading of this specification is that loading a skill grants the ability to use its tools. It does not. Every invocation is checked against the agent's capabilities at the moment of the call (COG-13), and an agent that loads a privileged skill without holding the corresponding capabilities gains instructions it cannot act on. Implementations MUST NOT treat presence in a loaded skill's tool list as evidence of authority.

Resource Exhaustion

Each loaded skill consumes context budget every turn. Implementations MUST bound the per-skill budget, MUST account loaded skills within the agent's overall context budget, and SHOULD evict under pressure by a defined order rather than failing the turn. Directory sources are read per turn to build the index, which bounds practical directory size; venues expecting large libraries should expose a listing that does not require reading every value.

Live Resolution Is a Live Surface

Because bodies re-resolve each turn, editing a skill silently changes the behaviour of every agent currently carrying it. This is the intended contract — it is what makes skills maintainable — but it means write access to a skill source is effectively write access to the prompts of the agents using it. Where that is unacceptable, use pinned, content-addressed skills: a hash cannot be edited underneath a loaded agent.

Related Specifications

• COG-5: Asset Metadata — the metadata a skill is
• COG-6: Artifacts — content resolution and verification for skill bodies
• COG-7: Operations — the tools a skill contributes, and the facet model it mirrors
• COG-11: Agent Lifecycle — the agents that load skills
• COG-13: Agent Capabilities — the authority check that loading never bypasses
• COG-15: Cross-Venue Federation — how skills, as assets, cross venue boundaries