e921fd96df
- Add bin/use-skills.sh helper with use_skill and load_skills_from_manifest - Add .skills manifest pattern for declarative skill configuration - Fix ai-skills.nix: remove broken npm plugin code, update skill list - Add update-opencode, web-search, web-research to flake.nix availableSkills - Add RFC and documentation for team adoption 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
134 lines
3.3 KiB
Markdown
134 lines
3.3 KiB
Markdown
# 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.
|