Guide 04 · Harnesses

Skills: instructions an agent loads when it needs them

A skill is a folder with a SKILL.md file. The agent sees its name and description in every session and reads the rest only when a task matches.

Related:

Settings · Skills

Checked against the source:

Nov 4, 2026

Tools:

OMP 18.14.1 · Claude Code 2.1.281

What it is for

A skill holds instructions, a procedure or reference material that only some of your tasks need. You write it once instead of repeating the same instructions in each session. Unlike a context file such as AGENTS.md, its body costs context only when the agent uses it. The skills GhostFactory loads are listed on Settings · Skills.

How the agent finds and loads a skill

1. At startup the agent gets the name and description of every skill, not the body.
2. When a task matches a description, the agent loads the body: in OMP by reading skill://<name>, in Claude Code with its Skill tool. You can also call a skill yourself: /skill:<name> in OMP, /<name> in Claude Code.
3. Other files in the skill's folder load only when the body points to them and the task needs them.

In our test on Nov 4, 2026, the agent's first step was to read the skill (OMP) or call its Skill tool (Claude Code). The body then stays in the conversation and is not read again. Write what holds for the whole task as a standing instruction, and put the important parts at the top.

Where skills live

Put one folder per skill directly under skills/. A skill one level deeper did not load in either tool (tested Nov 4, 2026). In our setup OMP also loads ~/.claude/skills/, because skills.enableClaudeUser is on. Claude Code skills follow the open Agent Skills format. Other agent CLIs have their own skill support; we have not tested them.

Skill, rule, subagent or hook

A rule that a skill holds only as text can be skipped. When it must hold every time, move it into a hook. In OMP a subagent gets the parent's skill list but not files named AGENTS.md, and a role can preload a skill. The review gate in guide 01 starts its reviewer with skills turned off (--no-skills), so nothing outside the role's own prompt steers it.

What you need

• OMP or Claude Code.
• A project folder under git. Both tools look for project skills up to the repo root.
• A task you repeat often enough to write down.

Steps

1. Write SKILL.md

   The file starts with YAML frontmatter between two --- lines, then the instructions in Markdown. name uses lowercase letters, digits and hyphens and matches the folder name.

   ---
   name: changelog-entry
   description: Writes an entry for CHANGELOG.md in this project's format. Use when the user asks to add a changelog entry, log a change, or describe a fix or feature for the changelog.
   ---
   
   # Changelog entry
   
   Write the entry in this format:
   
       ## YYYY-MM-DD
       - Fixed: one sentence in the past tense.
   
   Rules:
   
   - Use today's date.
   - One bullet per change, at most three.
   - Start each bullet with `Added:`, `Changed:` or `Fixed:`.
   - Put the entry at the top of CHANGELOG.md, below the `# Changelog` title. If the file does not exist, create it with that title.

   Saved as .claude/skills/changelog-entry/SKILL.md, both OMP and Claude Code load it from there.

2. Write the description

   The description decides when the agent picks the skill. Say what the skill does and when to use it, in the words a user would say. Put the main use first: Claude Code cuts a skill's entry in its listing at 1,536 characters and drops descriptions when there are many skills. Say when not to use it.

   description: >
     Generate an end-of-session review queue for another, independent model
     to validate architecture decisions, catch blind spots, and prepare the
     next session. Use when the user says "session review", "end of session
     review", "what did we miss", or explicitly wraps up a coding session.
     Produces three blocks: decision review, open questions and edge cases,
     and pattern validation.

   Model names removed; Czech trigger phrases translated or left out.

   The same skill once existed in two copies with different descriptions. The second one says where it applies and where it does not.

   # The copy in our knowledge repo:
   description: >
     Source of truth for our issue tracker: how to write, triage and plan issues.
     Use ALWAYS when you hear: "create an issue", "write an issue", "triage",
     "sprint planning", "what goes into the sprint".
   
   # The copy the agent loads:
   description: >
     Source of truth for our issue tracker: how to write, triage and plan issues.
     Use for tracker work when the current project belongs to the studio or the
     user names one of its products, and asks to create or check an issue,
     triage, backlog, cycle or sprint planning. Do not use these project rules
     for other workspaces.

   Translated from Czech and shortened; the tracker and product names are removed.

   Only name and description reach the agent. A list of triggers in some other frontmatter field does not help.

3. Add files only when the skill needs them

   Put detail in references/ and checks the agent must run in scripts/. SKILL.md says when to read or run each one. Keep SKILL.md under about 500 lines.

   brand-design/
   ├── SKILL.md
   ├── references/
   │   ├── typography.md
   │   ├── layout.md
   │   ├── motion.md
   │   └── components.md
   ├── scripts/
   │   ├── legibility_audit.py
   │   └── generate_carousel.py
   └── assets/
       └── fonts and logos

   2. Read `references/typography.md` and work out the smallest legible size.
      This is the first step, not the last.
   7. Run `scripts/legibility_audit.py`. Export only when it returns an empty list.
      Do not skip the audit, even in a hurry.
   8. Build the PDF with `scripts/generate_carousel.py` and check the preview
      at feed width.

   Translated from Czech and shortened; the folder is renamed.

4. Keep side effects manual

   A skill that deploys, commits or sends something should run only when you call it. In Claude Code, disable-model-invocation: true means only you can start the skill, and its description stays out of the agent's context.

   ---
   name: deploy
   description: Deploy the application to production.
   disable-model-invocation: true
   ---

   OMP docs list the same key; we have not tested it.

How to check it works

First check that the tool finds the skill, then that the agent uses it.

# OMP: is the skill found? Prints the file, or "Unknown skill".
omp read skill://changelog-entry

# Claude Code: is it in the list?
claude -p "What skills are available? List only their names, one per line."

# Does the agent use it? Run in the project folder.
omp -p "Add a changelog entry: we fixed a crash when the config file is empty."
claude -p --permission-mode acceptEdits "Add a changelog entry: we fixed a crash when the config file is empty."

With the skill, both tools wrote the entry in the skill's format. In a folder without the skill, the same prompt gave a different format.

# Changelog

## 2026-11-04
- Fixed: The application no longer crashed when the config file was empty.

# Changelog

All notable changes to this project are documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

## [Unreleased]

### Fixed

- Fixed a crash when the config file is empty.

To test one skill on its own, omp -p --no-session --skills changelog-entry … limits OMP to that skill, and claude -p --setting-sources project … leaves out your personal skills. A prompt that does not match the description should not load the skill; ours did not. Claude Code docs suggest comparing a few realistic prompts with and without the skill in fresh sessions.

What to watch out for

• observed Oct 15, 2026

  An old copy won

  A skill also lived in another tool's skill folder. OMP kept opening that old text after the project copy was fixed. Turning off that whole source fixed it; a name filter would have hidden the project copy too. Keep one copy per name.

• observed Oct 15, 2026

  One rule in five places

  A commit rule was written in context files, team docs and a skill, each time in different words. It now lives in one rules file, and a hook writes the log line instead of the agent.

• observed Nov 2, 2026

  Generated skills get regenerated

  A code-index tool rewrote its own skill files in the repo each time it re-indexed. Do not hand-edit skills a tool generates, and check git status before you commit.

• observed Nov 4, 2026

  Turning skills off does not hide the file

  In a baseline run with skills off, the agent listed the folder, found SKILL.md and followed it anyway. Run the baseline in a folder without the skill.

• tested Nov 4, 2026

  Nested folders do not load

  A skill one folder deeper than skills/<name>/ did not load in OMP or Claude Code. In our knowledge repo a tool had placed its skills that way, and OMP does not load them from there.

Sources

• Claude Code docs, “Extend Claude with skills” (code.claude.com), checked Nov 4, 2026
• Agent Skills specification (agentskills.io), checked Nov 4, 2026
• OMP docs: skills.md, cli-reference.md, tools/task.md, OMP 18.14.1
• OMP config.yml and the user skills in our setup, checked Nov 4, 2026
• adr/ADR-002-skill-taxonomy.md and K-B sprint notes, Oct 15 and Nov 2, 2026
• hooks/pre-commit in GhostFactory's knowledge repo (K-B)
• Our test runs in a scratch folder, Nov 4, 2026

← All guides