dan/skills
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
skills/docs/worklogs/2025-11-09-nix-flake-module-development-opencode-skills-integration.org
dan 5fea49b7c0 feat(tufte-press): evolve skill to complete workflow with JSON generation and build automation 
- Transform tufte-press from reference guide to conversation-aware generator
- Add JSON generation from conversation context following strict schema
- Create build automation scripts with Nix environment handling
- Integrate CUPS printing with duplex support
- Add comprehensive workflow documentation

Scripts added:
- skills/tufte-press/scripts/generate-and-build.sh (242 lines)
- skills/tufte-press/scripts/build-card.sh (23 lines)

Documentation:
- Updated SKILL.md with complete workflow instructions (370 lines)
- Updated README.md with usage examples (340 lines)
- Created SKILL-DEVELOPMENT-STRATEGY-tufte-press.md (450 lines)
- Added worklog: 2025-11-10-tufte-press-skill-evolution.org

Features:
- Agent generates valid JSON from conversation
- Schema validation before build (catches errors early)
- Automatic Nix shell entry for dependencies
- PDF build via tufte-press toolchain
- Optional print with duplex support
- Self-contained margin notes enforced
- Complete end-to-end testing

Workflow: Conversation → JSON → Validate → Build → Print

Related: niri-window-capture, screenshot-latest, worklog skills
2025-11-10 15:03:44 -08:00

11 KiB
Raw Blame History

Nix Flake Module Development and OpenCode Skills Integration

Session Summary

Date: 2025-11-09 (Initial comprehensive development session)

Focus Area: Nix flake infrastructure for declarative AI skills deployment

Accomplishments

  • Created complete AGENTS.md with development guidelines for skills repository
  • Enhanced AGENTS.md with comprehensive deployment strategy (global/local/commands)
  • Developed lightweight tufte-press skill (JSON prompt provider, no build dependencies)
  • Created comprehensive user stories for orch multi-model chat feature (492 lines)
  • Wrote implementation quickstart guide for orch team (200 lines)
  • Diagnosed opencode-skills plugin installation issue (not installed despite config)
  • Designed complete Nix flake for skills repository with Home Manager module
  • Implemented ai-skills.nix module with automatic opencode-skills plugin installation
  • Created comprehensive NIX-FLAKE-USAGE.md documentation (350+ lines)
  • Validated flake structure with `nix flake check` (passing)
  • Established model for other repos to consume skills declaratively

Key Decisions

Decision 1: Tufte-Press Skill as Prompt Provider Only

  • Context: Initially planned to have skill run full PDF build pipeline

  • Options considered:

    1. Full integration - run Nix build, Python conversion, Tectonic compilation
    2. Prompt provider - just give LLM authoring prompt and JSON schema
  • Rationale: Dependency-free approach is more portable and separates concerns
  • Impact: Skill works anywhere without Nix, users bring prompts to any LLM

Decision 2: Nix Flake Architecture for Skills

  • Context: Needed reusable pattern for deploying skills across multiple repos

  • Options considered:

    1. Manual copying via scripts
    2. Flake with packages only
    3. Full Home Manager module with automatic plugin installation
  • Rationale: Declarative approach integrates with existing Nix infrastructure
  • Impact: Skills become first-class Nix packages, enabling version control and atomic updates

Decision 3: Automatic opencode-skills Plugin Installation

  • Context: Plugin exists on npm but wasn't installed, breaking skill loading

  • Options considered:

    1. Manual installation instructions only
    2. Home Manager activation script with npm/bun install
    3. Nix package wrapper for the plugin
  • Rationale: Activation script provides best UX while maintaining flexibility
  • Impact: Users get working plugin automatically when using the module

Decision 4: Separate User Stories for Orch Implementation Team

  • Context: Multi-model chat feature needed clear requirements

  • Options considered:

    1. Brief bullet points in existing spec
    2. Complete user stories with acceptance criteria
    3. Both user stories + technical quickstart
  • Rationale: Implementation team benefits from both high-level user stories and technical guidance
  • Impact: Created 002-multi-model-chat-user-stories.md (492 lines) + QUICKSTART (200 lines)

Problems & Solutions

Problem Solution Learning
OpenCode not seeing niri-window-capture skill despite deployment Discovered opencode-skills npm plugin not installed (config referenced it but node_modules didn't have it) Config can reference plugins that don't exist - OpenCode silently ignores them
Duplicate `packages` attribute in flake.nix Refactored to single packages attribute using let binding with merged attrsets Nix attribute sets can't have duplicate keys, use // merge or nested let
Flake trying to access skills not yet in git Added filter to check pathExists before packaging Nix flakes only see git-tracked files, need to handle missing paths gracefully
Skills module needed to install npm package Implemented home.activation script with bun/npm fallback Home Manager activation scripts run after file deployment, can install packages

Technical Details

Code Changes

  • Total files created: 8 major files

  • Key files created:

    • `flake.nix` - Main flake with packages, devShell, and module exports
    • `modules/ai-skills.nix` - Home Manager module (~180 lines)
    • `NIX-FLAKE-USAGE.md` - Complete usage documentation (~350 lines)
    • `NIX-FLAKE-README.md` - Quick reference summary
    • `skills/tufte-press/SKILL.md` - Tufte press skill (162 lines)
    • `skills/tufte-press/README.md` - User documentation (217 lines)
    • `specs/002-multi-model-chat-user-stories.md` - Orch user stories (492 lines)
    • `specs/002-multi-model-chat-QUICKSTART.md` - Implementation guide (200 lines)

  • Files modified:

    • `AGENTS.md` - Enhanced with deployment strategies
    • `DEPLOYMENT.md` - Streamlined and updated (668 → ~300 lines)

Commands Used

```bash

nix flake lock

nix flake check

nix flake show

nix build .#worklog

npm search opencode-skills ```

Architecture Notes

Flake Structure

  • Uses flake-utils for multi-system support
  • Exports both homeManagerModules and nixosModules (compatibility)
  • Individual skill packages + combined all-skills package
  • Library helpers (getSkillPath, getAllSkillPaths, availableSkills)

Home Manager Module Design

  • service.ai-skills namespace for clarity
  • Per-agent control (enableClaudeCode, enableOpenCode)
  • Automatic plugin installation via activation scripts
  • Checks for both bun and npm package managers
  • Validates plugin is in config.json

Skills Repository Pattern

  • Development-only repo (skills/ not deployed here)
  • Flake provides packaging and deployment mechanism
  • Other repos consume via flake inputs
  • Skills can be used globally or project-locally

Process and Workflow

What Worked Well

  • Iterative approach: AGENTS.md → tufte-press skill → orch user stories → Nix flake
  • Reading existing patterns (tufte-press flake.nix, dotfiles opencode.nix)
  • Testing with `nix flake check` after each major change
  • Creating both comprehensive docs (NIX-FLAKE-USAGE) and quick ref (NIX-FLAKE-README)
  • Using todo tracking to maintain progress through multi-step tasks

What Was Challenging

  • Understanding opencode-skills plugin mechanism (not in official docs)
  • Debugging why skills weren't loading (plugin vs tool vs command confusion)
  • Nix attribute set syntax for merging individual + combined packages
  • Balancing between complete automation and user control in module

Learning and Insights

Technical Insights

OpenCode Plugin System

  • Official docs show custom tools (.opencode/tool/*.ts files)
  • Separate plugin system exists: opencode-skills (npm package by malhashemi)
  • Plugin scans ~/.config/opencode/skills/ for SKILL.md files
  • Skills are NOT the same as Tools or Commands in OpenCode
  • Config can reference plugins that aren't installed (silent failure)

Nix Flake Best Practices

  • Filter inputs early to avoid evaluation errors on missing paths
  • Use // merge operator for combining attribute sets
  • Export modules as both homeManagerModules and nixosModules
  • lib output useful for helpers and constants
  • Home Manager activation scripts powerful for post-deployment setup

Tufte-Press Architecture

  • Separation of concerns: JSON authoring vs PDF building
  • LLM authoring prompt is ~180 lines with complete schema spec
  • Skills can be references/templates instead of executables
  • Dependency-free skills more portable across environments

Process Insights

  • User stories benefit from both acceptance criteria AND implementation pseudocode
  • Two-document approach (comprehensive + quickstart) serves different audiences
  • Flake-based deployment enables atomic updates and rollbacks
  • Testing early with `nix flake check` catches errors before integration

Architectural Insights

  • Skills repository can serve as Nix package source for multiple consumers
  • Home Manager modules enable declarative skill deployment
  • Project-local vs global skills distinction maps well to Nix patterns
  • npm/bun plugin installation can be automated via activation scripts

Context for Future Work

Open Questions

  • Should opencode-skills plugin be packaged as Nix derivation for reproducibility?
  • How to handle skill version conflicts across multiple repos?
  • Should skills have version numbers independent of repo tags?
  • What's the best way to test Home Manager modules before deployment?
  • Should the flake provide a "recommended skills" bundle?

Next Steps

  • Test ai-skills module in dotfiles repository
  • Verify opencode-skills plugin actually installs via activation script
  • Add remaining skills (niri-window-capture, screenshot-latest) to git
  • Publish skills repo to GitHub for remote flake access
  • Create example integration in tufte-press repository
  • Document orch team handoff with user stories
  • Consider creating skill templates for common patterns

Related Work

  • ~/proj/dotfiles - Target for testing the module integration
  • ~/proj/tufte-press - Could use tufte-press skill locally
  • ~/proj/orch - Awaiting user stories implementation
  • Niri window capture - Related skill development

Raw Notes

Terminology Clarifications

  • Nix flake: Repository with flake.nix providing packages/modules
  • Home Manager module: Nix module that configures user environment
  • OpenCode Skills: SKILL.md files loaded by opencode-skills plugin
  • OpenCode Tools: TypeScript files in .opencode/tool/ (different system)
  • OpenCode Commands: Markdown files in .opencode/command/ (slash commands)
  • OpenCode Agents: Different modes (Build/Plan), not related to skills

Discovery Process

  1. Started with improving AGENTS.md
  2. Discovered tufte-press needs skill, created lightweight version
  3. User asked about orch multi-model plans, wrote comprehensive user stories
  4. Discovered OpenCode skills not loading, diagnosed plugin issue
  5. Realized need for declarative deployment, created Nix flake
  6. Wrote comprehensive docs so pattern is reusable

Resources Consulted

  • https://opencode.ai/docs/custom-tools - OpenCode tools documentation
  • ~/proj/dotfiles/docs/skills-and-commands-workflow.md - Existing workflow doc
  • ~/proj/tufte-press/flake.nix - Pattern for flake structure
  • npm search results for opencode-skills plugin

Key Files for Reference

  • Tufte-press skill: skills/tufte-press/SKILL.md, README.md
  • Nix flake: flake.nix, modules/ai-skills.nix
  • Orch user stories: specs/002-multi-model-chat-user-stories.md
  • Usage docs: NIX-FLAKE-USAGE.md, NIX-FLAKE-README.md

Session Metrics

  • Commits made: 0 (staged but not committed)
  • Files touched: 15+ (8 new, 7 modified)
  • Lines added: ~2500 (major documentation and code session)
  • Skills created: 1 (tufte-press)
  • Modules created: 1 (ai-skills.nix)
  • User stories written: 6 (orch multi-model feature)
  • Documentation pages: 5 (README, usage guide, quickstart, etc.)