| name | project-local-skills |
| description | How to create, manage, and share project-local skills — .clarc/skills/ structure, scope hierarchy, team workflow, and promotion to global clarc |
| skill_family | clarc-workflow |
| related_agents | [] |
| tags | ["clarc","skills","project-local","team"] |
| version | 1.0.0 |
Project-Local Skills
Project-local skills live in .clarc/skills/ inside a project repository.
They are automatically loaded at session start and override global clarc skills of the same name.
When to Activate
Use project-local skills when:
- A team has project-specific conventions (internal API patterns, company auth library)
- Conventions differ from clarc's global rules for this codebase
- A migration is underway and the pattern is temporary
- The skill should be versioned alongside the code it describes
Directory Structure
<project-root>/
.clarc/
skills/
our-auth-pattern/
SKILL.md ← project-local skill
internal-api/
SKILL.md
instincts.md ← personal learned patterns (gitignore this)
context.md ← last session context
progress.md ← current progress
Scope Hierarchy
Skills are resolved in this order (highest precedence first):
1. .clarc/skills/<name>/ → project-local (this project only)
2. ~/.clarc/skills/<name>/ → global clarc (all projects)
3. Claude Code native skills → built-in system-reminder skills
When a local skill overrides a global one, session-start logs:
Local skill 'typescript-patterns' overrides global version
Creating a Project-Local Skill
/skill-create --local <name>
Scaffolds .clarc/skills/<name>/SKILL.md:
---
title: <Name>
scope: project-local
tags: []
created: <date>
team:
---
## When to Use
<situation that calls for this skill>
## Pattern
<the approved approach, with code examples>
## Anti-patterns
<what NOT to do>
## References
<internal docs, ADRs, tickets>
Fill in the sections, then commit .clarc/skills/ to the repo.
Team Workflow
1. Developer creates skill: /skill-create --local our-auth-pattern
2. Fills in pattern content
3. Commits .clarc/skills/ to the project repo
4. Team pulls → all members get the skill at next session start
5. When ready for global use: /promote-skill our-auth-pattern
Listing Local Skills
/skills-local
Output:
Project-local skills — .clarc/skills/ (2 skills)
our-auth-pattern How we use the internal auth library
payment-flow Approved payment integration pattern
Total: 2 local · 0 override global
Promoting to Global
When a project-local skill is useful across multiple projects:
/promote-skill our-auth-pattern
/promote-skill our-auth-pattern --pr
Safety checklist before promoting:
What to Gitignore
# Keep skills committed (shared with team)
# .clarc/skills/ ← do NOT ignore
# Keep instincts private (personal learning)
.clarc/instincts.md
.clarc/context.md
.clarc/progress.md
Or commit everything if the full memory bank should be shared.
Anti-patterns
- Creating a local skill for something already covered by a global clarc skill (use
/find-skill first)
- Promoting a skill that still contains internal URLs or company names
- Putting project-local skills in
~/.clarc/skills/ — those become global for all projects
- Forgetting to commit
.clarc/skills/ — other team members won't see the skill
Related Commands
/skill-create --local <name> — scaffold a new project-local skill/skills-local — list all local skills and override status/promote-skill <name> — promote a local skill to global scope/find-skill <topic> — search global clarc skills before creating a new one
