Support .claude/agents-local/ and .claude/skills-local/ directories (gitignored, markdown)
Problem
Claude Code has a well-established pattern for gitignored local variants of shared configuration:
| Shared (tracked) | Local (gitignored) |
|---|---|
| CLAUDE.md | CLAUDE.local.md |
| .claude/settings.json | .claude/settings.local.json |
However, this pattern does not extend to agents, skills, or commands. Currently:
.claude/agents/*.md— tracked, shared with team ✅~/.claude/agents/*.md— user-level, applies to all projects globally.claude/settings.local.json{ "agents": { ... } }— local, but uses JSON syntax instead of markdown
There is no way to have a project-scoped, gitignored agent or skill defined in markdown.
Why this matters
Teams that want a bottom-up workflow for evolving shared agents and skills — experiment locally first, then promote to shared config once proven — don't have a clean way to do the local experimentation step. The user-level ~/.claude/agents/ pollutes other projects, settings.local.json uses a different syntax than the shared .claude/agents/*.md files, and adding entries to .gitignore is itself a tracked change.
Proposed solution
Support *-local/ variants of the .claude/ subdirectories, following the same pattern as CLAUDE.local.md and settings.local.json:
| Shared (tracked) | Local (gitignored) |
|---|---|
| .claude/agents/*.md | .claude/agents-local/*.md |
| .claude/skills/<name>/ | .claude/skills-local/<name>/ |
| .claude/commands/*.md | .claude/commands-local/*.md |
These directories would:
- Be scanned by the same directory scanner that already handles the shared variants
- Use the exact same format (markdown frontmatter for agents/commands,
SKILL.md+ references for skills) - Be treated as
localSettingssource (likesettings.local.json) - Be added to the default
.gitignoretemplate (or documented as needing to be gitignored)
This way, promoting a local experiment to shared config is literally:
mv .claude/agents-local/reviewer.md .claude/agents/reviewer.md
mv .claude/skills-local/deploy/ .claude/skills/deploy/
Alternatives considered
- Per-file
*.local.mdinside.claude/agents/— Could work for agents and commands if Claude Code recognized*.local.mdas a built-in convention (no.gitignorechange needed, likeCLAUDE.local.md). However, it doesn't extend to skills, which are directories, not single files. - Rely on
settings.local.jsonJSON agents — Works but the syntax gap between JSON and markdown frontmatter adds unnecessary friction when promoting a local experiment to shared config.
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗