Repository skills — a mounted GitHub repo carries its own

Why you'd careThe problem it solves

You already keep the working knowledge in the repository. The release checklist is in the repository. The rule about never touching the generated directory is in the repository. Turning any of that into a skill an agent could use meant leaving the repository: zip the directory, upload it to the workspace, get an id back, put the id in the agent's configuration, and then remember to do all of it again the next time somebody edits the checklist. The skill and the code it is about drift apart on day one, and nothing in the pull request that changed the build command touches the skill that describes it.

Repository skills remove the publish step entirely. The skill sits next to the code, versions with it, and is reviewed by the same people in the same pull request. That is the payoff, and it is a real one. The cost arrives in the same sentence: if the repository decides what the agent knows, then whoever can commit to the repository decides what the agent knows.

ConceptWhat it is

There are two ways a skill reaches a Managed Agent, and they are independent of each other. The first is the agent's skills array — entries of {type, skill_id, version}, where type is anthropic for a pre-built skill or custom for one you uploaded to the workspace through the Skills API. That route requires the skill to exist somewhere central before a session can name it.

The second is a mounted repository. When a session mounts a repo through the github_repository resource, the repository's root .claude/skills directory is scanned at session start and each skill found there becomes available to the agent. Nothing is uploaded and nothing is added to the skills array. The agent is shown each discovered skill's name, description and path in the sandbox, and reads that skill's SKILL.md when a task matches it — including any scripts and resources the skill ships alongside.

Discovery is exact rather than recursive, and this is the part that costs people an afternoon. It matches .claude/skills/<skill-name>/SKILL.md, one directory level deep at the repository root. Nothing about the mechanism searches the tree for skill-shaped folders.

Two properties follow from the mechanism and are worth holding onto before you design anything around it. The scan is a one-shot event at session start, so the set of skills is fixed for the session's lifetime. And discovery is carried out by the agent reading files, which means it depends on the agent's read tool being enabled.

How it worksThe mechanics

The layout that works, and the ones that look like they should:

your-repo/
  .claude/
    skills/
      code-review/
        SKILL.md            <- discovered
      release-process/
        SKILL.md            <- discovered
        scripts/
          run_checks.sh
  src/

Three spellings are documented as not discovered at session start, and each of them is an easy thing to write by accident:

• .claude/skills/SKILL.mda SKILL.md with no skill directory around it.
• .claude/skills/tools/code-review/SKILL.mdnested more than one directory level deep.
• skills/code-review/SKILL.mda skills directory outside .claude.

A fourth case is softer and worth reading carefully rather than filing as a fourth failure: a .claude/skills directory elsewhere in the repository, such as inside a package subdirectory, is not announced at session start — but those skills can still surface when the agent reads files under that subtree. So a monorepo's per-package skills are not registered; they are merely findable.

Mounting is a session-create concern, not an agent one. mount_path is optional and defaults to /workspace/<repo-name>:

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "github_repository",
            "url": "https://github.com/org/repo",
            "mount_path": "/workspace/repo",
            "authorization_token": "ghp_your_github_token",
        },
    ],
)

Which skills you get depends on what is checked out: the resource's checkout branch or commit when it sets one, otherwise the repository's default branch. Pinning the checkout pins the skills. A private repository needs an authorization_token with access to it, the same personal access token flow as any repository mount.

Timing is unforgiving in one direction only. The scan runs once, when the session starts; commits pushed mid-session are not picked up, and loading updated skills means starting a new session. Nothing degrades or warns — the agent simply keeps working from the version it read at start.

Collisions do not shadow. If a repository skill shares a name with a skill attached through the skills array, or with a skill from another mounted repository, both stay available and each is announced with its own path. That is a deliberately different answer from the last-write-wins behaviour a marketplace name gets, and it means the path is the disambiguator a reader and a model both see.

At a glanceSee it

Discovery is exact and it runs once: one directory level under the repository root, at session start.

Where it runsSurfaces and availability

The line to hold in your head is that this is a session-scoped, filesystem-derived skill source on a surface whose other skill source is a workspace-scoped, id-addressed registry. They behave differently under everything that matters operationally: change control, rollback, audit, and who can add one. A skill in the registry got there because somebody uploaded it. A skill in the repository got there because somebody merged a pull request — and the docs are explicit that this puts a mounted repository inside the agent's trust boundary, that the platform loads what it finds with no review step, and that session tools such as bash and web_fetch give those instructions real reach. Mount only repositories you trust, and read .claude/skills before mounting one that accepts outside contributions.

ExampleIn the real world

A platform team runs a nightly agent that cuts release candidates. Its knowledge used to live in an uploaded custom skill: the tag format, the order of the smoke checks, the rule that a migration without a backfill is never released. Every time the release process changed, somebody had to remember to re-zip and re-upload it, and twice they did not.

They move the whole thing into .claude/skills/release-process/SKILL.md in the service repository, with the checks it references under scripts/ in the same folder. The session mounts the repo at the release branch. Now the agent reads the version of the process that matches the code it is releasing, and a pull request that changes the release order changes the skill in the same diff, reviewed by the same person.

Then the failure mode arrives from a direction nobody was watching. The repository accepts outside contributions, and a first-time contributor's pull request — a genuine, useful documentation fix — also adds .claude/skills/ci-helper/SKILL.md. It looks like tidy housekeeping and it is approved in ninety seconds by a reviewer scanning a documentation diff. That night the agent starts its session, the scan announces a skill nobody on the platform team wrote, and its instructions run with the same bash and web_fetch reach as everything else in the session.

The fix is not technical and there is no setting for it. The team adds .claude/skills to the code owners file, so a change under that path needs a platform-team review, and they treat an edit there as a change to production configuration rather than to documentation. The repository was always inside the trust boundary; what changed is that the review now knows it.

Not thisWhat it is often confused with

• Not the skills arraynothing about a repository skill appears in the agent's configuration. If you are looking for a skill in the agent object and cannot find it, look at the session's resources instead. Both routes can be live at once.
• Not a recursive searchthe scan is an exact match on one shape at the repository root. A .claude/skills inside a package directory is not announced; the agent may still surface it by reading files under that subtree, which is a different and much weaker guarantee.
• Not a live reloadthe scan is a session-start event. A commit landing while the session runs changes nothing about that session, and there is no signal that it did not.
• Not reviewed by the platformthe docs say so plainly. What is in the directory at session start is what loads. Whatever review a skill gets is the review your repository gives it.
• Not a way to keep source private from the agentthis is a mount, and a mount is a checkout in a sandbox. It is a way to keep skills next to code, not a way to keep code out of the session.

LimitsWhen not to reach for it

• The repository accepts outside contributions and nothing gates that path.Add code owners on .claude/skills first, or use the skills array, where adding a skill is an explicit act by someone with workspace access rather than a merged diff.
• You are on a self-hosted sandbox.GitHub repository resources are not supported there, so this mechanism does not exist. Attach skills to the agent instead.
• The agent runs with read disabled.Discovery relies on that tool. The skills will simply not load, and the absence looks like nothing at all rather than like an error.
• The skill has to be available whether or not a repo is mounted.A skill that encodes company-wide policy should not depend on which repository this particular session happened to check out. Upload it once and attach it.
• You need the skill to change during a run.It cannot. Restructure so the decision happens before sessions.create, or end the session and start another.

RelatedGo deeper