skills/DEPLOYMENT-QUESTIONS.md

Deployment Architecture Questions

Current Understanding

Development flow:

~/proj/skills/            → Develop & test skills
     ↓ (manual copy)
~/proj/dotfiles/claude/skills/  → Source of truth for deployment
     ↓ (nix home-manager)
~/.claude/skills/         → Runtime (Claude Code)
~/.config/opencode/skills/      → Runtime (OpenCode)

Project-local flow:

<project>/.opencode/command/  → Project-specific commands
     ↓ (auto-loaded by OpenCode)
Available only in that project

Questions to Answer

1. Repository Relationship

Current model: Manual copy from skills repo to dotfiles

Questions:

• Should ~/proj/skills be a submodule of dotfiles?
• Should dotfiles symlink to skills repo instead of copying?
• Is the manual copy step intentional (review gate)?
• How do we keep them in sync?

Options:

A) Manual copy (current)
   - Pro: Review gate, dotfiles is source of truth
   - Con: Easy to get out of sync

B) Git submodule
   - dotfiles includes skills as submodule
   - Nix deploys from submodule
   - Pro: Version controlled, atomic
   - Con: Submodule complexity

C) Symlink in Nix
   - home.file.".claude/skills/foo".source = ~/proj/skills/skills/foo
   - Pro: No copy, always in sync
   - Con: Development changes immediately live

D) Separate repos, manual sync
   - Keep current model
   - Add deployment script to help
   - Pro: Clear separation, review step
   - Con: Manual process

My take: Option D feels right. Skills repo is for development/experimentation, dotfiles is for stable deployment. The copy step is a deployment decision point.

2. OpenCode Agents

What we know:

• OpenCode has "agents" concept (keybind: <leader>a for agent list)
• Commands can specify agent via frontmatter: agent: plan
• Skills plugin loaded via "plugin": ["opencode-skills"]

Questions:

• What agents exist? (plan, code, debug, etc.?)
• Do agents have different capabilities?
• Should skills target specific agents?
• Do skills work across all agents by default?

Need to research:

• OpenCode docs on agents
• Check .opencode/command/ for agent examples
• Test if skills work with different agents

Hypothesis: Skills are agent-agnostic, agents are just different personalities/modes. Commands can route to specific agents, but skills work with whoever invokes them.

3. Global vs Project-Local Skills

Global skills (~/.config/opencode/skills/):

• Available in all projects
• Examples: worklog, niri-window-capture, screenshot-latest
• Deployed via Nix from dotfiles

Project-local (.opencode/command/):

• Available only in that project
• Examples: /test (nix flake check), /rebuild (nixos-rebuild)
• Loaded directly from project directory

Questions:

• Can .opencode/ contain skills/ not just command/?
• What's the difference between a skill and a command?
• Should project-local be commands or skills?

Current understanding:

• Commands = User-invoked slash commands (/test)
• Skills = AI-invoked based on intent (natural language)
• Project-local are commands because they're explicit actions
• Skills are almost always global (AI decides when to use)

Exception: Could have project-specific skills

• Example: "Django migration skill" only for Django projects
• Pattern: .opencode/skills/django-migrations/SKILL.md
• Loaded when working in that project

4. Security-Sensitive Skills

niri-window-capture is unique:

• High security risk
• Requires user configuration before deployment
• Needs audit logging
• Should users be able to enable/disable at runtime?

Questions:

• Should security-sensitive skills be opt-in after deployment?
• How to prevent accidental invocation?
• Should there be a "skills.disabled" list?
• How to make security review part of deployment workflow?

Options:

A) Deploy but document requirements
   - Skills always available after deployment
   - User must review SECURITY.md
   - User configures niri block-out rules
   - Trust deployment decision

B) Deploy with enable flag
   - Skill deployed but inactive
   - User runs: enable-skill niri-window-capture
   - Requires acknowledgment of security docs
   - More complex

C) Don't deploy by default
   - Security-sensitive skills opt-in only
   - User manually deploys after review
   - Separate deployment process

My take: Option A. If user deploys to dotfiles and rebuilds, they've made the decision. Security docs in skill are sufficient warning.

5. Deployment Helper Tools

Current: Manual process

1. Copy skill to dotfiles
2. Edit claude.nix
3. Edit opencode.nix
4. Rebuild
5. Restart agents

Questions:

• Should we automate this?
• Should deployment script update Nix configs?
• Should there be validation before deployment?
• Should there be rollback capability?

Created: bin/deploy-skill.sh (copies + shows instructions)

Could add:

• Automatic Nix config updates
• Validation (check SKILL.md exists, security docs present)
• Test suite (does skill work before deploying?)
• Rollback (remove from dotfiles + Nix configs)

Decisions Needed

Immediate (for current skills)

1. Deploy screenshot-latest?

   • Low risk, useful globally
   • Decision: Yes, deploy

2. Deploy niri-window-capture?

   • High risk, requires review
   • Decision: After user reviews SECURITY.md

3. Update DEPLOYMENT.md with final model?

   • Document chosen approach
   • Decision: Pending answers above

Short-term (for future skills)

4. Research OpenCode agents

   • Understand agent model
   • Document in DEPLOYMENT.md
   • Decision: Research needed

5. Define project-local skill pattern

   • When to use vs global
   • How to structure
   • Decision: Pending research

6. Enhance deployment tooling

   • Auto-update Nix configs?
   • Validation checks?
   • Decision: After more experience

Proposed Deployment Model (Draft)

For Global Skills

Development:

1. Develop in ~/proj/skills/skills/<name>/
2. Test locally with symlink
3. Iterate until stable

Deployment:

1. Run: ./bin/deploy-skill.sh <name>
2. Review security docs if present
3. Edit ~/proj/dotfiles/home/claude.nix (add skill)
4. Edit ~/proj/dotfiles/home/opencode.nix (add skill)
5. Commit to dotfiles: git add && git commit -m "Add <name> skill"
6. Rebuild: sudo nixos-rebuild switch --flake .#delpad
7. Restart agents

Maintenance:

• Update in skills repo
• Copy to dotfiles when stable
• Rebuild to deploy updates

For Project-Local Commands

Development:

1. Create in <project>/.opencode/command/<name>.md
2. Restart OpenCode to load
3. Test in that project

No deployment needed - auto-loaded from project directory

For Project-Local Skills (if needed)

Pattern (hypothetical):

1. Create in <project>/.opencode/skills/<name>/SKILL.md
2. OpenCode loads from project directory?
3. Available only when working in that project

Need to verify: Does OpenCode support .opencode/skills/?

Next Steps

1. Research OpenCode agents documentation
2. Test project-local skills pattern
3. Make deployment decision for screenshot-latest
4. Review SECURITY.md for niri-window-capture
5. Update DEPLOYMENT.md with final model
6. Document in dotfiles after deployment

References

• Dotfiles workflow: ~/proj/dotfiles/docs/skills-and-commands-workflow.md
• OpenCode docs: https://opencode.ai/docs
• Current deployment: DEPLOYMENT.md
• Security analysis: skills/niri-window-capture/SECURITY.md