Skills

Documents tell an assistant what is true. Skills tell it how to do something.

A release process, for example, has an order and several points where the assistant must stop for confirmation. Turn that process into a skill and the assistant can follow it whenever you ask for a release.

One source, several assistant formats

AI assistants use different skill formats and locations. In Deerlight, you maintain one source body, and Deerlight produces the appropriate format for Claude, Codex, and Trae.

You can change assistants or use several without rewriting the skill.

Write a skill

A skill has three parts:

Title — the human-readable name, also used to derive a filename.

When to use it — one sentence that clearly states the situation that should trigger this skill.

This sentence is crucial because assistants use it to decide whether to load the skill. It must answer “when should I use this?”, not “what is this?”:

✓ Use when publishing a new release: covers the required order for tags, artifacts, and rollout, plus the points that require confirmation.

✗ Release process.

The second description is too vague to match reliably.

Body — the actual procedure and decision rules. A useful structure is:

## When to use
(The concrete situations that should trigger this skill.)

## How to proceed
(Steps and decision rules.)

## Boundaries
(Where the skill does not apply, including known traps and counterexamples.)

Boundaries are often omitted and especially valuable: assistants more often fail by applying a good procedure in the wrong situation than by forgetting the procedure itself.

Do not hard-code one assistant’s local path or tool name in a shared body. Write instructions that remain valid when Deerlight generates another assistant’s format.

User-level and project-level skills

A skill can belong to one project or be available across all your projects.

A general commit-message convention is a good user-level skill. A release procedure unique to one product belongs in that project’s scope. You can move a skill later.

After an update

When a skill changes, assistants that installed it receive the new version the next time they use it. If nothing changed, they use the local copy instead of downloading the same body again.

Disable a skill

When you disable a skill:

• assistants can no longer obtain its body;
• an assistant that installed it is instructed to remove its local copy the next time it checks;
• the skill remains visible but inactive in Deerlight and can be enabled again later.

Import an existing skill

If you already have a skill file on a machine, import it into Deerlight and manage future versions from one place.