# 0022 · A skill is a page in the wiki's skills folder, and agents are told which they can read

**Status:** Accepted · 2026-10-24.

## Context

An agent connected to CoDNA reads a page when it thinks to. Teams also want to tell it how to do
things their way: how to write a proposal for a customer, how to answer a question about refunds,
what a weekly report must contain. That is what [Agent Skills](https://agentskills.io/) are for. A
skill is a `SKILL.md` with a name, a description and a body. The model is shown every skill's name
and description up front, and reads the body only when a task matches.

There are three ways to get skills to an agent, and on 2026-10-24 none of them suits CoDNA:

- **MCP's skills extension** ([SEP-2640](https://modelcontextprotocol.io/seps/2640-skills-extension),
  final since 2026-09-13) has a server publish skills as `skill://` resources, with `skills/list`
  and `skills/get`. No client we serve loads them yet. Claude's connector documentation says it
  does not support draft or advanced capabilities. ChatGPT copies a server's skills once, when a
  plugin is submitted to it. The Go SDK does not implement the extension.
- **A Claude plugin** carries skills alongside a connector. It works only in Claude, its skills are
  fixed in git, and each instance would need a plugin of its own.
- **Uploading a skill** into claude.ai is per person, by hand.

Every client does two things, though: it reads the instructions a server sends when it connects,
and it calls tools. The extension itself allows a server to point to its skills from its
instructions.

## Decision

**A skill is a page directly in the wiki's `skills` folder.** `wiki:skills/write-a-proposal` is
the skill `write-a-proposal`.

- Its slug is its name, and its title is what people see it as.
- Its description says when to use it. That is the `description` (or `summary`) in its
  frontmatter, as a `SKILL.md` has, or else its first paragraph. A list row's excerpt is chosen by
  the same rule, but a skill's description is cut longer, at 300 characters.
- Its body is the skill: the steps, the defaults, what good looks like. Material it relies on, such
  as a template, a policy or examples, is other pages it links to, wherever they are. Pages in
  folders beneath `skills` are not skills, so a skill's own supporting pages can sit beside it.
- Only an active page is a skill. A draft is a skill still being written, and an archived page is
  one that has been retired.

**On connect, each caller is told which skills it can read.** The instructions sent with
`initialize` end with a list of skills, in title order, 50 at most. One line names them all, and
then each gets its address, title and description. When there are more than 50, the list ends by
saying how to see the rest. The model is told to read a skill with `get_document` before it starts
a task the skill fits, and to follow its links.

- **A client may keep only the start of the instructions.** Claude Code keeps the first 2048
  characters of a server's instructions and drops the rest (checked 2026-10-24). The instructions
  CoDNA had sent until then ran to about 2450 characters, so their last bullet never reached the
  model there. They are now cut to about 1300 characters, and the details are left to each tool's
  own description. That leaves room for the line naming the skills, about fifteen of them, within
  what Claude Code keeps. The descriptions come after that line and are kept only by a client that
  takes more. A test holds the instructions to that length.

- Who is told about a skill is ordinary visibility. A skill nobody has shared is its writer's own.
  Shared with a team, it reaches the agents of everyone in the team. An agent
  ([0021](https://codna.me/docs/adr/0021-agents-are-members.md)) is told about the skills its responsible people shared
  with it.
- The list is made when the client connects. A skill added later shows up on the next connection.
  A skill that was changed is read as it is now, because `get_document` reads it when it is used.
- There is no new tool and no protocol extension. A client that ignores instructions can still find
  skills with `list_documents` and `search`, since they are pages.
- If the list cannot be made, the client connects without it, and the failure is logged. A skill
  helps; nothing depends on it.

**A skill steers agents, so editing one is a responsibility.** Whoever can edit a shared skill is
writing instructions for the agents of everyone who can read it. Skills are shared read-only with
the people they serve, and write is kept for the few who maintain them. A folder share on
`wiki:skills` ([0014](https://codna.me/docs/adr/0014-standing-folder-shares.md)) is the usual way to arrange that. The model
is told that a skill is guidance written by people in the organisation. It does not override the
person the agent acts for.

**When clients load skills from a server, the same pages are served that way too:** `skill://`
resources, `skills/list` and `skills/get`, and the pages stay as they are. That is not built yet.

## Consequences

- A skill is written, versioned, shared and reverted like any other page, in the editor people
  already use. It is current as soon as it is saved, and each instance has its own.
- It works in every client that reads server instructions, and needs no plugin, upload or admin.
- The client does not know these are skills. There is no skills screen and no per-skill switch,
  and a skill is used only if the model acts on the list. A plugin's skills are triggered by the
  client itself.
- Each connection costs one more listing query.
- The instructions grow with the list. Fifty skills at 300 characters each comes to about 20 KB at
  most. Past fifty, the list stops and points to `list_documents`. A team with that many skills
  should merge some of them.
- In Claude Code the model sees the skills' names and not their descriptions, so a name has to say
  what the skill is for: `write-a-proposal`, not `sales-2`. Past about fifteen skills, even the
  later names are cut.
- `skills` in the wiki is now a name with a meaning. A folder of that name about something else,
  such as people's skills, would be listed to agents. None of the hosted instances has such a folder
  (checked 2026-10-24).

## Alternatives rejected

**A `skill` tag on any page.** Anyone who can edit a page could make it a skill for everyone who
reads it, and there would be no one place to see the skills or control who changes them. A folder
gives both, and a folder share sets who maintains them.

**The MCP skills extension now.** It is right and it is where this goes, but no client we serve
reads it yet, and the SDK does not implement it.

**A Claude plugin per customer.** It works only in Claude, is fixed in git, needs a release for
every edit, and needs an Owner on a Team or Enterprise plan to install it. It is still worth
offering alongside this, to a customer who wants Claude's own skill handling.

**`list_skills` and `get_skill` tools.** They would do what `list_documents` and `get_document`
already do, and a model calls a tool only when it already thinks of it. The instructions are read
on every connection.

**Every page anywhere under `skills` as a skill.** The list would grow with every supporting page,
and a skill would have nowhere to keep its own material.