Status	Last updated	Parent	Read before this
incomplete	2026-04-30	none	none

Companion Skill Pattern

Not yet implemented as a standardised pattern. Sketched here to capture the intent; details and conventions are still open.

Current state

A pattern intended to let consuming projects customise a globally-installed skill without forking it.

The intended shape: a master skill lives in the global ~/.claude/skills/<skill>/ (or installed via the additionalDirectories mechanism). Inside its procedure, it would check for a project-level companion file — typically at <project>/.claude/skills/<skill>/project-config.md or referenced explicitly in the project's CLAUDE.md. If the companion exists, the skill reads it and adapts. If not, it falls back to defaults.

The companion is meant to have a constrained shape: it can override specific values (e.g., commit message format, max iteration counts, preferred test runner), declare project-specific patterns (e.g., "we name endpoints this way"), or add hooks to defined extension points. It cannot replace the skill's procedure or change its contract — that would defeat the purpose of having the master skill global.

Rationale

Without this pattern, projects diverge. Each project copies the global skill, edits it for project-specific needs, and the copies drift over time as the master skill evolves. Pulling in master-skill improvements becomes a manual merge per project, which means it usually doesn't happen.

With it, the master skill stays the source of truth and ships improvements to every project. The companion file is a small, well-scoped customisation surface — a project can declare its conventions without owning the procedure that uses them.

The constraint that companions can't replace the procedure matters. A companion that can override anything is a fork in disguise. Limiting companions to values, patterns, and hooks means the skill's behavior remains predictable and upgrades remain safe.

This pattern complements the Contract - Forge Adapter but addresses a different axis. The forge contract abstracts over which platform a project uses; the companion pattern would abstract over which conventions a project follows on whatever platform.

Open questions

• The exact location and format of the companion file isn't standardised. Options include project-config.md in the skill folder, a section in CLAUDE.md, or something else. Needs a single convention before the pattern can be relied on.
• Which skills should adopt this first. Forge adapters and /develop are likely candidates given how much they vary by project.
• How the master skill discovers and validates the companion (schema? free-form? referenced by a key in CLAUDE.md?).