Creating Commands
This guide walks you through creating, publishing, and sharing a ccmd command from scratch. We’ll create a real example command called “code-reviewer” that helps with code review tasks.
Prerequisites
- ccmd installed on your system
- Git installed
- GitHub account
- Basic familiarity with Markdown
Overview
We’ll create a command that:
- Reviews code for common issues
- Suggests improvements
- Can be installed by anyone using ccmd
Step 1: Initialize Your Command Project
First, create a directory for your command and initialize it:
# Create and enter the command directory
mkdir code-reviewer
cd code-reviewer
# Initialize the ccmd project
ccmd init
When prompted, enter these values:
This utility will walk you through creating a ccmd.yaml file.
Press ^C at any time to quit.
name: (code-reviewer) code-reviewer
version: (1.0.0) 1.0.0
description: AI-powered code review assistant for Claude Code
author: John Doe
repository: https://github.com/johndoe/code-reviewer
entry: (index.md) index.md
tags (comma-separated): code-review, quality, automation
About to write to /path/to/code-reviewer/ccmd.yaml:
name: code-reviewer
version: 1.0.0
description: AI-powered code review assistant for Claude Code
author: John Doe
repository: https://github.com/johndoe/code-reviewer
entry: index.md
tags:
- code-review
- quality
- automation
Is this OK? (yes) yes
This creates:
ccmd.yaml- Your command’s metadata.claude/commands/directory structure (if needed)
Step 2: Create the Command Instructions
Create the index.md file with instructions for Claude:
touch index.md
Add the following content to index.md:
# Code Reviewer Command
You are an AI assistant specialized in code review. When this command is invoked, you help users review their code for quality, best practices, and potential issues.
## Instructions
When the user invokes this command, you should:
1. **Analyze the code structure**
- Identify the programming language
- Understand the project context
- Note architectural patterns
2. **Review for common issues**
- Code style and formatting
- Potential bugs or errors
- Security vulnerabilities
- Performance concerns
3. **Suggest improvements**
- Better algorithms or data structures
- Cleaner code patterns
- Missing error handling
- Documentation gaps
4. **Provide actionable feedback**
- Be specific about line numbers
- Explain why something is an issue
- Offer concrete solutions
## Parameters
- `--file <path>`: Review a specific file
- `--severity <level>`: Filter by severity (error, warning, info)
- `--focus <area>`: Focus on specific areas (security, performance, style)
## Examples
### Basic Usage
User: "/code-reviewer --file src/api.js"
You should:
1. Read src/api.js
2. Analyze the code
3. Provide a structured review with:
- Summary of findings
- Detailed issues with line numbers
- Suggested fixes
### Focused Review
User: "/code-reviewer --focus security"
You should:
1. Scan all relevant files
2. Focus specifically on security issues
3. Highlight:
- SQL injection risks
- XSS vulnerabilities
- Authentication issues
- Data validation problems
## Response Format
Structure your responses as:
### Code Review Summary
- Files reviewed: X
- Issues found: Y (Z critical, W warnings, V suggestions)
### Critical Issues
1. **[File:Line]** Description
- Why it's a problem
- How to fix it
```language
// Fixed code example
```
### Warnings
[Similar format]
### Suggestions
[Similar format]
### Overall Assessment
Brief summary of code quality and next steps.
Step 3: Create User Documentation
Create a README.md for users:
touch README.md
Add the following content:
# Code Reviewer Command for ccmd
AI-powered code review assistant that helps you catch bugs, improve code quality, and follow best practices.
## Installation
```bash
ccmd install github.com/johndoe/code-reviewer
```
## Usage
Basic code review:
```bash
/code-reviewer --file src/main.js
```
Security-focused review:
```bash
/code-reviewer --focus security
```
Review all files:
```bash
/code-reviewer
```
## Features
- π Bug detection
- π Security vulnerability scanning
- β‘ Performance optimization suggestions
- π Documentation improvements
- π¨ Code style recommendations
## Options
- `--file <path>`: Review specific file
- `--severity <level>`: Filter by severity (error|warning|info)
- `--focus <area>`: Focus area (security|performance|style|all)
## Examples
### Review a Python file
```
/code-reviewer --file app.py
```
### Security audit
```
/code-reviewer --focus security --severity error
```
## Requirements
- Works with any programming language
- Best results with common languages (JavaScript, Python, Go, etc.)
## Author
John Doe - [@johndoe](https://github.com/johndoe)
## License
MIT
Step 4: Version Control with Git
Initialize Git and create your first commit:
# Initialize Git repository
git init
# Add all files
git add .
# Create initial commit
git commit -m "feat: initial code-reviewer command implementation"
# Create version tag
git tag -a v1.0.0 -m "Release version 1.0.0"
Step 5: Create GitHub Repository
- Go to GitHub
- Create a new repository named
code-reviewer - Don’t initialize with README (we already have one)
- Create the repository
Then connect your local repository:
# Add GitHub remote (replace with your username)
git remote add origin https://github.com/johndoe/code-reviewer.git
# Push code and tags
git push -u origin main
git push origin --tags
Step 6: Install and Test Your Command
Now anyone can install your command:
# Install from GitHub
ccmd instal https://github.com/johndoe/code-reviewer
# Verify installation
ccmd list
Output should show:
NAME VERSION DESCRIPTION UPDATED
-------------------- ---------- ---------------------------------------- --------------------
code-reviewer 1.0.0 AI-powered code review assistant for 1 minute ago
Claude Code
Test in Claude Code:
/code-reviewer --file <path-to-file>
Step 7: Updating Your Command
When you need to update your command:
1. Make Changes
Edit your files as needed:
# Edit index.md to add new features
# Update README.md with new documentation
2. Update Version
Edit ccmd.yaml:
version: 1.1.0 # Bump version according to semver
3. Commit and Tag
# Commit changes
git add .
git commit -m "feat: add support for TypeScript type checking"
# Create new version tag
git tag -a v1.1.0 -m "Release version 1.1.0
Features:
- TypeScript type checking
- Improved security scanning
- Better error messages"
# Push updates
git push origin main
git push origin --tags
4. Users Update
Users can update to the latest version:
ccmd update code-reviewer
Version Guidelines
Follow semantic versioning (semver):
- MAJOR (1.0.0 β 2.0.0): Breaking changes
- MINOR (1.0.0 β 1.1.0): New features, backwards compatible
- PATCH (1.0.0 β 1.0.1): Bug fixes
Examples:
- Adding a new parameter: Minor version bump
- Changing command behavior: Major version bump
- Fixing a typo: Patch version bump
Best Practices
1. Clear Instructions
Write instructions that are specific and actionable. Claude needs to understand exactly what to do.
2. Useful Examples
Include real-world examples in your index.md that demonstrate common use cases.
3. Error Handling
Tell Claude how to handle common error scenarios:
If the file doesn't exist, respond with:
"Error: File 'filename' not found. Please check the file path."
4. Consistent Updates
When updating:
- Document changes in commit messages
- Update README.md with new features
- Use meaningful version tags
Troubleshooting
Command not found after installation
- Check
ccmd listto verify installation - Ensure ccmd.yaml has correct name field
- Verify you have access to the repository
Changes not reflecting after update
- Check you pushed tags:
git push origin --tags - Users may need to run:
ccmd update code-reviewer - Verify version was bumped in ccmd.yaml
Installation fails
- Ensure repository exists and is accessible
- Check ccmd.yaml is valid YAML
- Verify index.md exists in repository root
Complete Example Repository Structure
Your final repository structure should look like:
code-reviewer/
βββ ccmd.yaml # Command metadata
βββ index.md # Claude instructions
βββ README.md # User documentation
Next Steps
- Enhance your command: Add more features based on user feedback
- Create more commands: Build a suite of useful tools
- Share with community: Announce in ccmd discussions
- Collaborate: Accept PRs and issues from users
Resources
- ccmd Documentation
- API Reference - File formats and specifications
- GitHub Discussions
Congratulations! You’ve created and published your first ccmd command. Users around the world can now install and use your code-reviewer command to improve their code quality.