skills/docs/RFC-TEAM-SKILLS-ADOPTION.md

RFC: Per-Project AI Agent Skills

Status: Proposal Date: 2025-11-30 Audience: All project teams using Claude Code or OpenCode

Summary

A standard pattern for projects to declare which AI agent skills they need. Team members automatically get the right skills when they clone and enter the project directory.

Problem

Currently, AI agent skills are deployed globally to everyone's machine. This means:

• All projects get all skills, whether they need them or not
• No way to share project-specific skills with teammates
• No visibility into what skills a project uses

Solution

Projects declare their skills in a .skills file. When you enter the directory (via direnv), the skills are automatically installed.

# .skills
worklog
web-search

That's it. Clone the repo, run direnv allow, and you have the skills.

How It Works

You clone a repo with .skills file
    ↓
Run `direnv allow`
    ↓
direnv reads .skills, builds each skill via Nix
    ↓
Skills symlinked to .claude/skills/ and .opencode/skills/
    ↓
Claude Code / OpenCode sees the skills

Skills come from the central skills repo (~/proj/skills), so everyone gets the same version.

Available Skills

Skill	Description
worklog	Create org-mode worklogs documenting sessions
web-search	Search the web via Claude subprocess
web-research	Deep research with multiple backends
update-opencode	Update OpenCode version via Nix
niri-window-capture	Capture window screenshots (security-sensitive)
tufte-press	Generate Tufte-style study cards

Adopting This Pattern

1. Create .skills file

echo "worklog" > .skills

2. Update .envrc

Add to your project's .envrc:

# AI Agent Skills
if [[ -f .skills ]]; then
  source ~/proj/skills/bin/use-skills.sh
  load_skills_from_manifest
fi

3. Update .gitignore

echo ".claude/skills/" >> .gitignore
echo ".opencode/skills/" >> .gitignore

4. (Optional) Add agent context

Add to your AGENTS.md or CLAUDE.md:

## Skills

This project uses AI agent skills declared in `.skills`.
- **Installed**: See `.skills`
- **To add**: Edit `.skills`, run `direnv reload`

5. Commit and share

git add .skills .envrc .gitignore
git commit -m "Add AI agent skills support"

Teammates will get the skills when they direnv allow.

FAQ

Q: Do I need Nix? A: Yes. Skills are built via Nix for reproducibility.

Q: What if I'm offline? A: Works fine. Skills build from the local ~/proj/skills repo.

Q: Can I pin a specific version? A: Yes. Use SKILLS_REPO="git+file://$HOME/proj/skills?rev=abc123" in your .envrc.

Q: What if a skill doesn't exist? A: The build will fail silently for that skill. Check the name matches a skill in the repo.

Q: How do I see what skills are installed? A: ls .claude/skills/ or cat .skills

Q: How do I add a skill after setup? A: Edit .skills, then run direnv reload.

Future Improvements

1. Global direnv helper - Add load_project_skills to ~/.config/direnv/direnvrc so .envrc only needs one line
2. CLI tool - skills init to set up a project, skills add <name> to add skills
3. Validation - Warn if a skill name doesn't exist

Questions / Feedback

Open an issue in the skills repo or ask in the team channel.