Skills

A skill is a directory with a SKILL.md: instructions and support files the agent loads by name when the task calls for them. Write a convention once as a skill and every agent that sees it applies it, instead of maintaining the same paragraph in nine prompts.

What skills do

Every team has knowledge that is not in the code: which migrations need a backfill, how the error taxonomy works, why one module is off limits. The system prompt is what an agent must do every session; a skill is expertise it pulls in only when the task calls for it, so one skill serves many agents without bloating any prompt.

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.

Agents pick up skills two ways: automatically, from the repositories in the sandbox; and explicitly, from the config's skills list.

Repo skills

Every repository in the sandbox contributes its .claude/skills/ directory at the session's checkout. No config change: add the directory, and every agent that clones the repository sees the skill. 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.

Repositories that already package skills as Claude Code plugins for laptop use work too: a committed .claude/settings.json that enables plugins from a marketplace directory inside the repository loads those plugins in cloud sessions, skills, slash commands, and subagents included. A marketplace with a remote source is ignored, and plugin-declared MCP servers and hooks never run: Ellipsis controls the sandbox's MCP servers through your connected integrations. A malformed plugin declaration never fails the session; the session runs without that repository's plugins. Full setup: Teach every agent your team's conventions.

Config skills

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.

trigger:
  type: react
  linear_issue:
    on: [opened]

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.

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 skill installs under the last segment of path (the entry path: skills/release-notes installs as release-notes), and 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, checked at session start:

• At most 10 skills entries per config, each with a unique installed name.
• Each skill: at most 50 files and 512 KiB total, 64 KiB per file, UTF-8 text only. Binary assets are not supported.

Sync and pull request validation also 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.

Keeping skills fresh

A skill states facts about your code, and the code keeps changing under it. A stale skill is worse than none: agents follow it confidently. Assign the maintenance to an agent: a daily cron that diffs the day's merged work against each skill's claims and opens a PR when one has drifted. The full config: Keep your skills from going stale.