Building skills

A skill is a reusable task: a name, a description, and instructions that turn the kind of work your team does over and over (drafting a grant section, summarizing a meeting, extracting fields from a contract) into something anyone on the team can reach for, without rewriting the prompt every time. This page is for the people who build skills: typically an admin working with a domain expert from the team that will use them.

Skills live on the Agents screen

Skills don't have a separate screen of their own. You build, find, and edit them from the Agents screen, in the same list as your agents. Each row has a Kind column showing whether it's an "Agent" or a "Skill": a skill row has no chat action (you can't talk to a skill directly), and shows no model of its own, since a skill only ever runs inside an agent that references it.

To build one, open New on the Agents screen and set its Kind to Skill instead of Standalone. It's the same form either way; the Kind you pick determines whether what you're creating is a persona you chat with or a task another agent can reach for.

What a skill actually is

A skill is defined with:

• A name and description. What the skill is for, in plain language. The description is a single line, it's what tells someone (or the agent choosing between skills) when to reach for this one.
• Instructions. The prompt the skill runs. There's no separate structured field for inputs or expected output, so state them directly in the instructions: what the task is, what it needs to know, and what a good result looks like.
• Optional knowledge bases. The same knowledge bases you'd attach to an agent, scoped to what this task needs.
• Optional tools. Any custom tools the skill can call directly, independent of whatever tools its parent agent has.

A skill has no model of its own and can't hold a conversation by itself. An agent is a persona with a model, knowledge, and skills attached; a skill is one task that persona can reach for.

Who builds them

Skill building is a collaboration between two roles.

• The admin or builder. Writes the instructions, attaches the knowledge bases and tools, and sets it up on the Agents screen.
• The domain expert. The person from the user team who does the work today. They define what good output looks like, supply sample inputs, and judge whether the skill is worth shipping.

A skill written without a domain expert tends to produce output that looks fine but misses what the team needs. A skill written without an admin tends to never ship.

The lifecycle

Building a skill is iterative.

1. Define the task. Pick something concrete and recurring. "Summarize the weekly status email into three bullets" is a good first skill. "Be a great research assistant" is not.
2. Collect sample inputs. Get five to ten realistic examples from the domain expert. These become your test set.
3. Write the instructions. Start simple. State the task, what it needs to know, the constraints, and the expected output. Run the skill against your samples.
4. Attach knowledge bases and tools. If the instructions alone can't get there, add what the task needs.
5. Iterate. Read the outputs with the domain expert. Adjust the instructions. Tighten the constraints. Re-run.
6. Ship. Once the skill produces useful output across your sample set, name it clearly and grant it to the relevant agents.

Most skills take two or three rounds of iteration to get right. Don't ship the first draft.

Naming, and changing a skill later

A skill name should describe what the user gets, not how it works. Prefer Draft grant cover letter over Cover letter generator v2.

Stoa doesn't keep prior versions of a skill to compare against or roll back to, so treat a meaningful change to a widely used skill's instructions or tools with the same care you'd give editing code in production. For a small wording fix, edit it in place. For a substantial change in behavior, consider building the new version alongside the old one under a different name, checking it against your sample set, and only then retiring the original, so you're never mid-edit on something people are actively relying on.

Inputs and outputs

Think about a skill's inputs and outputs as part of the instructions you write, since there's no separate structured field for either.

• What does the skill need to be told explicitly? Say it plainly in the instructions: what the task is, and what's required to do it well.
• What can be inferred? If the agent's knowledge base, the user's role, or today's date can be inferred, don't demand it in the instructions too.
• What does the output look like? State it explicitly. "Produce a markdown document with the sections X, Y, Z" beats "produce a useful report."

Skill or agent?

• If it's a task somebody does repeatedly with mostly the same shape, build a skill.
• If it's a persona that owns several related tasks and a body of knowledge, build an agent and attach skills to it.

A "Grant writing" agent might attach skills like Draft cover letter, Outline narrative, Generate budget justification, and Summarize program theory of change. The agent provides context and knowledge bases. The skills do the tasks.

Evaluating a skill

Before declaring a skill ready, run it against your samples and ask the domain expert two questions.

1. Is the output consistent across the samples? A skill that works one in five times isn't ready.
2. Is the output useful? Useful means the domain expert would actually use it as a starting draft instead of redoing the work from scratch.

If either answer is no, iterate. If both are yes, ship.

Next

• Skills (user view) for how end users actually run skills in the chat.
• Custom tools for the tools you'll attach to skills.
• Agents for how skills are grouped into personas users can pick.