skills/docs/RFC-SKILLS-MANIFEST.md

RFC: .skills Manifest Pattern

Status: Draft Created: 2024-11-30 Author: dan + claude

Summary

A lightweight pattern for per-repo skill deployment where projects declare desired skills in a .skills manifest file. This enables:

• Team members get skills on clone + direnv allow
• Agents can query installed skills without loading full docs
• Agents can install skills by editing the manifest
• Central skills repo remains single source of truth

Motivation

Current State

• Skills live in central skills repo
• Global deployment via Nix Home Manager to ~/.claude/skills/
• Per-repo deployment undocumented and manual

Problems

1. No per-repo differentiation - all projects get same global skills
2. Agent context bloat - loading full skill docs is expensive
3. No standard pattern - each project reinvents .envrc setup
4. Agent can't help - no standard way for agent to install skills

Goals

1. Projects declare which skills they need
2. Team members get skills automatically (via direnv)
3. Agents can answer "what skills do we have?"
4. Agents can add skills with minimal context

Design

The .skills Manifest

A simple text file in project root:

# .skills - AI agent skills for this project
# Run `direnv reload` after editing

worklog
web-search

Format:

• One skill name per line
• Lines starting with # are comments
• Empty lines ignored
• Skill names match flake package names

The .envrc Integration

Projects add to their .envrc:

# AI Agent Skills
if [[ -f .skills ]]; then
  export CODEX_HOME="$PWD/.codex"  # Optional: per-repo Codex skills
  SKILLS_REPO="${SKILLS_REPO:-git+file://$HOME/proj/skills}"
  mkdir -p .claude/skills .opencode/skills
  while IFS= read -r skill || [[ -n "$skill" ]]; do
    [[ -z "$skill" || "$skill" =~ ^[[:space:]]*# ]] && continue
    skill="${skill%%#*}"  # strip inline comments
    skill="${skill// /}"  # strip whitespace
    out=$(nix build --print-out-paths --no-link "${SKILLS_REPO}#${skill}" 2>/dev/null)
    if [[ -n "$out" ]]; then
      ln -sfn "$out" ".claude/skills/${skill}"
      ln -sfn "$out" ".opencode/skills/${skill}"
      if [[ -n "${CODEX_HOME:-}" ]]; then
        mkdir -p "${CODEX_HOME}/skills"
        ln -sfn "$out" "${CODEX_HOME}/skills/${skill}"
      fi
    fi
  done < .skills
fi

Or source the helper:

if [[ -f .skills ]]; then
  export CODEX_HOME="$PWD/.codex"  # Optional: per-repo Codex skills
  source ~/proj/skills/bin/use-skills.sh
  load_skills_from_manifest
fi

The .gitignore Entries

.claude/skills/
.opencode/skills/
.codex/skills/

The manifest (.skills) IS committed. The symlinks are not.

Agent Context Blurb

Add to project's CLAUDE.md or AGENTS.md:

## Skills

This project uses AI agent skills. Skills are declared in `.skills` and installed via direnv.

**Installed**: See `.skills`
**Available**: worklog, web-search, web-research, update-opencode, update-spec-kit, niri-window-capture, screenshot-latest, tufte-press
**To add**: Edit `.skills`, then run `direnv reload`
**Docs**: See ~/proj/skills for full skill documentation

This gives the agent enough context (~4 lines) to:

• Answer "what skills do we have?" → read .skills
• Add a skill → edit .skills, tell user to direnv reload
• Know where to find full docs if needed

Workflow

Initial Setup (one-time per project)

1. Create .skills with desired skills
2. Add skills loader to .envrc
3. Add .claude/skills/ to .gitignore
4. Add brief context to project's CLAUDE.md
5. Commit

Team Member Onboarding

1. Clone repo
2. Run direnv allow
3. Skills are installed automatically

Adding a Skill

Human workflow:

1. Edit .skills, add skill name
2. Run direnv reload

Agent-assisted workflow:

1. Human: "add the worklog skill"
2. Agent: edits .skills, adds worklog
3. Agent: "Added worklog to .skills. Run direnv reload to install."

Querying Skills

"What skills do we have?"

• Agent reads .skills file
• Or runs ls .claude/skills/

"What skills are available?"

• Agent references the list in CLAUDE.md context
• Or runs nix flake show $SKILLS_REPO

File Locations

project/
├── .skills              # Manifest (committed)
├── .envrc               # Loads skills from manifest (committed)
├── .gitignore           # Ignores .claude/skills/ (committed)
├── CLAUDE.md            # Agent context blurb (committed)
├── .claude/
│   └── skills/          # Symlinks to nix store (NOT committed)
│       ├── worklog -> /nix/store/xxx
│       └── web-search -> /nix/store/yyy
└── .opencode/
    └── skills/          # Same symlinks (NOT committed)

Helper Script

skills/bin/use-skills.sh provides:

# Load skills from .skills manifest
load_skills_from_manifest() {
  [[ ! -f .skills ]] && return
  mkdir -p .claude/skills .opencode/skills
  while IFS= read -r skill || [[ -n "$skill" ]]; do
    [[ -z "$skill" || "$skill" =~ ^[[:space:]]*# ]] && continue
    use_skill "${skill%%#*}"
  done < .skills
}

Migration

Existing Projects

1. Survey current .envrc files for skill-related setup
2. Extract skill list to .skills
3. Replace custom logic with standard pattern
4. Add CLAUDE.md context blurb

New Projects

Use the template:

cp ~/proj/skills/templates/skills-envrc-snippet.sh .envrc.skills
cat .envrc.skills >> .envrc
echo "worklog" > .skills
echo ".claude/skills/" >> .gitignore

Alternatives Considered

Full flake.nix in each project

• Heavier than needed
• Not all projects want/have flake.nix
• Decided: .envrc + nix build is lighter

Central config mapping repos to skills

• Single view of all projects
• But adds indirection and sync complexity
• Decided: per-repo manifest is simpler

Agent edits .envrc directly

• Fragile - .envrc has other content
• Decided: separate .skills file is cleaner for agent editing

Open Questions

1. Should we validate skill names? Currently fails silently if skill doesn't exist.
2. Should we support skill versions? e.g., worklog@v1.2.0
3. Should there be a skills CLI? e.g., skills add worklog, skills list

Implementation Checklist

• Create bin/use-skills.sh helper
• Create docs/PER-REPO-SKILLS.md documentation
• Create this RFC
• Update bin/use-skills.sh with load_skills_from_manifest
• Create template .skills file
• Create template CLAUDE.md blurb
• Survey existing projects for migration
• Migrate pilot project
• Update AGENTS.md with pattern reference