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:

   cd ~/proj/skills
   # Build skill: skills/<skill-name>/
   

2. Test locally (manual symlink):

   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:

   cp -r ~/proj/skills/skills/<skill-name> ~/proj/dotfiles/claude/skills/
   cd ~/proj/dotfiles
   

4. Add to Home Manager (edit home/claude.nix):

   home.file.".claude/skills/<skill-name>" = {
     source = ../claude/skills/<skill-name>;
     recursive = true;
   };
   

5. Add to OpenCode (edit home/opencode.nix):

   home.file.".config/opencode/skills/<skill-name>" = {
     source = ../claude/skills/<skill-name>;
     recursive = true;
   };
   

6. Rebuild system:

   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:

   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" (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:

  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

From opencode.ai docs (need to research more):

• OpenCode has "agents" concept separate from skills
• Agents appear to be different AI personalities/modes
• Skills work with all agents
• Commands can specify which agent via frontmatter

TODO: Research OpenCode agents to understand:

• What are the available agents?
• How do skills interact with agents?
• Should skills be agent-specific?
• Do we need agent-specific deployment?

For now: Deploy skills globally, they work with all agents.

Current Skills Status

Skill	Status	Security	Deploy Location	Deployed?
screenshot-latest	✅ Complete	Low risk	Global	⏸️ No
niri-window-capture	✅ Complete	HIGH RISK	Global	⏸️ No (awaiting security review)
worklog	✅ Deployed	Low risk	Global	✅ Yes (in dotfiles)
update-spec-kit	✅ Deployed	Low risk	Global	✅ Yes (in dotfiles)

Deployment Commands (Reference)

Test locally:

# 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:

# 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:

# 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