Skip to content
Context docs

Build and improve skills

A good skill starts from work that already went well, does one job, and gets better each time someone uses it. This guide covers when to write a skill, how to scope and test it, and how to improve it after it ships.

Know when to write a skill

Turn work into a skill when you see one of these signals:

  • You paste the same instructions into task after task. For example, the same rules for a weekly report, every week.
  • You correct the same mistake twice. If the agent keeps using the wrong chart style, write the right one down once.
  • Several people do the same job differently. A shared skill gives the team one way to do it.
  • A good result depended on knowledge only you have, such as which numbers the board cares about or which customers to leave out.

Don’t write a skill for a job you have done once. Do it in a task first and fix the result. The skill then records what worked, not what you guessed would work. See Choose between tasks, skills, automations, agents and applets for how a job grows from a task into a skill and beyond.

Scope it to one job

A skill should describe one kind of job from start to finish. “Write the monthly board deck” is one skill. “Board decks, sales data cleaning and customer emails” is three.

Scope matters for two reasons:

  • The agent decides from the name and description. Agents see only those two fields until they open a skill. A skill that covers too much has a description too vague to match the right tasks.
  • A small skill is easier to test. When one job goes wrong, you know which skill to fix.

Write the description as “use this when” plus the situation, in words people actually type. Compare:

Before: “Helps with reports.”

After: “Use this when you write the monthly operations report for Juniper Outdoor Co. leadership, from the warehouse and returns spreadsheets.”

If two skills keep getting confused, their descriptions overlap. Make each one name a situation the other doesn’t.

Write it

Create a skill has the steps and the fields in the skill editor. Two ways to start:

  • Write it yourself with New Skill on Skills. Best when you already know the steps.
  • Draft it with an agent. In an empty composer, click Attach skills > Add skill > Create skill with Context. The agent asks what the skill should do, then writes it with you. Best right after a task that went well, because the agent can turn that conversation into steps.

Whichever way you start, keep the content concrete:

  • Steps in order, each one an action: “List the three largest cost changes, with last month’s figure beside each.”
  • Rules the agent can check, such as “Under 400 words” or “Every chart has a source line.” Rules such as “Be clear” can’t be checked.
  • One example of good output, if you have one. An example shows tone and level of detail better than a description of them.
  • Only what the agent wouldn’t know. Skip general advice the agent already follows, such as “Check your spelling”. It makes the skill longer without changing the result.

Test it on real tasks

Test a skill on the work it’s meant for before you share it.

  1. Run it. In the skill editor, click Run (“Run with the active agent”). It saves your changes first, then attaches the skill to the composer of the agent you have open. You can also add it to any task with Attach skills.
  2. Use real inputs. Use last month’s real spreadsheet, not a tidy sample. Real inputs show the edge cases.
  3. Compare the result with your own test. Check each rule in the skill. If a rule was broken, the rule is probably unclear, buried, or in conflict with another one.
  4. Fix the skill, not the task. When the result is wrong, change the skill and run it again, instead of correcting the task with a follow-up. A follow-up fixes this result only. A change to the skill fixes every result after it.
  5. Try a few different cases. Try three or four real tasks of different kinds, such as a quiet month and a busy one, before you share it.

After the skill has been used, its Activity tab shows that use.

Improve it over time

A skill is never finished. People find new cases, and the job itself changes. These tools help you keep it right.

Collect feedback

Where feedback is turned on, each agent reply has a Give feedback button, and the task header has Feedback for the whole task. Ask the people who use the skill to rate results and say what went wrong in a line. Then read that feedback before you edit.

Edit and keep the history

Every save that changes the skill creates a new version, and the version number in the top bar goes up. Open History from the version number to see who changed what. Before a big rewrite, check what the skill said before. See Version history.

Let an agent tidy the text

In the skill editor, open Skill actions (next to the name) and choose Optimize. It saves your changes, then fills in the open composer with a request to rewrite the skill so the Markdown is clean, well structured and easy for an agent to follow. Send it, and read the result before you keep it. Optimize improves how the skill reads; it doesn’t measure whether results get better.

Run a measured improvement loop

To improve results, not just wording, click Improve in the skill editor’s top bar (“Improve this skill against its rubric in chat”), or type /improve in a task and name the skill. Improve saves your changes and fills in the open composer for you to send. The agent then:

  1. Changes one thing at a time and runs the skill on a fixed set of tasks.
  2. Keeps a change only if the score goes up.
  3. Saves its candidates as a separate private copy, never over your skill. In a task, you approve each save on a card.
  4. Hands the best version back as a suggestion on your skill.

The loop needs something to score against: an evaluation of the skill with criteria, or a rubric on the skill. If it finds neither, it stops and says so. The loop runs the skill many times, so it costs more than a single task. Improve and Optimize only show on skills you can edit.

Review suggestions

When suggestions are waiting, the skill editor shows a count of improvements in its top bar. Click it, then click Review on a suggestion. The editor shows the proposed changes, and you can Accept all, Reject all or Exit. Nothing changes in your skill until you accept. See Improvement suggestions.

Measure with Evals

For a skill that many people rely on, measure before and after a change. Where Evals is available to you, a skill’s Evaluations tab lists everything that grades it. Click New evaluation and choose:

  • Benchmark: test the skill on a dataset of real tasks.
  • Monitor: grade a sample of its live requests.

In a benchmark that compares Skills, you can compare the latest version with an earlier one using Another version, or with No skill to check that the skill helps at all. Change one thing between runs, so you know what made the difference. See Evals.

Share it and keep it findable

  • Tag it. Add tags in the editor, such as board-decks, so people can filter the skill list. Use the same tags across a team.
  • Share it with the team that does the job. Give the workspace Viewer access, and Editor access to the few people who maintain it.
  • Add it to agents that always need it. Then nobody has to remember to attach it.
  • Name an owner. One person reads the feedback and reviews suggestions, so changes don’t pile up.

See Share and manage skills for each step.

Next steps