skills/docs/approach/2026-01-25-skill-organization.md

Approach: Skill Organization Across Agents

Strategy

Core philosophy: Single source, Nix-deployed, per-repo filtered.

Skills live in dotfiles. Nix deploys them to each agent's expected location. Pi's settings handle per-repo filtering via includeSkills/ignoredSkills.

Key Decisions:

1. Source location: ~/proj/skills/skills/ vs ~/proj/dotfiles/skills/ → dotfiles — skills are config, not code. Dotfiles is the deployment source.

2. Deployment target: Single location vs all agent locations → All locations — deploy to ~/.claude/skills/, ~/.codex/skills/, ~/.config/opencode/skills/ for compatibility. Pi reads from ~/.claude/skills/ (disable other pi sources).

3. Per-repo filtering mechanism: Project config vs global config per repo → Pi settings — use includeSkills/ignoredSkills in project .pi/settings.json. Other agents don't support this, but pi is primary.

4. Development workflow: Direct edit in dotfiles vs edit in skills repo + deploy script → Skills repo + deploy — develop/test in ~/proj/skills/, run deploy-skill.sh, Nix rebuild picks it up.

5. Existing scattered skills: Migrate vs leave in place → Migrate — consolidate everything to dotfiles, remove old locations after Nix manages them.

Architecture

Directory Structure

~/proj/skills/skills/<name>/        # Development (universal)
         │
         │  deploy-skill.sh <name>
         ▼
~/proj/dotfiles/skills/<name>/      # Nix source (universal)
         │
         │  home-manager rebuild
         ▼
~/.claude/skills/<name>/            # Claude Code + Pi
~/.codex/skills/<name>/             # Codex
~/.config/opencode/skills/<name>/   # OpenCode


~/proj/skills/skills/<name>/        # Development (pi-only)
         │
         │  deploy-skill.sh <name> --pi-only
         ▼
~/proj/dotfiles/pi/skills/<name>/   # Nix source (pi-only)
         │
         │  home-manager rebuild
         ▼
~/.pi/agent/skills/<name>/          # Pi only

Two tiers:

• Universal: Deploy to all agents (~/.claude/, ~/.codex/, ~/.config/opencode/)
• Pi-only: Deploy to ~/.pi/agent/skills/ only (for extension-dependent skills like ralph-work-loop)

Pi Settings

Global ~/.pi/agent/settings.json:

{
  "skills": {
    "enableClaudeUser": true,    // Universal skills (~/.claude/skills/)
    "enablePiUser": true,        // Pi-only skills (~/.pi/agent/skills/)
    "enableCodexUser": false,    // Don't double-load (Nix manages ~/.codex/)
    "enableClaudeProject": true,
    "enablePiProject": true
  }
}

Pi reads from both ~/.claude/skills/ (universal) and ~/.pi/agent/skills/ (pi-specific).

Per-Repo Filtering

Project .pi/settings.json:

{
  "skills": {
    "ignoredSkills": ["nix-review", "ops-review"]
  }
}

Or positive filtering:

{
  "skills": {
    "includeSkills": ["worklog", "code-review", "intent", "approach", "work"]
  }
}

Nix Module

In home/skills.nix (or similar):

{
  home.file = {
    ".claude/skills" = {
      source = ./skills;
      recursive = true;
    };
    ".codex/skills" = {
      source = ./skills;
      recursive = true;
    };
    ".config/opencode/skills" = {
      source = ./skills;
      recursive = true;
    };
  };
}

Risks

Known Unknowns

• OpenCode skill format: Does it use the same SKILL.md format? Need to verify.
• Codex recursive scanning: Pi docs say it scans recursively — does Codex itself do this too?
• Project-local skills: Should these also be standardized, or left as-is per project?

Failure Modes

• Nix rebuild required: Skills don't update until rebuild. Could forget and wonder why changes aren't visible.
• Agent format drift: If an agent changes its skill format, we'd need to adapt.
• includeSkills too restrictive: Forget to add a skill to the include list, then wonder why it's not loading.

Blast Radius

• Dotfiles changes: Modifying Nix config affects all machines using these dotfiles.
• Removing old locations: If we delete ~/.pi/agent/skills/ contents, need to ensure pi settings are updated first.

Phases

Phase 1: Consolidate to Dotfiles

• Move all global skills to ~/proj/dotfiles/skills/
• Update Nix to deploy to all agent locations
• Update pi settings to read from ~/.claude/skills/ only

Phase 2: Clean Up Old Locations

• Remove skills from ~/.codex/skills/, ~/.pi/agent/skills/ (Nix now manages these)
• Verify all agents still work

Phase 3: Per-Repo Filtering

• Add .pi/settings.json to repos that need filtering
• Document the pattern for future repos