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:

```nix
{
  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:

```nix
{
  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:

```nix
{
  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

```nix
# 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**:
   ```bash
   cd ~/proj/skills
   # Create/edit skills in skills/your-skill/
   ```

2. **Point your config at local path**:
   ```nix
   services.ai-skills = {
     skillsPath = /home/dan/proj/skills/skills;  # Local path
     skills = [ "your-skill" ];
   };
   ```

3. **Rebuild**:
   ```bash
   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**:
   ```bash
   cd ~/proj/skills
   git add .
   git commit -m "Add new skill"
   git push
   ```

2. **Update flake input** in consuming repo:
   ```nix
   inputs.ai-skills.url = "github:yourusername/skills/main";
   ```

3. **Update flake lock**:
   ```bash
   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:

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

Then ensure `config.json` includes:

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

## Troubleshooting

### Skills not appearing in OpenCode

1. **Check plugin is installed**:
   ```bash
   ls ~/.config/opencode/node_modules/opencode-skills
   ```

2. **Verify config**:
   ```bash
   jq '.plugin' ~/.config/opencode/config.json
   # Should output: ["opencode-skills"]
   ```

3. **Check skills are deployed**:
   ```bash
   ls -la ~/.config/opencode/skills/
   ```

4. **Restart OpenCode** completely (exit and reopen)

### Skills not appearing in Claude Code

1. **Check deployment**:
   ```bash
   ls -la ~/.claude/skills/
   ```

2. **Verify SKILL.md exists**:
   ```bash
   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:
   ```nix
   skillsPath = "${ai-skills}/skills";  # Good
   # NOT: skillsPath = ai-skills;       # Wrong
   ```

2. **Verify flake input** is correct:
   ```bash
   nix flake metadata path:/home/dan/proj/skills
   ```

### Plugin installation fails

If `bun install` or `npm install` fails during activation:

1. **Manually install**:
   ```bash
   cd ~/.config/opencode
   bun add opencode-skills
   ```

2. **Disable automatic installation**:
   ```nix
   services.ai-skills.installOpencodePlugin = false;
   ```

## Advanced Usage

### Custom Skills Path Per Agent

```nix
{
  # 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

```nix
{
  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

```nix
{
  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:

```nix
# ~/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](README.md) - Overview of available skills
- [skills/AGENTS.md](AGENTS.md) - Development guidelines for skills
- [skills/DEPLOYMENT.md](DEPLOYMENT.md) - Deployment strategy details
- [Home Manager Manual](https://nix-community.github.io/home-manager/)