project-local-skills

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        # Copy to ~/.clarc/skills/
/promote-skill our-auth-pattern --pr   # Also open upstream PR

Safety checklist before promoting:

• Remove internal URLs and company-specific names
• Replace hardcoded paths with generic examples
• Ensure examples work without internal dependencies

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