Give agents skills

A skill is a directory with a SKILL.md: instructions and support files Claude Code loads by name when the task calls for them. Where the system prompt is what an agent must do every session, a skill is expertise it pulls in only when relevant, so one skill serves many agents without bloating any prompt.

Agents pick up skills two ways: automatically, from the .claude/skills/ directory of every repository in the sandbox, and explicitly, from the config's skills list.

Check skills into a repository

Every repository in the sandbox contributes its .claude/skills/ at the session's checkout. No config change: add the directory, and every agent that clones the repository sees the skill.

A skill that teaches agents how splitshift-api migrations work, at splitshift-api/.claude/skills/schema-migrations/SKILL.md:

---
name: schema-migrations
description: How schema migrations work in splitshift-api. Use when writing, reviewing, or debugging a migration.
---

Migrations are dated SQL files under db/migrations/, applied in filename
order by `make migrate`. Rules:

- Never edit an applied migration; fix forward with a new file.
- Every new table needs a `restaurant_id` column and an index on it.
- Run `make check-migrations` before opening a pull request.

The frontmatter name and description are what the agent sees at startup; it reads the body when the work matches the description. When the Linear issue implementer picks up a schedule-conflict bug that needs a schema change, it reads the skill, writes the migration as a dated file, and runs make check-migrations before opening the PR.

Because repository skills load at the session's checkout, skill and code move together: a PR session that edits both sees its own version of the skill.

Declare skills in the config

The skills list installs skills the sandbox repositories don't provide: a skill elsewhere in the config's repository, a shared skills repository your whole org maintains, or a public repository. Each entry names a directory containing a SKILL.md:

ellipsis:
  version: v1
  name: Linear issue implementer
  description: Implements Linear issues as pull requests

claude:
  system: |
    Implement the Linear issue this session was started for. Open a
    pull request and link the issue in its description.

triggers:
  - type: react
    events:
      - event: linear_issue_open

sandbox:
  repositories:
    - name: splitshift-api

skills:
  - path: .agents/skills/pr-conventions
  - path: skills/release-notes
    repository:
      name: platform-skills

The first entry resolves in the repository this config lives in. The second pulls skills/release-notes from splitshift-hq/platform-skills, a repository this sandbox never clones: that is how one skills repository serves every agent in the org. repository takes any repository of your installation, or a public repository from another owner (owner: anthropics); private repositories outside your account are rejected.

Config-declared skills also work for sessions with no repositories at all, where there is no .claude/skills/ to load from.

How skills resolve

Config-declared skills are fetched at session start, before the agent begins:

• A bare path resolves in the config's repository: at the session's checkout when that repository is in the sandbox, otherwise at the head of the branch the config syncs from.
• An entry with repository resolves there: at the session's checkout when that repository is in the sandbox, otherwise at repository.ref if set, otherwise at the head of its default branch.
• The files are installed at the sandbox's personal skill level (~/.claude/skills/) under the last segment of path (the entry path: skills/release-notes installs as release-notes). Personal skills take precedence over repository skills, so a config-declared skill deterministically overrides a same-named repository skill.

A skill that cannot be resolved fails the session before the agent starts: status is error, and the session's status_reason names the entry and what went wrong (no SKILL.md at the path, an unreachable repository, a limit exceeded). A session never runs with a silently missing skill.

Limits

• At most 10 skills entries per config.
• Each skill: at most 50 files and 512 KiB total, 64 KiB per file, UTF-8 text only. Binary assets are not supported.
• Installed names must be unique: two entries whose paths end in the same directory name fail validation.

Sync and pull request validation check each bare-path entry's SKILL.md at the pushed commit, so a typo'd path or broken frontmatter fails before the config registers. Entries with repository are checked at session start.

Next

• Every skills field, default, and constraint: Agent config.
• What else is in the sandbox skills land in: The sandbox.