# 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

```bash
echo "worklog" > .skills
```

### 2. Update `.envrc`

Add to your project's `.envrc`:

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

### 3. Update `.gitignore`

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

### 4. (Optional) Add agent context

Add to your `AGENTS.md` or `CLAUDE.md`:

```markdown
## Skills

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

### 5. Commit and share

```bash
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.