Features

Detailed introduction to all features of AI Instruction Kits.

🧩 v2.0 Skill-Based Architecture

Overview

The v2.0 skill-based architecture enables automatic selection and execution of skills tailored to each task.

Skill Orchestrator (ROOT_INSTRUCTION)

Analyzes tasks and automatically selects the optimal skills from .claude/skills/ to execute them.

Key Features:

Automatic task analysis: Just input tasks in natural language
Intelligent selection: Selects optimal skills based on task content
Marketplace integration: Easily add community-built skills
Start with minimal config: Get started with just the core skills

Core Skills (4 types)

checkpoint-manager: Task progress management
- Automatically tracks task start, progress, and completion
- Parallel task management, statistics display
worktree-manager: Git worktree management
- Automatically creates safe working branches per task
- Merge and cleanup on completion
auto-build: Automatic build and test
- Detects project type and runs appropriate build commands
- Test execution and result reporting
commit-safe: Safe commits
- Clean commits without AI signatures
- File-specific safe commit workflow

Marketplace Skills

Add community-created skills from claude-skills-marketplace.

Skills become available simply by placing them in .claude/skills/.

Usage Examples

# Skill orchestrator automatically selects skills
claude "Implement a new feature"
# → ROOT_INSTRUCTION analyzes the task
# → worktree-manager creates a safe working branch
# → checkpoint-manager automatically tracks progress
# → auto-build runs build and tests
# → commit-safe performs clean commits

# Progress management
claude "Check task progress"
# → checkpoint-manager skill activates
# → Shows list of incomplete tasks and statistics

# Safe commits
claude "Commit my changes"
# → commit-safe skill commits without AI signatures

📚 Skills and Customization

System Instructions

ROOT_INSTRUCTION.md - Skill orchestrator (auto-selects optimal skills from .claude/skills/)

Core Skills (placed in `.claude/skills/`)

Marketplace Skills

Install additional specialized skills from claude-skills-marketplace.

Category	Example Skills
Development Tools	build, commit-and-report, github-issues
Role Skills	web-api-dev, data-analyst, python-expert, code-reviewer
Presentation	marp-slides
Quality	fact-checker, evidence-check

Custom Instructions

Add project-specific instructions under instructions/en/:

instructions/en/coding/ - Coding related
instructions/en/writing/ - Writing related
instructions/en/analysis/ - Analysis related

🔧 Core Features

Claude Code Agent Feature

Automate large-scale analysis tasks using Task tool (agent feature):

Code Quality Analysis: Project-wide quality checks
Dependency Investigation: Comprehensive dependency mapping
Test Coverage: Thorough coverage analysis
Documentation Verification: Implementation consistency checks

Use Claude Code’s Task tool to run sub-agents that perform parallel analysis in independent contexts. Refer to the “Claude Code Agent Feature” section in CLAUDE.md for configuration details.

Checkpoint Management (Extended Version)

Detailed tracking of work progress and instruction usage history

# Task start
scripts/checkpoint.sh start "New feature implementation" 5
📌 Task ID: TASK-123456-abc123

# Track instruction usage (new feature)
scripts/checkpoint.sh instruction-start "instructions/en/system/ROOT_INSTRUCTION.md" "API development" TASK-123456-abc123
scripts/checkpoint.sh instruction-complete "instructions/en/system/ROOT_INSTRUCTION.md" "3 endpoints implemented" TASK-123456-abc123

# AI-friendly concise output mode (new feature)
scripts/checkpoint.sh ai pending
scripts/checkpoint.sh ai progress TASK-123456-abc123 2 5 "Implementing" "Creating tests"

# Statistics display (new feature)
scripts/checkpoint.sh stats
scripts/checkpoint.sh history

Claude Code Custom Commands (New Feature)

Efficiency features for Claude Code users:

Command	Description	Example
`/checkpoint`	Checkpoint management	`/checkpoint start "New feature implementation" 5`
`/commit-and-report`	Commit & Issue report	`/commit-and-report "Bug fix complete"`
`/commit-safe`	Clean commit (no AI signature)	`/commit-safe "Documentation update"`
`/reload-instructions`	Reload instructions	`/reload-instructions`
`/github-issues` 🆕	Check GitHub issues and organize tasks	`/github-issues`
`/reload-and-reset` 🆕	Reset AI system and reload instructions	`/reload-and-reset`

Integration Modes

Choose based on project needs

Mode	Benefits	Use Cases
Copy	• No Git • Fastest setup • Offline support	Small projects Non-Git environments
Clone	• Full control • Custom modifications • History management	Large customizations Custom instruction development
Submodule	• Easy updates • Version control • Multi-project support	Team development Long-term projects

Custom URL Support

Use instructions from your own repository

# Corporate internal repository
--url https://gitlab.company.com/ai-team/instructions.git

# Personal fork
--url https://github.com/yourname/custom-instructions.git

# Private repository (requires authentication)
--url git@github.com:org/private-instructions.git

🎯 Advanced Usage

1. Creating Custom Instructions

# Custom Instruction Template
## Purpose
Clearly describe the purpose of this instruction

## Prerequisites
- Required knowledge
- Environment requirements
- Dependencies

## Specific Instructions
1. Detailed step 1
2. Detailed step 2
3. ...

## Expected Outcomes
- Deliverable 1
- Deliverable 2

---
## License Information
- **License**: [License name]
- **Author**: [Name]
- **Date**: [Date]

2. PROJECT.md Customization

Describe project-specific settings in detail:

## Project-specific Additional Instructions

### Architecture
- Microservices architecture
- API Gateway: Kong
- Message Queue: RabbitMQ

### Development Standards
- Commit messages: Conventional Commits
- Branch strategy: Git Flow
- Code review: Required (2+ reviewers)

### Security
- Authentication: OAuth 2.0
- Data encryption: AES-256
- Secret management: HashiCorp Vault

3. Pre-customizing Templates

# Edit templates
vi templates/en/PROJECT_TEMPLATE.md

# Add common settings applied to all new projects
- CI/CD configuration
- Standard lint rules
- Common test frameworks

🔒 Security Features

Private Repository Support

Securely retrieve instructions from organization-specific private repositories.

Implementation

# Example of internal repository
bash setup-project.sh --url https://github.com/company/private-ai-instructions.git

Benefits: Securely manage organization-specific confidential instructions
Use cases: Internal coding standards, proprietary business logic, security policies

SSH Authentication Support

Supports secure authentication using SSH keys.

Implementation

# Using SSH format URL
bash setup-project.sh --url git@github.com:company/private-instructions.git --submodule

Benefits: Secure authentication without passwords, easy automation in CI/CD environments
Prerequisites: SSH key setup required (ssh-keygen and ssh-add)

Access Token Support

Supports authentication using personal access tokens from GitHub/GitLab.

Implementation

# Embedding token in URL
bash setup-project.sh --url https://YOUR_TOKEN@github.com/company/repo.git

# Using environment variable (more secure)
export GIT_TOKEN=your_personal_access_token
bash setup-project.sh --url https://${GIT_TOKEN}@github.com/company/repo.git

Benefits: Fine-grained permission control, expiration settings, minimal access rights
Use cases: CI/CD environments, automation scripts, temporary access

Internal Network Support

Supports Git servers inside organizations not exposed to the internet.

Implementation

# Example internal GitLab server
bash setup-project.sh --url https://gitlab.company.local/team/ai-instructions.git

# Example internal Gitea server
bash setup-project.sh --url http://git.internal:3000/dev/instructions.git

Supported servers: GitLab CE/EE, Gitea, Bitbucket Server, other Git-compatible servers
Benefits: Completely internal operation, no external network required, high security

📦 Version Management

Version Pinning

Pin the version of instructions used in your project to prevent unexpected changes.

Implementation with Submodules

# Pin to specific commit
cd instructions/ai_instruction_kits
git checkout v1.2.3  # or specific commit hash
cd ../..
git add instructions/ai_instruction_kits
git commit -m "Pin instructions to v1.2.3"

Benefits: Ensure reproducibility, stable operation, consistency across teams
Use cases: Production environments, critical projects, auditable environments

Update Control

Manage instruction updates systematically and apply after testing.

Update Process

# Check latest version (without actually updating)
cd instructions/ai_instruction_kits
git fetch
git log HEAD..origin/main --oneline

# Apply update after testing
git pull origin main
cd ../..
git add instructions/ai_instruction_kits
git commit -m "Update instructions to latest version"

Workflow:
1. Test new version in development environment
2. Review and confirm changes
3. Gradually apply to staging → production

Rollback Feature

Instantly revert to previous stable version if issues occur.

Rollback Steps

# Revert to previous version
cd instructions/ai_instruction_kits
git checkout HEAD~1
cd ../..
git add instructions/ai_instruction_kits
git commit -m "Rollback instructions to previous version"

# Revert to specific stable version
cd instructions/ai_instruction_kits
git checkout v1.1.0  # Specific stable version
cd ../..
git add instructions/ai_instruction_kits
git commit -m "Rollback instructions to v1.1.0 (stable)"

Benefits: Risk management, quick incident response, safe to try updates
Recommendation: Test before and after rollback, record change history

📊 Usage Statistics and Metrics

Checkpoint Log Analysis

Quantitatively understand work progress and results.

Basic Statistics

# Total completed tasks
grep "COMPLETE" checkpoint.log | wc -l

# Check running tasks (incomplete)
grep "START" checkpoint.log | grep -v "COMPLETE"

# Today's task list
grep "$(date +%Y-%m-%d)" checkpoint.log

# Extract tasks with errors
grep "ERROR" checkpoint.log

Task Analysis Example

# Script example to calculate time per task ID
#!/bin/bash
while read -r line; do
    if [[ $line =~ \[TASK-([a-f0-9]+)\] ]]; then
        task_id="${BASH_REMATCH[1]}"
        # Find START/COMPLETE pairs and calculate time difference
        # (Implementation details omitted)
    fi
done < checkpoint.log

Project Customization Analysis

Understand project characteristics from PROJECT.md contents:

# Check project settings
cat instructions/PROJECT.md | grep -E "(Build command|Lint command|Test framework)"

# Count customized items
grep -v "^#" instructions/PROJECT.md | grep -v "^$" | grep -v "Example:" | wc -l

Deliverable Quantification

Extract results from checkpoint log:

# Generate deliverable summary
grep "Result:" checkpoint.log | sed 's/.*Result: //' | sort | uniq -c | sort -nr

# Count created files, tests, etc.
grep "Result:" checkpoint.log | grep -E "[0-9]+ (files|tests|endpoints)"

🚀 Future Plans

Planned Features

🤖 AI-powered Instruction Generation

Automatically generate instructions for new categories by learning from existing ones

Suggest optimal instructions by analyzing project characteristics
Combine best practices from existing instructions
Improve based on user feedback

🔍 Instruction Search and Filtering

Quickly find needed instructions even as they grow

Tag-based classification system
Keyword search functionality
Dependency visualization
Usage frequency-based recommendations

📝 Version Diff Display

Easily understand what changed during updates

Highlight changed sections
Impact analysis
Decision support for rollback

🧪 Instruction Testing Framework

Ensure instruction quality

Test cases for expected output
Ambiguity checking
Cross-AI compatibility testing

Community Contributions

Adding new instruction categories
Multi-language support (Chinese, Korean, etc.)
Industry-specific template collections
Best practice sharing

Features

🧩 v2.0 Skill-Based Architecture

Overview

Skill Orchestrator (ROOT_INSTRUCTION)

Core Skills (4 types)

Marketplace Skills

Usage Examples

📚 Skills and Customization

System Instructions

Core Skills (placed in .claude/skills/)

Marketplace Skills

Custom Instructions

🔧 Core Features

Claude Code Agent Feature

Checkpoint Management (Extended Version)

Claude Code Custom Commands (New Feature)

Integration Modes

Custom URL Support

🎯 Advanced Usage

1. Creating Custom Instructions

2. PROJECT.md Customization

3. Pre-customizing Templates

🔒 Security Features

Private Repository Support

Implementation

SSH Authentication Support

Implementation

Access Token Support

Implementation

Internal Network Support

Implementation

📦 Version Management

Version Pinning

Implementation with Submodules

Update Control

Update Process

Rollback Feature

Rollback Steps

📊 Usage Statistics and Metrics

Checkpoint Log Analysis

Basic Statistics

Task Analysis Example

Project Customization Analysis

Deliverable Quantification

🚀 Future Plans

Planned Features

🤖 AI-powered Instruction Generation

🔍 Instruction Search and Filtering

📝 Version Diff Display

🧪 Instruction Testing Framework

Community Contributions

📚 Learn More

Core Skills (placed in `.claude/skills/`)