skills/DEPLOYMENT.md

# Skills Deployment Strategy

## Current State

This repository (`~/proj/skills`) is a **development and testing repository** for AI agent skills. It is NOT the deployment location.

**Actual deployment** happens from `~/proj/dotfiles`:
- Source: `~/proj/dotfiles/claude/skills/`
- Runtime: `~/.claude/skills/` and `~/.config/opencode/skills/`
- Managed by: Home Manager (Nix)

## Deployment Model

### Global Skills (System-Wide)

**Path**: `~/proj/dotfiles/claude/skills/<skill-name>/`

**Deployed to**:
- `~/.claude/skills/<skill-name>/` (Claude Code)
- `~/.config/opencode/skills/<skill-name>/` (OpenCode)

**Who uses**: All AI agents, all projects

**Examples**:
- `worklog` - Document work sessions
- `update-spec-kit` - Update spec-kit ecosystem

### Project-Local Skills

**Path**: `<project>/.opencode/command/<skill-name>.md`

**Deployed to**: Loaded directly from project directory

**Who uses**: Only when working in that specific project

**Examples**:
- `/test` in dotfiles (runs `nix flake check`)
- `/rebuild` in dotfiles (runs `nixos-rebuild`)
- `/speckit.*` in skills repo (spec-kit commands)

## Deployment Categories for Our New Skills

### 1. screenshot-latest (Global)

**Category**: Global skill  
**Why**: Useful in any project where user takes screenshots  
**Security**: Low risk (just finds existing files)  

**Deployment path**: `~/proj/dotfiles/claude/skills/screenshot-latest/`

**Usage scenarios**:
- Writing documentation with screenshots
- Analyzing UI/UX in any project
- Debugging visual issues
- General screenshot reference

### 2. niri-window-capture (Global, Security-Sensitive)

**Category**: Global skill  
**Why**: Window capture capability useful system-wide  
**Security**: HIGH RISK (invisible cross-workspace capture)  

**Deployment path**: `~/proj/dotfiles/claude/skills/niri-window-capture/`

**Requirements before deployment**:
1. User must review SECURITY.md
2. User must configure niri block-out rules
3. User must understand audit logging
4. User must trust the AI agent

**Usage scenarios**:
- Capture window from inactive workspace for analysis
- "Find the window with error message" across all workspaces
- Compare windows side-by-side without switching
- Analyze UI state invisibly

### 3. Project Commands (This Repo Only)

**Category**: Project-local  
**Why**: Specific to skills development workflow  

**Path**: `~/proj/skills/.opencode/command/`

**Potential commands**:
- `/test-skill <name>` - Test a skill before deployment
- `/deploy-skill <name>` - Copy skill to dotfiles for deployment
- `/security-check <skill>` - Run security analysis on skill

## Deployment Workflow

### For Global Skills

1. **Develop in skills repo**:
   ```bash
   cd ~/proj/skills
   # Build skill: skills/<skill-name>/
   ```

2. **Test locally** (manual symlink):
   ```bash
   ln -s ~/proj/skills/skills/<skill-name> ~/.claude/skills/<skill-name>-test
   # Test with AI agent
   rm ~/.claude/skills/<skill-name>-test
   ```

3. **Copy to dotfiles**:
   ```bash
   cp -r ~/proj/skills/skills/<skill-name> ~/proj/dotfiles/claude/skills/
   cd ~/proj/dotfiles
   ```

4. **Add to Home Manager** (edit `home/claude.nix`):
   ```nix
   home.file.".claude/skills/<skill-name>" = {
     source = ../claude/skills/<skill-name>;
     recursive = true;
   };
   ```

5. **Add to OpenCode** (edit `home/opencode.nix`):
   ```nix
   home.file.".config/opencode/skills/<skill-name>" = {
     source = ../claude/skills/<skill-name>;
     recursive = true;
   };
   ```

6. **Rebuild system**:
   ```bash
   cd ~/proj/dotfiles
   sudo nixos-rebuild switch --flake .#delpad
   ```

7. **Restart agents**:
   - OpenCode: Exit and restart
   - Claude Code: Restart application

### For Project-Local Commands

1. **Create in project**:
   ```bash
   cd ~/proj/skills
   mkdir -p .opencode/command
   vim .opencode/command/test-skill.md
   ```

2. **OpenCode loads automatically** on next startup in this directory

## Version Control Strategy

### skills repo (development)
- Purpose: Development, experimentation, version history
- Branch: Feature branches for each skill
- Commits: Detailed development history
- Status: Working code, specs, analysis

### dotfiles repo (deployment)
- Purpose: System configuration, stable deployments
- Branch: main (stable only)
- Commits: "Add <skill-name> skill" (deployment markers)
- Status: Production-ready only

### Workflow:
```
skills repo (dev) --[copy]--> dotfiles repo (deploy) --[nix]--> runtime
     ↓                              ↓                              ↓
  git commit                   git commit                    ~/.claude/skills/
  version history              deployment marker             (symlink to nix store)
```

## Security Considerations

### Global Skills Deployment

**Before deploying globally, ensure**:
1. ✅ Security analysis documented
2. ✅ Risks clearly communicated
3. ✅ Audit logging implemented
4. ✅ Protection mechanisms documented
5. ✅ User can review before using

**Do NOT deploy if**:
- ❌ Security implications unclear
- ❌ No audit trail
- ❌ High risk without mitigations
- ❌ Requires per-project configuration

### niri-window-capture Specific

**Additional requirements**:
1. SECURITY.md must be in deployed skill
2. README must have security warning
3. SKILL.md must reference security docs
4. User must configure niri block-out rules BEFORE deployment

**Deployment checklist**:
- [ ] Review SECURITY.md
- [ ] Configure niri window rules:
  ```kdl
  window-rule {
      match app-id=r#"^org\.keepassxc\.KeePassXC$"#
      block-out-from "screen-capture"
  }
  ```
- [ ] Test audit logging works: `journalctl --user -t niri-capture`
- [ ] Verify blocked windows can't be captured
- [ ] Deploy to dotfiles
- [ ] Document deployment in dotfiles commit message

## OpenCode Agent Functionality

**Built-in agents:**
- **Build** - Default primary agent with all tools enabled (file ops, bash, etc.)
- **Plan** - Restricted agent for analysis/planning without making changes

**Custom agents** can be created with:
- Custom system prompts
- Model overrides (e.g., faster model for planning)
- Tool access control (per-agent tool enable/disable)

**Skills + Agents interaction:**
- Skills are global - all agents see available skills in their tool description
- Agents access skills via `skill({ name: "skill-name" })` tool
- Permission control per-agent via `opencode.json` or agent frontmatter:
  ```json
  {
    "permission": {
      "skill": {
        "skill-name": "allow",
        "pattern-*": "deny",
        "*": "ask"
      }
    }
  }
  ```

**Skill discovery paths (searched in order):**
- `.opencode/skill/<name>/SKILL.md` (project-local)
- `~/.config/opencode/skill/<name>/SKILL.md` (global)
- `.claude/skills/<name>/SKILL.md` (Claude-compatible)

**Conclusion:** Deploy skills globally to `~/.claude/skills/` (works for both Claude Code
and OpenCode). No agent-specific deployment needed - use permissions to control access.

## Current Skills Status

| Skill | Status | Security | Deploy Location | Deployed? |
|-------|--------|----------|-----------------|-----------|
| screenshot-latest | ✅ Complete | Low risk | Global | ✅ Yes |
| niri-window-capture | ✅ Complete | Medium risk | Global | ✅ Yes |
| worklog | ✅ Deployed | Low risk | Global | ✅ Yes (in dotfiles) |
| update-spec-kit | ✅ Deployed | Low risk | Global | ✅ Yes (in dotfiles) |

## Deployment Commands (Reference)

**Test locally**:
```bash
# Temporary symlink
ln -s ~/proj/skills/skills/<skill-name> ~/.claude/skills/<skill-name>-test

# Test with AI
# ...

# Remove test
rm ~/.claude/skills/<skill-name>-test
```

**Deploy to dotfiles**:
```bash
# Copy skill
cp -r ~/proj/skills/skills/<skill-name> ~/proj/dotfiles/claude/skills/

# Edit Nix configs
vim ~/proj/dotfiles/home/claude.nix
vim ~/proj/dotfiles/home/opencode.nix

# Rebuild
cd ~/proj/dotfiles
sudo nixos-rebuild switch --flake .#delpad
```

**Verify deployment**:
```bash
# Check symlinks exist
ls -la ~/.claude/skills/<skill-name>
ls -la ~/.config/opencode/skills/<skill-name>

# Check they point to Nix store
readlink ~/.claude/skills/<skill-name>/SKILL.md

# Should show: /nix/store/.../SKILL.md
```

## Next Steps

1. **Decide on deployment** for screenshot-latest and niri-window-capture
2. **Review security** for niri-window-capture before deploying
3. **Research OpenCode agents** to understand deployment implications
4. **Create deployment helper** (optional): script to copy + update Nix configs
5. **Document in dotfiles** after deployment (update skills README)

## References

- Dotfiles deployment: `~/proj/dotfiles/docs/skills-and-commands-workflow.md`
- Existing skills: `~/proj/dotfiles/claude/skills/`
- Home Manager config: `~/proj/dotfiles/home/claude.nix`, `~/proj/dotfiles/home/opencode.nix`
- Skills development: `~/proj/skills/README.md`