Usage Guide

Learn how to use AI Instruction Kits v2.0 with its skill-based architecture and best practices.

📖 Basic Usage

In v2.0, simply referencing CLAUDE.md is all you need. ROOT_INSTRUCTION automatically selects the optimal skill for your task. After setup, the workflow is extremely simple.

Setup

# Integrate into your project
bash scripts/setup-project.sh

Daily Usage

# That's all you need! ROOT_INSTRUCTION auto-selects the right skill
claude "Refer to CLAUDE.md and implement user authentication"

# Same entry point regardless of task type
claude "Refer to CLAUDE.md and investigate performance bottlenecks"
claude "Refer to CLAUDE.md and design a RESTful API"

How it works: CLAUDE.md → ROOT_INSTRUCTION.md (Skill Orchestrator) → auto-selects optimal skill from .claude/skills/ → executes task

🎯 Skill-Based Workflow

The core of v2.0 is four core skills placed in .claude/skills/. ROOT_INSTRUCTION automatically suggests the appropriate skill based on the task at hand.

checkpoint-manager (Task Progress Management)

Automatically suggests checking pending tasks at the start of a conversation.

# Start a task
scripts/checkpoint.sh start "New feature development" 5
# → Task ID: TASK-123456-abc is issued

# Report progress
scripts/checkpoint.sh progress TASK-123456-abc 2 5 "Design complete" "Start implementation"

# Complete task
scripts/checkpoint.sh complete TASK-123456-abc "5 features implemented, 20 tests created"

Auto-suggestion timing: Suggests checking pending tasks at conversation start

worktree-manager (Git Worktree Management)

Suggests creating a worktree for complex tasks or multi-file changes.

# Create worktree
scripts/worktree-manager.sh create TASK-123456-abc "feature-auth"
# → .gitworktrees/ai-TASK-123456-abc-feature-auth/ is created

# Move to working directory
cd .gitworktrees/ai-TASK-123456-abc-feature-auth/

# After completing work
scripts/worktree-manager.sh complete TASK-123456-abc

Auto-suggestion timing: Suggests worktree creation for complex tasks

auto-build (Automatic Build & Test)

Automatically detects project type and runs the appropriate build command.

# Auto-detects project type and builds
# package.json → npm run build
# Cargo.toml → cargo build
# go.mod → go build
# etc.

Auto-suggestion timing: Suggests build/test execution after code changes

commit-safe (Safe Commits)

Creates clean commits without AI signatures.

# Clean commit with AI signatures automatically removed
scripts/commit.sh "feat: Add user authentication"

Auto-suggestion timing: Suggests file-specific commits after changes

Basic Workflow

1. Check pending → 2. Start task → 3. Create worktree (optional) → 4. Work → 5. Commit → 6. Complete

🛒 Marketplace Skills

Install additional skills from claude-skills-marketplace.

Install via Claude Code /plugin Command

# Step 1: Register the marketplace (one-time only)
/plugin marketplace add dobachi/claude-skills-marketplace

# Step 2: Install skills
/plugin install code-reviewer@dobachi-skills
/plugin install data-analyst@dobachi-skills

Run /plugin alone to open the plugin manager UI for interactive skill browsing, installation, and management.

Installation Scopes

Scope Description Saved to
User Available across all your projects ~/.claude/settings.json
Project Available to team members .claude/settings.json
Local Only you, this repo only .claude/settings.local.json

Manual Installation

If not using the /plugin command, you can place skill files directly:

# Copy a skill directory from the marketplace
cp -r path/to/code-reviewer .claude/skills/code-reviewer

Creating Custom Skills

If you need custom skills, use the skill-creator skill from the marketplace. Simply place skill files in .claude/skills/ to make them available.

📊 Checkpoint Management

scripts/checkpoint.sh is a script that records and manages task progress in detail.

Key Commands

Command Purpose Example
start Start a new task scripts/checkpoint.sh start "API development" 5
progress Report progress scripts/checkpoint.sh progress TASK-xxx 2 5 "Design complete" "Start implementation"
complete Complete a task scripts/checkpoint.sh complete TASK-xxx "3 endpoints implemented"
pending List pending tasks scripts/checkpoint.sh pending
summary Show task details scripts/checkpoint.sh summary TASK-xxx
error Report an error scripts/checkpoint.sh error TASK-xxx "Dependency error"

Tracking Skill Usage

# Record skill usage start
scripts/checkpoint.sh instruction-start ".claude/skills/auto-build" "API development" TASK-xxx

# Record skill usage completion
scripts/checkpoint.sh instruction-complete ".claude/skills/auto-build" "3 endpoints implemented" TASK-xxx

Visualizing Progress

# Check pending tasks
scripts/checkpoint.sh pending

# View detailed task history
scripts/checkpoint.sh summary TASK-xxx

# Show help
scripts/checkpoint.sh help

🌲 Git Worktree Workflow

For complex tasks or changes spanning multiple files, working in a Git worktree is recommended.

# 1. Start task
scripts/checkpoint.sh start "Auth feature development" 5
# → TASK-123456-abc

# 2. Create worktree
scripts/worktree-manager.sh create TASK-123456-abc "feature-auth"

# 3. Move to worktree and work
cd .gitworktrees/ai-TASK-123456-abc-feature-auth/

# 4. Work and commit
scripts/commit.sh "feat: Add authentication feature"

# 5. Complete task and clean up worktree
scripts/checkpoint.sh complete TASK-123456-abc "Auth feature implemented"
scripts/worktree-manager.sh complete TASK-123456-abc

Worktree Management Commands

# List worktrees
scripts/worktree-manager.sh list

# Switch to a specific worktree
scripts/worktree-manager.sh switch TASK-xxx

# Complete and clean up
scripts/worktree-manager.sh complete TASK-xxx

# Bulk remove unused worktrees
scripts/worktree-manager.sh clean

⚙️ Customizing PROJECT.md

Centralize project-specific settings in PROJECT.md.

Basic Configuration Example

## Project-Specific Instructions

### Coding Standards
- ESLint config: Follow .eslintrc.js
- Naming convention: camelCase
- Comments: JSDoc format

### Test Requirements
- Coverage: 80% minimum
- E2E tests: Using Cypress

### Build Settings
- Build command: npm run build
- Lint command: npm run lint
- Test command: npm run test

### Instruction Priority
1. PROJECT.md (highest priority)
2. Task-specific instructions
3. Skill auto-selection

🤖 Codex CLI / Gemini CLI

AI Instruction Kits supports AI CLI tools beyond Claude Code.

Codex CLI

Custom prompts are placed in .codex/prompts/. The filename becomes the /command-name you can invoke.

# Available commands
/build              # Detect project type and assist with build
/checkpoint         # Guide through checkpoint.sh subcommands
/commit-safe        # Safe commits without AI signatures
/commit-and-report  # Commit, push, and report to Issues
/reload-instructions # Reload instructions

Gemini CLI

TOML command definitions are placed in .gemini/commands/. The same command set as Codex CLI is available.

🎯 Best Practices

1. Skill Selection Tips

2. Managing Customizations

3. Feedback Loop

🔍 Troubleshooting

Q: Skills are not being auto-selected?

A: Verify that skill files are placed in the .claude/skills/ directory.

# Check for installed skills
ls .claude/skills/

# Re-run setup
bash scripts/setup-project.sh

Q: Checkpoint log not found?

A: checkpoint.log is created in the project root. It is auto-generated when you start your first task.

# Start a new task to create the log
scripts/checkpoint.sh start "Test task" 1

Q: Worktree creation fails?

A: Make sure you are running from the Git repository root directory.

# Navigate to repository root
cd $(git rev-parse --show-toplevel)

# Create worktree
scripts/worktree-manager.sh create TASK-xxx "description"

Q: Unsure about instruction priority?

A: Instructions are applied in the following priority order:

1. PROJECT.md (highest priority)
2. Task-specific instructions
3. ROOT_INSTRUCTION skill selection
4. Skill default behavior

📚 Learn More

💡 Tip

In v2.0, simply saying "Refer to CLAUDE.md" is enough for ROOT_INSTRUCTION to auto-select the optimal skill. Start simple, then add skills from the marketplace as needed.