How to Install the Caveman Skill: Local and Global Setup Guide

Run caveman skills install caveman to install the Caveman skill in your current repository, or add the --user flag to install it globally in ~/.claude/skills for machine-wide access.

The Caveman skill is a built-in compression utility for the JuliusBrussee/caveman repository that reduces token counts by rendering model responses as compressed images. According to the source code in skills/caveman/SKILL.md, this skill activates when users trigger phrases like "talk like caveman" or invoke the /caveman command. Whether you need project-specific behavior or system-wide availability, you can deploy this skill using the Caveman CLI with specific flags that control installation scope and rendering behavior.

Installation Commands

Repository-Scoped Installation (Default)

By default, the Caveman CLI installs skills into the current repository's .claude/skills directory. This keeps the skill localized to your specific project context.

caveman skills install caveman

This command copies the skill definition from skills/caveman/SKILL.md in the JuliusBrussee/caveman repository into your local .claude/skills folder.

Global User Installation

To install the Caveman skill across all repositories on your machine, append the --user flag. This deploys the skill to your home directory rather than the current project.

caveman skills install caveman --user

The CLI places the files in ~/.claude/skills according to the implementation logic documented in packages/cli/README.md.

Agent-Specific Installation

Target specific AI agents by using the --agent flag followed by the agent identifier. This restricts the skill to particular models (e.g., Codex) rather than making it universally available.

caveman skills install caveman --agent codex

Disabling Auto-Pixel Conversion

The Caveman skill is pixel-enabled by default, meaning it automatically compresses response bodies into images when doing so provides net token savings. To install without this compression behavior:

caveman skills install caveman --no-pixel

Source Files and Installation Logic

Skill Definition and Registry

The core behavior is defined in skills/caveman/SKILL.md within the JuliusBrussee/caveman repository. This markdown file contains the trigger conditions, parameter definitions, and response handlers.

The central registry that maps skill IDs to source paths is stored in skills/registry.json. When you run the install command, the CLI queries this registry to locate the caveman skill ID and resolve the correct source files.

CLI Implementation Details

The installation logic is implemented in the CLI source under src/cli, with command documentation available in packages/cli/README.md. The tool handles path resolution automatically, determining whether to copy files to the local repository scope (./.claude/skills) or the global user scope (~/.claude/skills) based on your flags.

Update Behavior

The Caveman CLI automatically detects existing installations. If you run the install command on a system that already contains the skill, the CLI updates the files in place rather than creating duplicates or failing with an error.

Verification Steps

After installation, verify that the skill is properly registered by listing all installed skills:

caveman skills list

You should see caveman listed among the active skills. Once verified, the skill becomes active immediately and will compress responses or activate when the model encounters the specific trigger phrases defined in SKILL.md.

Summary

• Run caveman skills install caveman for local repository installation, or add --user for global deployment to ~/.claude/skills
• The skill definition originates from skills/caveman/SKILL.md and is tracked via skills/registry.json in the JuliusBrussee/caveman repository
• Use --no-pixel to disable automatic image compression of responses
• The CLI automatically updates existing installations in place when re-run
• Verify successful installation using caveman skills list before attempting to trigger the skill

Frequently Asked Questions

Where does the Caveman skill get installed by default?

By default, the CLI installs the skill into the current repository's .claude/skills directory, creating a localized instance that only affects the current project. When using the --user flag, the installation targets ~/.claude/skills for machine-wide availability across all repositories.

What is the pixel-enabled feature and how do I disable it?

The pixel-enabled feature automatically converts the skill's text responses into compressed images when this conversion reduces the total token count. To disable this behavior during installation, append the --no-pixel flag to your command, which stores the skill without the automatic image rendering logic.

How do I update an existing Caveman skill installation?

The Caveman CLI automatically detects when the skill is already present in the target directory and performs an in-place update. Simply re-run the installation command with your preferred flags (e.g., caveman skills install caveman --user) to refresh the skill files from the source repository.

Can I install the Caveman skill for only specific AI agents?

Yes, use the --agent flag followed by the specific agent name (such as codex) to restrict the skill's availability. This creates an isolated installation that only activates when using that particular AI agent, rather than applying globally or to the entire repository.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}