Write skills and agents for your teams

Last published : Nov 09, 2026
This guide shows you how to write skills, context, and agents for the teams you support, so they load reliably when you provide them through central configuration.
For how to register and assign them, see Set up central configuration.
Related information
Administer Knowledge Worker Agent

Choose a skill, context, or an agent

Use For Cost in every chat
A skill A task people do sometimes, such as building a presentation or reviewing a contract. The assistant loads it when a request matches. Only its description, until it's loaded.
Context Guidance that applies to every conversation, such as a writing style or product facts the assistant must always know. The whole file, in every chat.
An agent A role people choose on purpose, with its own instructions, model, and permissions. Only when someone chooses it.
Put anything occasional in a skill. Context is read in full in every chat, so a large context file makes every conversation slower and more expensive. Keep context for what applies every time.

Write a skill

A skill is a folder with a SKILL.md file, plus any scripts and reference files it needs.
  1. Create a folder, and give it the skill's name, for example contract-review.
  2. In the folder, create SKILL.md with two front matter keys, name and description, followed by the instructions:
    ---
    name: contract-review
    description: Use when reviewing a contract or an NDA for risky clauses. Trigger on requests like "review this contract" or "what should I push back on".
    ---

    # Contract review

    The steps the assistant follows...
  3. Make name the same as the folder name. If they differ, the skill has two names, depending on what reads it.
  4. Keep SKILL.md to the instructions. Put long reference material in a separate file in the folder, and say in SKILL.md when to read it. The assistant then reads it only when it's needed.

Write the description for the moment it's needed

The assistant sees only the name and description of each skill until it decides to load one. The description decides whether the skill is ever used.
  • Say when to use the skill, not what it is.
  • Include the words people actually use when they ask, for example "review this contract".
  • Cover changing and reviewing, not only creating, if people ask for those too.
A description of a few hundred characters is usually enough.

Keep paths relative to the skill

Skills are written to a folder chosen at startup, not to ~/.config/opencode. A skill can't know where it will be, so:
  • Don't put a fixed path in a skill, such as ~/.config/opencode/skills/....
  • Refer to files in the skill's folder relative to the skill's own location.
  • Don't leave placeholders, such as <skill>, for the assistant to fill in. It has nothing to fill them in with.
The same applies to context and agents. In an agent, refer to "the product context in your instructions", not to a file name or path.

Run scripts through an interpreter

Files lose their execute permission when they're written to the workspace. Run a script through its interpreter, for example bash setup.sh or python3 scripts/extract.py, not ./setup.sh.

Turn documents into text or images

Some model providers, such as GitHub Copilot, accept only images as attachments. A skill that works with documents, such as PDF files, must extract their text or render their pages as images. Don't have the assistant attach the document itself.

Ship only what the skill needs

Everything in the skill's folder is copied to every user of the project. Before you add the skill to the repository, remove test output, caches such as __pycache__, and any file with a secret in it.

Write context

  • Use a single Markdown file. Register each file on its own. A context artifact that points to a folder stops the whole run, and the workspace gets nothing.
  • Write it as guidance the assistant can follow in any conversation.
  • Remember that context is guidance, not a control. It's always loaded, but whether the model follows it is best effort.

Write an agent

An agent is an opencode agent file (.md). The simplest way to write one is to build it in the Agent builder, check that it works, and export it. For the steps, see Create your own agents.
If the agent depends on skills, connectors, or context, provide them to the same project. They aren't included in the agent file.

Check the skill before you assign it

These mistakes don't show an error to users. The skill is simply missing:
Mistake What happens
No description The skill is installed, but the assistant never sees it.
Front matter that isn't valid YAML The skill is skipped. The error is only in the log.
No name, or a name that isn't text The skill is skipped without a message.
The same name as another skill Only one of them is used. The log shows a warning.
Knowledge Worker Agent always installs its own skills: the document skills pdf, docx, pptx, and xlsx, and reports-and-dashboards, which builds reports that can be shared. A skill you assign with one of those names replaces the built-in one in the project's workspaces. Use one of those names only to replace the built-in skill.
After you assign the skill, start Knowledge Worker Agent in a workspace of the project, and check that the skill is in the Toolbox. To see what was applied, see Check that it worked.