skills/NIX-FLAKE-USAGE.md

Using the AI Skills Nix Flake

This repository provides a Nix flake that makes it easy to deploy AI agent skills to Claude Code and OpenCode in other repositories.

Quick Start

In Your Flake-Based Repository

Add the skills flake as an input:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    ai-skills.url = "path:/home/dan/proj/skills";  # Or use git URL when published
    # Or: ai-skills.url = "github:yourusername/skills";
  };

  outputs = { self, nixpkgs, ai-skills, ... }: {
    homeConfigurations.youruser = home-manager.lib.homeManagerConfiguration {
      # ... your config ...
      
      modules = [
        ai-skills.homeManagerModules.ai-skills
        {
          services.ai-skills = {
            enable = true;
            skillsPath = "${ai-skills}/skills";  # Use flake's skills
            skills = [
              "worklog"
              "screenshot-latest"
              # "niri-window-capture"  # Optional
            ];
            enableClaudeCode = true;
            enableOpenCode = true;
            installOpencodePlugin = true;
          };
        }
      ];
    };
  };
}

Using Local Skills Path

If you've cloned the skills repo locally:

{
  services.ai-skills = {
    enable = true;
    skillsPath = /home/dan/proj/skills/skills;  # Point to local path
    skills = [ "worklog" "screenshot-latest" ];
  };
}

Using Individual Skill Packages

You can also use the packaged skills directly:

{
  inputs.ai-skills.url = "path:/home/dan/proj/skills";
  
  outputs = { ai-skills, ... }: {
    homeConfigurations.youruser = {
      home.file.".claude/skills/worklog" = {
        source = "${ai-skills.packages.x86_64-linux.worklog}";
        recursive = true;
      };
    };
  };
}

Module Options

services.ai-skills.enable

Type: bool
Default: false
Enable AI skills deployment.

services.ai-skills.skills

Type: list of strings
Default: []
List of skills to deploy.

Available skills:

• niri-window-capture - Invisibly capture window screenshots (security-sensitive)
• screenshot-latest - Find latest screenshots
• tufte-press - Generate study card JSON
• worklog - Create org-mode worklogs
• update-spec-kit - Update spec-kit ecosystem

services.ai-skills.skillsPath

Type: path
Required: yes
Path to the skills directory (e.g., ${ai-skills}/skills or /home/user/proj/skills/skills).

services.ai-skills.enableClaudeCode

Type: bool
Default: true
Deploy skills to ~/.claude/skills/.

services.ai-skills.enableOpenCode

Type: bool
Default: true
Deploy skills to ~/.config/opencode/skills/.

services.ai-skills.installOpencodePlugin

Type: bool
Default: true
Automatically install the opencode-skills npm plugin and configure it.

Complete Example

# flake.nix in your dotfiles repo
{
  description = "My system configuration";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    home-manager.url = "github:nix-community/home-manager";
    ai-skills.url = "github:yourusername/skills";
  };

  outputs = { self, nixpkgs, home-manager, ai-skills }: {
    homeConfigurations.dan = home-manager.lib.homeManagerConfiguration {
      pkgs = import nixpkgs { system = "x86_64-linux"; };
      
      modules = [
        # Import the ai-skills module
        ai-skills.homeManagerModules.ai-skills
        
        # Your home configuration
        {
          home.username = "dan";
          home.homeDirectory = "/home/dan";
          
          # Enable and configure AI skills
          services.ai-skills = {
            enable = true;
            skillsPath = "${ai-skills}/skills";
            
            skills = [
              "worklog"                # Org-mode worklogs
              "screenshot-latest"      # Find latest screenshots
              "tufte-press"           # Generate study cards
              # "niri-window-capture" # Uncomment if using niri
            ];
            
            enableClaudeCode = true;
            enableOpenCode = true;
            installOpencodePlugin = true;
          };
          
          # Optional: Configure OpenCode with additional settings
          home.file.".config/opencode/config.json".text = builtins.toJSON {
            plugin = [ "opencode-skills" ];
            # ... other OpenCode config ...
          };
        }
      ];
    };
  };
}

Development Workflow

Testing Local Changes

When developing new skills:

1. Work in the skills repo:

   cd ~/proj/skills
   # Create/edit skills in skills/your-skill/
   

2. Point your config at local path:

   services.ai-skills = {
     skillsPath = /home/dan/proj/skills/skills;  # Local path
     skills = [ "your-skill" ];
   };
   

3. Rebuild:

   home-manager switch --flake .#youruser
   # or
   sudo nixos-rebuild switch --flake .#yourhostname
   

4. Restart agents to load new skills:

   • OpenCode: Exit and restart
   • Claude Code: Restart application

Publishing Skills

When ready to share:

1. Push to git:

   cd ~/proj/skills
   git add .
   git commit -m "Add new skill"
   git push
   

2. Update flake input in consuming repo:

   inputs.ai-skills.url = "github:yourusername/skills/main";
   

3. Update flake lock:

   nix flake update ai-skills
   

Flake Outputs

The skills flake provides:

homeManagerModules.ai-skills

Home Manager module for deploying skills.

packages.<system>.<skill-name>

Individual packaged skills:

• packages.x86_64-linux.worklog
• packages.x86_64-linux.screenshot-latest
• packages.x86_64-linux.niri-window-capture
• etc.

packages.<system>.all-skills

Combined package with all skills.

lib.availableSkills

List of available skill names.

lib.getSkillPath

Helper function: getSkillPath "worklog" → ./skills/worklog

devShells.default

Development shell for working on skills.

OpenCode Plugin Installation

The module automatically:

1. Creates ~/.config/opencode/package.json with opencode-skills dependency
2. Runs bun install or npm install to fetch the plugin
3. Verifies the plugin is listed in config.json

If automatic installation fails, manually install:

cd ~/.config/opencode
bun add opencode-skills
# or
npm install opencode-skills

Then ensure config.json includes:

{
  "plugin": ["opencode-skills"]
}

Troubleshooting

Skills not appearing in OpenCode

1. Check plugin is installed:

   ls ~/.config/opencode/node_modules/opencode-skills
   

2. Verify config:

   jq '.plugin' ~/.config/opencode/config.json
   # Should output: ["opencode-skills"]
   

3. Check skills are deployed:

   ls -la ~/.config/opencode/skills/
   

4. Restart OpenCode completely (exit and reopen)

Skills not appearing in Claude Code

1. Check deployment:

   ls -la ~/.claude/skills/
   

2. Verify SKILL.md exists:

   cat ~/.claude/skills/worklog/SKILL.md
   

3. Restart Claude Code application

Module evaluation errors

If you get Nix evaluation errors:

1. Check skillsPath is valid:

   skillsPath = "${ai-skills}/skills";  # Good
   # NOT: skillsPath = ai-skills;       # Wrong
   

2. Verify flake input is correct:

   nix flake metadata path:/home/dan/proj/skills
   

Plugin installation fails

If bun install or npm install fails during activation:

1. Manually install:

   cd ~/.config/opencode
   bun add opencode-skills
   

2. Disable automatic installation:

   services.ai-skills.installOpencodePlugin = false;
   

Advanced Usage

Custom Skills Path Per Agent

{
  # Deploy different skills to different agents
  home.file.".claude/skills/worklog".source = "${ai-skills}/skills/worklog";
  home.file.".config/opencode/skills/tufte-press".source = "${ai-skills}/skills/tufte-press";
}

Conditional Deployment

{
  services.ai-skills = {
    enable = true;
    skillsPath = "${ai-skills}/skills";
    
    # Only deploy worklog on work machines
    skills = if config.networking.hostName == "work-laptop"
             then [ "worklog" "screenshot-latest" ]
             else [ "screenshot-latest" ];
  };
}

Override Skill Files

{
  services.ai-skills.enable = true;
  
  # Override specific skill with custom version
  home.file.".config/opencode/skills/worklog" = lib.mkForce {
    source = /path/to/custom/worklog;
    recursive = true;
  };
}

Example: tufte-press Repository

To use the tufte-press skill in the tufte-press repository:

# ~/proj/tufte-press/flake.nix
{
  inputs = {
    ai-skills.url = "path:/home/dan/proj/skills";
  };
  
  outputs = { ai-skills, ... }: {
    # Make tufte-press skill available in this repo
    devShells.default = pkgs.mkShell {
      shellHook = ''
        # Create project-local opencode skills
        mkdir -p .opencode/skills
        ln -sf ${ai-skills}/skills/tufte-press .opencode/skills/tufte-press
        
        echo "📚 Tufte-press skill loaded in .opencode/skills/"
      '';
    };
  };
}

Or use Home Manager to install it globally as shown above.

See Also

• skills/README.md - Overview of available skills
• skills/AGENTS.md - Development guidelines for skills
• skills/DEPLOYMENT.md - Deployment strategy details
• Home Manager Manual