Harnesses

Default targets

shelf writes borrowed skills to two directories in each project:

These two cover every harness below except Kiro and a few that document neither directory. Change the default for all your projects with targets in the config; change it for one project with shelf targets.

Where each harness looks

As of October 2026:

Harness ids

shelf targets knows these harnesses. Use the id (or the directory) with --add and --remove.

The user directories matter in two places: shelf setup installs the bundled shelf skill in ~/.agents/skills and ~/.claude/skills, plus the user directory of any installed harness that doesn't read .agents/skills (for example ~/.kiro/skills when ~/.kiro exists). And shelf insights counts the skills in all of them as "loaded everywhere".

Only Claude Code and Codex get hooks.

Project targets

$ shelf targets
Skills are written to: .agents/skills, .claude/skills (your default)

HARNESS    DIRECTORY              NOTE
agents     .agents/skills     on  detected
claude     .claude/skills     on  detected
kiro       .kiro/skills           detected
github     .github/skills         reads .agents/skills
cursor     .cursor/skills         reads .agents/skills
…
openhands  .openhands/skills      

Kiro is used here but does not read .agents/skills: shelf targets --add kiro

detected means the harness's config directory (such as .kiro/) exists in the project. shelf suggests adding a detected harness that doesn't read .agents/skills and isn't already covered.

$ shelf targets --add kiro
Skills are written to: .agents/skills, .claude/skills, .kiro/skills
…

Changing targets moves every loan in the project: copies appear in added directories and are removed from removed ones. The project's targets are written to its lockfile ("targets": [...]), so every clone uses them.

A directory that isn't a known harness works too, as long as it is inside the project: shelf targets --add tools/agent-skills. A project needs at least one target.

Symlinked harness directories

Some projects symlink one harness directory to another, such as .claude/skills → .agents/skills. shelf compares targets by their real path: aliases are written once, never turned into a link to themselves, and removing one name never deletes the copy behind the other. shelf targets notes such a harness as same directory as … (symlink).

Link mode

By default every target holds its own copy. In link mode, the first target holds the only real copy and the others are relative symlinks to it (junctions on Windows):

$ shelf borrow pdf-tools --link
Borrowed pdf-tools (due 2026-11-06) → .agents/skills, .claude/skills

$ ls -l .claude/skills
lrwxrwxrwx 1 me me 30 Oct  7 13:35 pdf-tools -> ../../.agents/skills/pdf-tools

Use --link per loan, or "mode": "link" in the config for every new loan. The lockfile records "mode": "link" for such loans. Hashing follows symlinks, so content states work the same in both modes.

Why copies, not symlinks

Symlinked skills have open or recent bugs in Cursor, Claude Code and Codex, mostly on Windows, and Windows-native apps can't follow Linux symlinks inside WSL. Copies work everywhere, and shelf tracks them by hash, so they can't drift unnoticed. Use link mode in projects where you know symlinks work.

Frontmatter

The Agent Skills spec requires name (1 to 64 characters of [a-z0-9-], matching the directory) and description (at most 1024 characters). The reference validator rejects unknown top-level keys, and some harnesses silently skip skills that fail validation. shelf therefore never writes its own fields into SKILL.md; all tracking data lives in the lockfile and the database.

Adding a harness to shelf

Harnesses are one entry each in packages/core/src/projection/harnesses.ts. Add the entry and a row to the tables on this page. See Architecture.

Sources

• Spec: https://agentskills.io/specification
• Claude Code: https://code.claude.com/docs/en/skills
• Codex: https://learn.chatgpt.com/docs/build-skills
• Cursor: https://cursor.com/docs/context/skills
• Gemini CLI: https://geminicli.com/docs/cli/skills/
• Copilot: https://docs.github.com/en/copilot/concepts/agents/about-agent-skills
• OpenCode: https://opencode.ai/docs/skills/
• Amp: https://ampcode.com/docs/customize/skills
• Windsurf / Devin: https://docs.devin.ai/desktop/cascade/skills
• Goose: https://goose-docs.ai/docs/guides/context-engineering/using-skills
• Cline: https://docs.cline.bot/features/skills
• Roo Code: https://roocodeinc.github.io/Roo-Code/features/skills
• Factory: https://docs.factory.com/cli/configuration/skills
• Kiro: https://kiro.dev/docs/skills/