# Skills

A skill tells an agent how your team does a task: how to write a proposal for a customer, how to
answer a question about refunds, what goes in a weekly report. In CoDNA a skill is an ordinary page
in the wiki's `skills` folder. An agent that can read the page is told about it when it connects,
and reads it when a task fits.

This works in Claude, ChatGPT, Claude Code and any other client that reads what an MCP server tells
it on connect. It works for your own [agents](https://codna.me/docs/agents.md) too. The decision is
[adr/0022](https://codna.me/docs/adr/0022-skills-are-wiki-pages.md).

## Writing one

Create a page directly in `wiki/skills`, for example `wiki:skills/write-a-proposal`:

```markdown
# Write a proposal

Use when someone asks for a proposal to a customer, or to turn meeting notes into one.

1. Read the customer's page in wiki/customers and their latest meeting notes.
2. Start from the [proposal template](write-a-proposal/template.md), and keep its sections.
3. Price from the [price list](../sales/prices.md). Never offer a discount above 10%.
4. Save the draft in output and give the person its address.
```

- **The first paragraph says when to use the skill.** The agent decides by it, so write it about
  the task: "Use when …". It is cut at 300 characters. If the page's frontmatter has a
  `description`, as a `SKILL.md` does, the description is used instead.
- **The rest of the page says how:** the steps, the defaults, what good looks like and what to
  avoid.
- **Link to the material it relies on,** such as a template, a policy or past examples. Pages in
  folders beneath `skills`, such as `wiki:skills/write-a-proposal/template`, are not skills, so a
  skill's own material can sit beside it.
- **A draft is not listed,** so you can mark a skill as a draft while you write it. An archived
  page is not listed either.

## Who is told about it

A skill reaches whoever can read its page, as any page does.

- **Until you share it, only you.** Your own agent is told about the skill, so you can try it
  first.
- **Share it with a group or with Everyone** to reach their agents, or with an agent to reach that
  agent.
- **Share it to read.** Anyone who can edit a shared skill is writing instructions for the agents
  of everyone who reads it, so give write to the people who maintain it, and no one else. A
  [folder share](https://codna.me/docs/permissions.md#folder-shares) on `wiki/skills` is the usual way to arrange that.

## How an agent uses it

When an agent connects, the instructions CoDNA sends it end with the skills it can read, 50 at
most. One line names them all, and then each gets its address, title and first paragraph. When a
task fits one, the agent reads it with `get_document` and follows it, along with the pages it
links to.

- **Give a skill a name that says what it is for,** such as `write-a-proposal`, because its name
  is its address. Claude Code keeps only the start of what a server tells it, and that covers the
  line of names but not the descriptions after it. In Claude Code the agent chooses by name.

- **The list is made when the agent connects.** A new skill shows up in the next conversation. A
  skill you edit is read as it is now.
- **A skill is guidance, not an order.** The agent is told that a skill was written by people in
  your organisation, and does not override the person it is working with.
- **The client does not know these are skills.** Claude and ChatGPT show no menu for them, and
  whether a skill is used depends on the model. If an agent misses one, ask for it by name: "use
  the write-a-proposal skill".