Skillzwave

Advanced Topics

This guide covers advanced Skilz topics including installation modes, manifest files, project vs user installation, and advanced configuration scenarios.

Remember: Install Skilz first with pip install skilz before exploring advanced features.

Diagram showing Skilz CLI data flow from CLI Layer through Commands Layer to Core Layer with registry, agents, and git operations

Installation Modes

Skilz supports two installation modes: copy and symlink.

Copy Mode (Default)

Copy mode creates a complete copy of skill files in the target directory. This is the default and most reliable mode. 

{
  "agents": {
    "my_agent": {
      "default_mode": "copy"
    }
  }
}

Advantages:

  • Works in all environments (including sandboxed setups)
  • Skills are self-contained and portable
  • No dependency on source location

Disadvantages:

  • Uses more disk space (duplicate files)
  • Manual update required when source changes

Symlink Mode

Symlink mode creates symbolic links to the cached skill repository. Changes to the source are immediately reflected. 

{
  "agents": {
    "my_agent": {
      "default_mode": "symlink"
    }
  }
}

Advantages:

  • Saves disk space (single copy)
  • Updates automatically when cache is refreshed
  • Faster installation

Disadvantages:

  • May not work in sandboxed environments
  • Depends on cache directory integrity
  • Some agents don't follow symlinks

Note: Some agents (like certain IDE plugins) may not correctly follow symlinks. If skills don't load properly, switch to copy mode.

User vs Project Installation

User-Level Installation (Default)

User-level skills are installed in your home directory and available to all projects.

pip install skilz
# Install to ~/.claude/skills/
skilz install anthropics_skills/theme-factory

Use Cases:

  • General-purpose skills you use across projects
  • Personal productivity skills
  • Standard tooling and workflows

Project-Level Installation

Project-level skills are installed in the current project directory and committed with your code.

pip install skilz
# Install to ./.claude/skills/
skilz install anthropics_skills/theme-factory --project

Use Cases:

  • Project-specific skills (e.g., framework-specific)
  • Team-shared skills (committed to repo)
  • Reproducible environments
  • Different skill versions per project

Installation Priority

When both user and project skills exist with the same name:

  1. Project-level skills take precedence
  2. User-level skills are fallback

Manifest Files

Each skill has a manifest file (default: SKILL.md) that defines the skill's metadata and content.

Manifest File Format

# SKILL.md

---
name: My Skill
description: A brief description of the skill
version: 1.0.0
author: Your Name
triggers:
  - "when user asks about X"
  - "when working with Y"
---

# My Skill

Instructions and content for the AI agent...

## Usage

Examples of how to use this skill...

## References

Additional resources and documentation...

Multi-Agent Workflows

Install the same skill to multiple agents simultaneously:

pip install skilz
# Install to multiple agents
skilz install anthropics_skills/theme-factory --agent claude
skilz install anthropics_skills/theme-factory --agent opencode
skilz install anthropics_skills/theme-factory --agent cursor

Setting Different Defaults per Project

Use project-level config to set different defaults for different projects: 

// .config/skilz/config.json (in project root)
{
  "default_agent": "opencode"
}

Skill Development

Local Skill Testing

Test a skill locally before publishing:

# Create skill directory
mkdir -p ~/.claude/skills/my-test-skill

# Create manifest
cat > ~/.claude/skills/my-test-skill/SKILL.md << 'EOF'
---
name: My Test Skill
description: A test skill
---

# My Test Skill

This is a test skill for development.
EOF

# Skill is now available in Claude

Skill Directory Structure

Skills can include additional files beyond the manifest:

my-skill/
├── SKILL.md           # Main manifest (required)
├── prompts/           # Additional prompt templates
│   ├── template1.md
│   └── template2.md
├── examples/          # Example files
│   └── example.py
└── resources/         # Additional resources
    └── schema.json

Environment Variables

Override configuration with environment variables:

Variable Description Example
AGENT_DEFAULT Override default agent opencode or claude
CLAUDE_CODE_HOME Override Claude Code home directory /custom/path/.claude
OPEN_CODE_HOME Override OpenCode home directory /custom/path/opencode
pip install skilz
# Use environment variables
export AGENT_DEFAULT=opencode
export CLAUDE_CODE_HOME=~/.claude
export OPEN_CODE_HOME=~/.config/opencode

skilz install anthropics_skills/theme-factory

CI/CD Integration

Install skills in CI/CD pipelines:

# .github/workflows/setup.yml
name: Setup AI Skills
on: [push]

jobs:
  setup:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Skilz
        run: pip install skilz

      - name: Install project skills
        run: |
          skilz install anthropics_skills/code-review --project
          skilz install anthropics_skills/testing --project

      - name: Verify installations
        run: skilz list --project

See Also