Support .claude/agents-local/ and .claude/skills-local/ directories (gitignored, markdown)

Resolved 💬 2 comments Opened Apr 1, 2026 by lslv1243 Closed May 8, 2026

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 localSettings source (like settings.local.json)
  • Be added to the default .gitignore template (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.md inside .claude/agents/ — Could work for agents and commands if Claude Code recognized *.local.md as a built-in convention (no .gitignore change needed, like CLAUDE.local.md). However, it doesn't extend to skills, which are directories, not single files.
  • Rely on settings.local.json JSON agents — Works but the syntax gap between JSON and markdown frontmatter adds unnecessary friction when promoting a local experiment to shared config.

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗