dot-agent-kit 0.1.29

Kit management for Claude Code

dot-agent-kit

Kit management system for Claude Code.

Package vs CLI

• Package name: dot-agent-kit (what you install)
• CLI command: dot-agent (what you run)

This naming follows the convention where the package name describes what it provides (a kit management system), while the CLI command is concise for frequent use.

Installation

uv pip install dot-agent-kit

Or with pip:

pip install dot-agent-kit

Usage

After installation, use the dot-agent command:

# Initialize configuration
dot-agent init

# View available commands
dot-agent --help

# Manage kits
dot-agent kit install <kit-name>
dot-agent kit list

Creating Kits

Understanding Command Types

There are two distinct types of commands in the kit system:

1. Slash commands - Markdown files (.md) invoked in Claude Code with /command-name

   • Defined in .claude/commands/ directory (after installation)
   • Stored in commands/ directory within the kit
   • Listed in kit.yaml under artifacts.command
   • Expand to prompts when invoked
   • Example: /gt:submit-branch

2. Kit cli commands - Python executables (.py) invoked via CLI with erk kit exec kit-id command-name

   • Stored in kit_cli_commands/ directory within the kit
   • Listed in kit.yaml under kit_cli_commands
   • Defined in kit directories as Python scripts
   • Listed in kit.yaml under kit_cli_commands
   • Execute Python code directly
   • Example: erk kit exec gt submit-branch

This distinction is important when creating kits and defining their capabilities in kit.yaml.

Kit Structure

A kit is a collection of Claude Code artifacts (agents, skills, slash commands) distributed as a package. Each kit requires:

1. kit.yaml - Manifest file with kit metadata and artifact paths
2. Artifacts - The actual agent, skill, and slash command files

Namespace Pattern (Required)

All bundled kits must follow the namespace pattern:

{artifact_type}s/{kit_name}/...

This organizational pattern:

• Prevents naming conflicts when multiple kits are installed
• Makes it clear which kit an artifact belongs to
• Enables clean uninstallation of kit artifacts
• Keeps the .claude/ directory organized

Example structure:

my-kit/
├── kit.yaml
├── agents/
│   └── my-kit/
│       └── my-agent.md
└── skills/
    └── my-kit/
        ├── tool-a/
        │   └── SKILL.md
        └── tool-b/
            └── SKILL.md

Example kit.yaml:

name: my-kit
version: 1.0.0
description: My awesome Claude Code kit
artifacts:
  agent:
    - agents/my-kit/my-agent.md
  skill:
    - skills/my-kit/tool-a/SKILL.md
    - skills/my-kit/tool-b/SKILL.md
  command:
    - commands/my-kit/my-slash-command.md
kit_cli_commands:
  - name: my-cli-command
    path: kit_cli_commands/my-kit/my_cli_command.py
    description: Execute Python CLI command

Invocation Names vs File Paths

Important: Claude Code discovers artifacts by their filename/directory name, not the full path:

• Agents: Discovered by filename (e.g., agents/my-kit/helper.md → invoked as "helper")
• Skills: Discovered by directory name (e.g., skills/my-kit/pytest/SKILL.md → invoked as "pytest")
• Slash commands: Discovered by filename (e.g., commands/my-kit/build.md → invoked as "/build")
• Kit cli commands: Invoked via CLI (e.g., erk kit exec my-kit build for command defined in kit_cli_commands)

The namespace directory (my-kit/) is organizational only - it doesn't become part of the invocation name.

Hyphenated naming convention (kebab-case): ALL artifacts MUST use hyphenated naming (kebab-case), NOT underscores. Use hyphens to combine words (e.g., skills/devrun-make/SKILL.md → "devrun-make", commands/my-command.md → "/my-command"). This is the standard for ALL Claude artifacts - bundled kits and project-local alike.

DO NOT use underscores (_) in artifact names. Use hyphens (-) instead:

• ✅ CORRECT: my-command.md, api-client/SKILL.md, test-runner.md
• ❌ WRONG: my_command.md, api_client/SKILL.md, test_runner.md

Exception: Python scripts within artifacts may use snake_case (they're code, not artifacts).

Supporting Documentation

Supporting documentation for kits (examples, tutorials, references, etc.) should be stored in:

.claude/docs/{kit_id}/

This organizational pattern:

• Keeps non-executable documentation separate from the actual artifacts
• Prevents documentation files from appearing as commands
• Provides a clear location for kit-specific documentation
• Maintains organization when multiple kits are installed

Example structure:

.claude/
├── commands/
│   └── my-kit/
│       └── my-command.md      # Executable command
├── docs/
│   └── my-kit/
│       ├── EXAMPLES.md         # Usage examples
│       ├── TUTORIAL.md         # Tutorial guide
│       └── REFERENCE.md        # API reference
└── skills/
    └── my-kit/
        └── SKILL.md            # Executable skill

Important: Only place actual executable artifacts (commands, skills, agents) in their respective directories. All supporting documentation, examples, tutorials, and non-executable markdown files should go in .claude/docs/{kit_id}/.

Namespace Standards for Kit Types

Bundled kits (distributed with packages): Should follow hyphenated naming convention (e.g., skills/kit-name-tool/) to avoid naming conflicts and maintain clear organization.

Project-local artifacts (in .claude/ not from kits): MUST also use kebab-case naming. The hyphenated naming standard applies to ALL artifacts, regardless of whether they're bundled or project-local.

Adopting Hyphenated Naming

To align with the standard hyphenated naming convention:

1. Flatten directory structure with hyphenated names:

   # Example: Convert skills/devrun/make/ to skills/devrun-make/
   mv skills/devrun/make skills/devrun-make
   mv skills/devrun/pytest skills/devrun-pytest
   

2. Update kit.yaml artifact paths:

   artifacts:
     skill:
       - skills/devrun-make/SKILL.md # Was: skills/devrun/make/SKILL.md
       - skills/devrun-pytest/SKILL.md # Was: skills/devrun/pytest/SKILL.md
   

3. Test installation to verify paths are correct

Adding Bundled Kits

To add a new bundled kit to the dot-agent-kit registry:

1. Create the kit structure in src/dot_agent_kit/data/kits/{kit-name}/:

   kits/
   └── my-kit/
       ├── kit.yaml
       ├── kit_cli_commands/
       │   └── my-kit/
       │       └── my_cli_command.py
       ├── commands/
       │   └── my-kit/
       │       └── my-slash-command.md
       ├── agents/
       │   └── my-kit/
       │       └── my-agent.md
       └── skills/
           └── my-kit/
               └── SKILL.md
   

2. Define kit.yaml with metadata and artifact paths:

   name: my-kit
   version: 0.1.0
   description: Brief description of what the kit provides
   license: MIT
   artifacts:
     agent:
       - agents/my-kit/my-agent.md
     skill:
       - skills/my-kit/SKILL.md
     command:
       - commands/my-kit/my-slash-command.md # Slash command (markdown)
   kit_cli_commands: # Kit CLI commands (Python executables)
     - name: my-cli-command
       path: kit_cli_commands/my-kit/my_cli_command.py
       description: Execute Python CLI command
   

3. Register the kit in src/dot_agent_kit/data/registry.yaml:

   - kit_id: my-kit
     name: My Kit
     description: Brief description of what the kit provides
     source: bundled:my-kit
   

4. Test the kit is discoverable:

   dot-agent kit search
   

5. Install and verify the kit:

   # Install using the bundled: prefix
   dot-agent kit install bundled:my-kit
   
   # Verify installation
   dot-agent check
   

Note: The source: field in registry.yaml determines the prefix users must use:

• source: bundled:my-kit → install with dot-agent kit install bundled:my-kit
• source: package:my-kit → install with dot-agent kit install package:my-kit

The kit will now appear in the available kits list and can be installed by users.

Managing Kit Artifacts

Once a kit is created, you can add or remove artifacts (agents, skills, commands, docs) to extend or modify its functionality.

Adding Artifacts to an Existing Kit

To add a new artifact to a bundled kit:

1. Create the artifact file in the appropriate namespace directory:

   kits/{kit-name}/
   ├── agents/{kit-name}/        # For agents
   ├── skills/{kit-name}/         # For skills
   ├── commands/{kit-name}/       # For slash commands
   ├── docs/{kit-name}/           # For documentation
   └── kit_cli_commands/{kit-name}/  # For CLI commands
   

2. Update kit.yaml to reference the new artifact:

   For agents, skills, commands, or docs:

   artifacts:
     agent:
       - agents/{kit-name}/my-agent.md
     skill:
       - skills/{kit-name}/my-skill/SKILL.md
     command:
       - commands/{kit-name}/my-command.md
     doc:
       - docs/{kit-name}/my-doc.md
   

   For kit CLI commands:

   kit_cli_commands:
     - name: my-cli-command
       path: kit_cli_commands/{kit-name}/my_command.py
       description: Brief description
   

3. Test the changes by reinstalling the kit:

   # Uninstall existing kit
   dot-agent kit uninstall bundled:{kit-name}
   
   # Reinstall with new artifacts
   dot-agent kit install bundled:{kit-name}
   
   # Verify installation
   dot-agent check
   

Removing Artifacts from a Kit

To remove an artifact from a bundled kit:

1. Delete the artifact file from the kit directory
2. Remove the entry from kit.yaml (from artifacts or kit_cli_commands section)
3. Test the changes by reinstalling the kit (see above)

Common Patterns

Adding an agent:

• File: agents/{kit-name}/my-agent.md
• Entry: artifacts.agent list in kit.yaml
• Invoked as: "my-agent" (filename without .md)

Adding a skill:

• File: skills/{kit-name}/my-skill/SKILL.md (or skills/my-skill-name/SKILL.md for flattened structure)
• Entry: artifacts.skill list in kit.yaml
• Invoked as: "my-skill" (directory name containing SKILL.md)

Adding a slash command:

• File: commands/{kit-name}/my-command.md
• Entry: artifacts.command list in kit.yaml
• Invoked as: "/my-command" (filename without .md)

Adding a kit CLI command:

• File: kit_cli_commands/{kit-name}/my_command.py
• Entry: kit_cli_commands list in kit.yaml
• Invoked as: erk kit exec {kit-id} my-cli-command

Adding documentation:

• File: docs/{kit-name}/my-doc.md
• Entry: artifacts.doc list in kit.yaml
• Referenced by: Skills or agents that need supporting documentation

Troubleshooting

Missing artifact after rename:

This is the most common issue when renaming artifacts.

• Symptom: dot-agent check shows "Missing artifacts (in manifest but not installed)"
• Cause: kit.yaml still references old filename, or kit wasn't reinstalled after rename
• Fix:
  1. Update kit.yaml with new artifact path
  2. Force-reinstall kit: dot-agent kit install bundled:{kit-name} --force
  3. Verify: dot-agent check should show ✅
• See: ARTIFACT_LIFECYCLE.md for complete rename procedure

Stale symlink:

• Symptom: Symlink exists in .claude/ but appears broken (red in ls -la)
• Cause: Source file was renamed/moved but kit wasn't reinstalled
• Diagnosis: readlink .claude/commands/{namespace}/{artifact}.md points to non-existent file
• Fix: Force-reinstall kit to recreate symlinks with correct targets

Force reinstall required after manifest changes:

• When needed: After any changes to kit.yaml (adding/removing/renaming artifacts)
• Why: Symlinks sync file contents automatically, but structural changes require reinstallation
• How: dot-agent kit remove {kit-name} then dot-agent kit install bundled:{kit-name} --force
• Safe in dev mode: Symlinks point to source files, so no data is lost

Command not found after changes:

• Symptom: Artifact appears in dot-agent artifact list but invocation fails
• Possible causes:
  • Cross-references in other files still use old command name
  • Naming convention violated (must use kebab-case, not snake_case)
  • Namespace incorrect (should match directory structure)
• Fix: Update all cross-references, verify kebab-case naming, check namespace matches directory path

Artifact not appearing after installation:

• Verify the artifact path in kit.yaml matches the actual file location
• Check that the path is relative to the kit root directory
• Ensure the artifact follows naming conventions (kebab-case, no underscores)

Kit reinstall fails:

• Validate kit.yaml syntax with a YAML parser
• Check that all referenced files exist
• Verify namespace directories match kit name

Artifact conflicts between kits:

• Ensure each kit uses its own namespace directory ({kit-name}/)
• Check for duplicate artifact names across kits
• Review installed artifacts with dot-agent check

Further troubleshooting:

For detailed procedures on common operations (renaming, deleting, moving artifacts), see docs/ARTIFACT_LIFECYCLE.md.