Nested Skills Discovery

When working with files in a subdirectory that has its own .claude/skills, those skills should be automatically discovered and available.

Nested Skills Discovery is the automatic availability of skills defined in a .claude/skills directory located in a subdirectory of the current project, enabling distributed skill organization across monorepos and workspace hierarchies.

How It Works

When a Claude Code session initializes, skill discovery traverses the project directory tree. Rather than loading only from the root .claude/skills, the runtime checks all parent and local .claude/skills directories up the hierarchy. This allows each package in a monorepo, git submodule, or workspace section to maintain its own skill definitions without polluting shared skill namespaces.

Test Scope and Result

The test (2026-01-16, version 2.1.6 on 2.1.9) created a nested directory structure with a .claude/skills/nested-test/SKILL.md file deep in the project tree and defined the invocation pattern: a new session started inside the subdirectory should discover and make the nested-test skill available. The test was NOT RUNTIME TESTED. The authors correctly identified that skill discovery depends on working directory context and cannot be verified within the same session; manual verification requires starting a fresh Claude Code session from inside the subdirectory and checking /context or attempting skill invocation.

Why It Matters

This enables more granular skill organization in large projects. Skills are no longer limited to root .claude/skills - they can be distributed throughout the project hierarchy.

Distributed skill definitions support monorepo packages with isolated workflows, project submodules with their own tooling, and team-level skill isolation—each subdirectory can declare its own capabilities without registering globally.

Caveats and Unknowns

The feature was not confirmed at runtime. The test setup is sound and the hypothesis is well-reasoned, but actual discovery behavior—whether the runtime correctly walks the tree, handles conflicts between same-named skills at different levels, and resolves precedence—remains unverified. Manual verification requires a fresh session instantiated in a nested directory.

Evidence & receipt

file2.1.6/tests/01-nested-skills/TEST-RESULTS.md

◇ ed25519 receipt

idprimitive_2c681a7e54b5792e177f7651

alged25519

pubkey9b87705613b1e2fd064d57fa75a6b679d2856ceafad6b1daa8f982493871b6dd

sig

c814d8f7a285948470d38a3db4d97737e6040acf791265acb2bbe60bf61f1e3041e5b82eb3cd5853710b426bb4819294b7703225d434c0e557e80f79641abe0b

Signed with an ed25519 key held off the repo. Anyone can verify against the published public key; nobody without the secret key can forge it. Click verify: it recomputes the signature in your browser. The signature proves integrity and authorship of this exact content — not a third-party timestamp or that the underlying claim is objectively true. signedAt is when the @f3/attest pipeline ran, not when the work happened; the evidence refs carry the source dates.

Connected

instance-of Skill Runtime Class
introduces (in) 2.1.6 Test (2.1.6) Release
verifies (in) Nested Skills Discovery — runtime test Test

Nested Skills Discovery

Primitive

Kind	Primitive
Introduced	Claude Code 2.1.6
Class	Skill Runtime
Epistemic	inconclusive · runtime-test
Evidence	1 ref
Receipt	ed25519 · verifiable

Hands-on runtime test · Claude Code 2.1.6

Cite this page

Hunter, R. "Nested Skills Discovery." The Runtime Atlas. Content-addressed entity primitive_2c681a7e54b5792e177f7651, ed25519-signed (integrity, not third-party timestamp). https://ryanhunter.io/atlas/e/2-1-6-nested-skills

@misc{atlas-2-1-6-nested-skills,
  title  = {Nested Skills Discovery},
  author = {Hunter, Ryan},
  note   = {The Runtime Atlas; entity primitive_2c681a7e54b5792e177f7651; ed25519-signed for integrity},
  url    = {https://ryanhunter.io/atlas/e/2-1-6-nested-skills}
}