Skill authoring

This guide covers how to write a skill the model can select and follow. For the folder format and the selection IDs, see Skills.

What makes a skill useful

A skill supplies knowledge or a procedure the model would otherwise get wrong. Start from real tasks, corrections, and failures. Keep one clear purpose, state a default approach, and spell out project constraints that are not obvious.

Length is not a measure of quality. Use enough structure that the decisions are easy to find, and no more.

Write the description first

The description decides whether the model loads the skill, so write it for that decision.

• Say what the user wants and when the skill helps.
• Say where the skill’s usefulness ends, so the model does not load it for nearby tasks.
• Avoid internal file-format terms as the main hint. “Writes a changelog entry in this repository’s format” is a better hint than “CHANGELOG.md skill”.

Test the description with both likely requests and near misses. A skill about writing config files should not load when the user asks for a plain Markdown checklist.

Folder layout

• Directoryskills/my-skill/

  • SKILL.md
  • Directoryreferences/

    • style-guide.md
  • Directoryscripts/

    • check.sh
  • Directoryassets/

    • …

SKILL.md must start with ---, then a lowercase kebab-case name that matches the folder, a nonempty description of at most 1024 characters, and a closing ---.

Refer to references/, scripts/, and assets/ by relative path in the body. The model reads them with builtin/read_file when it needs them.

A body outline

Use this outline as a starting point. It is a writing aid, not a required format.

# <Task and outcome>

Use for <specific intent>. For <nearby intent>, use <other route>.

## Choose the path
- Explain: answer from the reference below. Read files only if needed.
- Change: carry out the requested work with the steps below.
- Diagnose: start from the reported error and inspect its inputs.

## Inputs and contract
<Required information, safe defaults, paths, field types, constraints.>

## Procedure
1. Establish the target from the information you have.
2. Perform the smallest complete operation the user asked for.
3. Check the result, and fix the actual failure if the check fails.

## Example
<A runnable example, or a labeled fragment with where it goes.>

## Verification and common failures
<What success looks like, boundary cases, and how to recover.>

## Report
<The outcome, the checks you ran, and what remains uncertain.>

Branch before the steps. An explanation request should not inherit steps that edit files.

Write for the model

• Be specific. Give exact field names, file paths, commands, and supported values. Label placeholders as placeholders.
• Prefer examples over prose for error-prone formats. Show a complete example and say where it belongs.
• Give the model judgment where it is needed. If several implementations are reasonable, describe the goal and the constraints instead of a single script.
• Say what the checks prove. A config that parses does not prove a server connects. Name the check and its limit.
• Keep the body within the size limit. load_skill returns the whole body, so it must fit the agent’s max_output_bytes (8192 bytes by default). Move long material into references/.

Keep dynamic data out of the text

Do not write the current time, a location, a credential, or command output into a skill. If the agent needs a value that changes, have it discover the value with builtin/list_vars and builtin/read_var, or have it pass a variable reference to a tool. See Variables.

Test the skill

Test discovery and execution separately.

1. Write a few realistic requests with the outcome you expect. Include near misses that should not load the skill.
2. Run each request with the agent. Check whether the model listed and loaded the right skill, and whether unrelated skills stayed unloaded.
3. Check the result. Did the files change as requested? Did examples parse and run under Raw’s contracts?
4. Compare the revised skill against the previous version with the same model and settings.

Note

Scripted tests can confirm wiring and file formats. Only real model runs show whether the model selects and follows the skill. Record failures as well as successes, and expand the test set around the failures you find.

Pre-ship checklist

• The description selects the right tasks and excludes realistic near misses.
• The body states its purpose and gives a clear next action.
• The how-to, change, and diagnosis paths do only the work each one needs.
• Examples show exactly where they go, and they run.
• Every file the body refers to is present in the skill folder, or in the package’s declared files.
• The body and the catalog fit the agent’s max_output_bytes.
• Any placeholder is labeled, and no credential, path, or time is hard-coded.

Related

• Skills covers the folder format, selection, and the skill tools.
• Packages covers sharing a skill with others.