Step-by-step guide

Give agents reusable know-how

Capture a repeatable method once and make it available when a task needs it.

You will build: A discoverable skill with an optional reference file.
Time: 10 minutes
Before you start: An agent with the use_skills grant.

What this changes

Skills are useful when a team repeats a method, standard or specialized workflow. They keep that know-how separate from the role itself so it can evolve and be shared independently.

01
Less prompt repetition
Recurring guidance no longer has to be pasted into every task.
02
More consistent execution
A proven method remains available across roles and projects.
03
Knowledge that can evolve
Improve the method without rewriting every agent that relies on it.

Minimum setup

Start with one working configuration.

Create a folder containing SKILL.md. The name and description make it discoverable; the body carries the procedure; nearby files hold detail that should be loaded only on demand.

<workspace>/.clarvis/skills/release-notes/SKILL.md skill

---
name: release-notes
description: Draft release notes from the commits between two git tags. Use when the user asks for a changelog, release notes, or what changed since a given tag.
---

# Release notes

1. Run `git log <previous-tag>..<new-tag> --oneline` to list the commits.
2. Group the entries under Breaking, Added, Fixed, Internal.
3. Write one line per entry, in the imperative mood.
4. Skip merge commits and version-bump commits.

Why this is the minimum

The block above is the whole file, saved at the path on its bar: no registration, no manifest, no index. No registration file is required. A workspace skill travels with the repository, while a skill under ~/.clarvis/skills is available to your personal agents in every workspace.

Working patterns

Adapt it to work you actually do.

Open a pattern to see the complete files and the reason behind each choice.

Pattern 01 A skill that keeps its detail in a reference file Configuration

The instructions are long. You want the short version in the body, and the twelve-page house style guide only fetched when the agent actually needs it. One caveat on the frontmatter below: allowed-tools is parsed and carried on the loaded skill, but nothing reads it today, so it records intent and does not restrict which tools the agent may call.

A skill that keeps its detail in a reference file example

<workspace>/.clarvis/skills/release-notes/SKILL.md

---
name: release-notes
description: Draft release notes from the commits between two git tags. Use when the user asks for a changelog, release notes, or what changed since a given tag.
argument-hint: <previous-tag>..<new-tag>
allowed-tools:
  - shell
  - read_file
---

# Release notes

Before writing anything, call `load_skill` with `name: release-notes` and
`resource: references/format.md` and follow the section order it gives.

1. Run `git log <previous-tag>..<new-tag> --oneline` to list the commits.
2. Group the entries into the sections that file names.
3. Write one line per entry, in the imperative mood.
4. Skip merge commits and version-bump commits.


<workspace>/.clarvis/skills/release-notes/references/format.md

## Section order

Breaking, Added, Fixed, Internal. Omit an empty section.
Never invent a section name.


Verified: the reference file is enumerated as `references/format.md` with
category `references`, and reading it back through the skill returns its text.

Pattern 02 A skill that runs on its own agent Configuration

Triage should not consume the conversation you are in. You want `/triage 4821` to hand the whole thing to a fresh headless run and come back with a report.

A skill that runs on its own agent example

<workspace>/.clarvis/skills/triage/SKILL.md

---
name: triage
description: Triage one bug report end to end and report the root cause with a suggested fix.
argument-hint: <issue number or URL>
metadata:
  delegate: skill-subagent
  author: platform-team
---

Triage the following: $ARGUMENTS

Reproduce it first. Then find the root cause in the code and cite it as
`path:line`. Propose the smallest fix. Do not apply the fix.


Note the nesting. `argument-hint` is a top-level key. `delegate` and `author`
live inside a `metadata:` mapping, one level down. Verified: this file resolves
as delegating, with entry agent `skill-subagent`, hint `<issue number or URL>`
and author `platform-team`, and `/triage 4821` renders with the argument
substituted in place.

Verify the behavior

Check the boundary, not just the happy path.

Use a small disposable task first. Confirm what works and what is deliberately unavailable before relying on the configuration in a real workflow.

01
The skill is listed by the name in its frontmatter.
02
Its description is specific enough for the agent to choose it on the right task.
03
Supporting references are fetched only after the skill is loaded, rather than filling every run context.

Next guide

Set the authority for each role

Separate which tools an agent receives from which commands the runtime will allow.

Continue All guides