prime

name

prime

description

Bootstrap a repository with expert skills and context files for productive Claude sessions. Analyzes codebase architecture, proposes domain-specific expert roles, creates SKILL.md files with references, and wires up feature/debug context loaders. Use when starting in a new repo ("/prime", "bootstrap this repo", "set up expert skills"), when skills are stale ("/prime --refresh"), or when the user wants to create expert roles for a codebase they'll work in repeatedly.

Prime

Analyze a codebase and generate expert skills + context files that make every future session productive. Run once to set up, --refresh to keep current.

/prime            → first-time: analyze repo, create expert skills + contexts
/prime --refresh  → update stale skills based on what changed since last prime

Archive root: Resolve $SESSION_KIT_ROOT (default: ~/.stoobz). All ~/.stoobz/ paths below use this root.

Check-In (precondition)

Before the Process section runs, invoke the check-in binary as a silent precondition:

sk checkin --silent --invoking prime

See checkin/SKILL.md for the protocol details (three-tier session-ID resolution, active-dir + ledger creation, scaffolding-idempotent re-entry with liveness refresh).

If sk checkin exits 1 (mkdir or ledger creation failure — the only durability conditions that fail loudly), this skill aborts too. Do not proceed to the Process section.

How It Fits

First time:   /prime → /pickup → [work] → /park
Returning:    /pickup → [work] → /park
Stale repo:   /prime --refresh → /pickup → [work] → /park

/prime creates the permanent knowledge layer (expert skills). /pickup loads session-specific context. Different layers of the same system.

Phase 1: Foundation

Establish the current state of the repo and any existing skills.

1a. CLAUDE.md Check

CLAUDE.md exists?
├── No → Run /init to generate it. Read the result as baseline.
├── Yes → Check staleness:
│   ├── Count commits since CLAUDE.md last modified
│   ├── If >10 commits behind → recommend update:
│   │   "CLAUDE.md is N commits stale. Quick refresh before proceeding?"
│   │   If user agrees → re-run /init to update, read result
│   │   If user declines → read existing CLAUDE.md as-is
│   └── If fresh → read as baseline

1b. Existing Skills Check

Scan .claude/skills/ for */SKILL.md files
├── No skills found → fresh setup, proceed to Phase 2
├── Skills found → report what exists:
│   "Found N existing expert skills: {list with descriptions}"
│   For each skill, check staleness:
│     git log --oneline --since="skill-mtime" -- <relevant-paths> | wc -l
│     "{skill-name} covers {paths} — {N} commits since last update"
│   Ask: "Create fresh skills or update existing ones?"

1c. Stack Detection

Identify the technology stack from project files:

Marker	Stack
package.json	Node/React/Vue/Angular (check dependencies)
*.csproj / *.sln	.NET (check TargetFramework for version)
mix.exs	Elixir/Phoenix
Cargo.toml	Rust
go.mod	Go
Gemfile	Ruby/Rails
pyproject.toml / requirements.txt	Python
pom.xml / build.gradle	Java/Kotlin

Note hybrid stacks (e.g., .NET backend + React frontend).

1d. .claudeignore Generation

Check for an existing .claudeignore in the repo root.

If missing: create it with build artifacts for the detected stack. No approval gate — just create and report one line: "Created .claudeignore with {N} patterns for {stack}.".

If exists: scan for missing patterns from the table below. If any are absent, append them and report: "Added {N} missing patterns to .claudeignore.". If already complete, skip silently.

If --refresh: re-run this check — new dependencies or tooling may have been added.

The stack → ignore-patterns table lives in reference/stack-tables.md — load it for this step.

Phase 2: Deep Analysis

Launch parallel background agents to analyze each architectural layer. Use the Task tool with subagent_type=Explore and run_in_background=true.

Agent assignment based on detected stack. Examples:

Stack	Agents to Launch
.NET + React	Backend (.NET patterns, controllers, services, data), Frontend (React patterns, components, state), Auth/Config (middleware, env config)
Elixir/Phoenix	Domain (contexts, schemas, queries), Web (controllers, views, channels), Infrastructure (config, deployment, telemetry)
React SPA	Components (patterns, state mgmt), API layer (services, hooks), Build/Config (webpack, env, CI)
Go microservice	Handlers (HTTP, gRPC), Domain (models, services), Infrastructure (config, deployment)

Each agent should analyze:

• Key patterns and conventions (with file paths)
• How things are wired together (DI, routing, middleware)
• Non-obvious architectural decisions
• Common gotchas a developer would hit
• Domain vocabulary

Launch 2-4 agents — enough for coverage, not so many they're redundant. While agents run, read key files yourself to build understanding. Synthesize agent results when they complete.

Phase 3: Skill Boundary Proposal (Approval Gate)

Based on analysis, propose expert roles to the user. Present:

Based on the analysis, I recommend N expert skills:

1. {repo}-expert — {what it covers: architecture, domain vocab, key patterns}
2. {repo}-{layer}-expert — {what it covers: specific layer patterns}
3. {repo}-auth-expert — {if auth is complex enough to warrant its own skill}

And 2 context files:
- {repo}-feature-context — loads all experts for feature development
- {repo}-debug-context — loads relevant experts + debugging decision tree

I'd also suggest these per-repo hooks for `.claude/settings.json`:
- {hook description and trigger — see table below}

Does this look right? Any adjustments to skills, contexts, or hooks?

Suggested hooks by stack — the lookup table (and the settings.json hook format used on approval, via /update-config) lives in reference/stack-tables.md. Include only hooks for linters/formatters that are present in the repo (check mix.exs, package.json, pyproject.toml, etc. for the tool before suggesting it). If no hooks are relevant to the detected stack, omit the hooks section from the proposal entirely.

Guidelines for proposing skills:

• 1 skill = 1 mental model. Each skill should represent a distinct area of expertise that a developer would think of as a unit.
• Minimum 2, maximum 5 expert skills. 1 is too broad, 6+ is fragmented.
• Always propose feature + debug contexts. These are the primary entry points.
• Name pattern: {repo}-expert for main, {repo}-{layer}-expert for specialized.
• Don't create a skill for something Claude already knows well (e.g., generic React patterns). Only for project-specific knowledge.

Wait for user approval before proceeding.

Phase 4: Creation

Write the skill files following progressive disclosure. The three output templates (expert SKILL.md structure, feature context, debug context) live in reference/templates.md — load that file when creating them.

Move detailed code examples, integration patterns, and extensive configuration docs into the generated skill's own references/*.md. Keep each generated SKILL.md under 300 lines.

Phase 5: Placement

Detect Existing Structure

Check .claude/skills/ for symlinks:
├── Symlinks found → detect source:
│   readlink on any symlink → extract the skill-hosting repo path
│   Ask: "Skills are symlinked from {path}. Create there?"
│   ├── Yes → create in detected path, run link script if present
│   └── No → create directly in .claude/skills/
├── No symlinks → create directly in:
│   .claude/skills/{skill-name}/SKILL.md
│   .claude/commands/contexts/{context-name}.md

Post-Creation

• Verify all files are readable through their final paths
• Summary: what was created, where it lives, usage instructions

Created N expert skills and 2 contexts:

Skills:
  .claude/skills/{skill-1}/SKILL.md + references/
  .claude/skills/{skill-2}/SKILL.md

Contexts:
  .claude/commands/contexts/{repo}-feature-context.md
  .claude/commands/contexts/{repo}-debug-context.md

Usage:
  /prime --refresh     to update when the codebase evolves
  /{skill-1}           to load specific expert knowledge
  /contexts/{repo}-feature-context  for full-stack feature work
  /contexts/{repo}-debug-context    for debugging

Refresh Mode (--refresh)

When called with --refresh:

1. Skip Phase 1a (don't re-run /init unless CLAUDE.md is very stale)
2. Run Phase 1b — check existing skills against git activity
3. Targeted Phase 2 — only launch agents for layers with significant changes:

   For each existing skill:
     git diff --stat $(stat -f %Sm SKILL.md) -- <covered-paths>
     If >20 files changed or >5 commits → re-analyze that layer
     Otherwise → skip, skill is current
   

4. Phase 1d — re-run .claudeignore check (new deps/tooling may have been added)
5. Phase 3 — propose updates as diffs, not full rewrites. Include hook suggestions for any new tooling detected (e.g., credo was added since last prime):

   {skill-name}: 2 new sections, 1 updated section
   - Added: New background job pattern (CMSWebsite/Jobs/NewJob.cs)
   - Updated: Controller patterns (new base class added)
   - Unchanged: Domain vocabulary, Auth flow
   
   New hook available: credo added to deps — suggest PreToolUse on git commit?
   

6. Phase 4 — update only changed sections, preserve unchanged content
7. Phase 5 — verify placement (should already be wired)

Rules

• One question at a time during approval gates. Don't overwhelm.
• Use parallel agents aggressively in Phase 2 — this is the expensive step, parallelize it.
• Don't create skills for generic knowledge — only project-specific patterns Claude wouldn't know.
• Progressive disclosure — SKILL.md stays lean (<300 lines), details in references/.
• Respect existing work — in refresh mode, update surgically. Don't rewrite what's still accurate.
• Name skills after the repo — {repo}-expert, not generic names like backend-expert.
• Always create both contexts — feature and debug are the minimum useful set.