.forge/skills/create-command/SKILL.md
Create and manage commands for the code-forge application. Commands are modular workflows that can be invoked to perform specific tasks.
CRITICAL: All command files must be created in the <cwd>/.forge/commands directory, where <cwd> is the current working directory of your code-forge project.
<cwd>/.forge/commands{command-name}.md/home/user/my-project, commands go in /home/user/my-project/.forge/commands/This is the only location where forge will discover and load custom commands.
Every command file must have:
YAML Frontmatter (required):
name: Command identifier (use hyphens for multi-word names)description: What the command doesCommand Body (required):
---
name: check
description: Checks if the code is ready to be committed
---
- Run the `lint` and `test` commands and verify if everything is fine.
<lint>cargo +nightly fmt --all; cargo +nightly clippy --fix --allow-staged --allow-dirty --workspace</lint>
<test>cargo insta test --accept --unreferenced=delete</test>
- Fix every issue found in the process
This sample demonstrates all three tag types:
---
name: sample-command
description: Sample command demonstrating the command file structure
---
This is a sample command that demonstrates the structure of command files.
- First step: Perform an initial action
<lint>echo "Running linting..."</lint>
- Second step: Execute tests
<test>echo "Running tests..."</test>
- Third step: Complete the workflow
<shell>echo "Workflow complete!"</shell>
- Final step: Verify everything worked correctly
Identify what the command should accomplish:
Use verb-based names with hyphens for multi-word commands:
check, fixme, pr-description, run-testschecker, fixing, PRdescriptionCreate the file in the <cwd>/.forge/commands directory with the format: {command-name}.md
IMPORTANT: The file MUST be in <cwd>/.forge/commands where <cwd> is your current working directory. Commands placed anywhere else will not be discovered by forge.
---
name: your-command-name
description: Clear, concise description of what this command does
---
Use markdown lists for steps. Each step should:
Use these tags for automated workflows:
<lint> TagFor linting/formatting commands:
<lint>cargo +nightly fmt --all; cargo +nightly clippy --fix --allow-staged --allow-dirty --workspace</lint>
<test> TagFor testing commands:
<test>cargo insta test --accept --unreferenced=delete</test>
<shell> TagFor general shell commands (not linting or testing):
<shell>rm -rf target/debug</shell>
Tags should be placed on their own line after the step description:
- Run linting and testing
<lint>your-lint-command</lint>
<test>your-test-command</test>
Single-step or instruction-only commands:
---
name: fixme
description: Looks for all the fixme comments in the code and attempts to fix them
---
Find all the FIXME comments in source-code files and attempt to fix them.
Commands with multiple sequential steps:
---
name: pr-description
description: Updates the description of the PR
---
- I have created a Pull Request with all the accepted changes
- Understand the current PR deeply using the GH CLI and update the PR title and description
- Make sure the title follows conventional commits standard
- Top-level summary should contain 2-3 lines about the core functionality improvements
Commands that include automated checks:
---
name: check
description: Checks if the code is ready to be committed
---
- Run the `lint` and `test` commands and verify if everything is fine.
<lint>cargo +nightly fmt --all; cargo +nightly clippy --fix --allow-staged --allow-dirty --workspace</lint>
<test>cargo insta test --accept --unreferenced=delete</test>
- Fix every issue found in the process
---
name: simple-command
description: Does one specific thing
---
Single clear instruction or description.
---
name: automated-workflow
description: Runs automated checks and performs follow-up actions
---
- Run automated checks
<lint>your-lint-command</lint>
<test>your-test-command</test>
- Review and fix any issues found
- Complete the workflow
---
name: multi-step-workflow
description: Performs multiple sequential steps
---
- First step with clear action
- Second step with context
- Third step with specific requirements
- Final step with verification
---
name: git-workflow
description: Performs git operations
---
- Stage changes
<shell>git add .</shell>
- Run pre-commit checks
<lint>cargo fmt --all</lint>
<test>cargo test</test>
- Commit with message
<shell>git commit -m "your commit message"</shell>
- Push to remote
<shell>git push</shell>
<lint>, <test>, and <shell> tags---
name: commit-check
description: Verifies code is ready to commit
---
- Run linting and tests
<lint>cargo fmt --all; cargo clippy --fix --allow-staged</lint>
<test>cargo test</test>
- Review and fix any issues
- Stage all changes
---
name: update-docs
description: Updates documentation for recent changes
---
- Review recent code changes
- Identify functions or modules that need documentation
- Update inline documentation comments
- Regenerate any auto-generated docs
- Verify documentation builds successfully
---
name: cleanup
description: Cleans up temporary files and artifacts
---
- Remove build artifacts
<shell>rm -rf target/debug</shell>
- Remove temporary files
<shell>find . -name "*.tmp" -delete</shell>
- Clean up dependency caches if needed
- Verify the project still builds
---
name: build-deploy
description: Builds the project and deploys to staging
---
- Build the project in release mode
<shell>cargo build --release</shell>
- Run integration tests
<test>cargo test --test integration</test>
- Build Docker image
<shell>docker build -t myapp:latest .</shell>
- Tag image for staging
<shell>docker tag myapp:latest myapp:staging</shell>
- Push to registry
<shell>docker push myapp:staging</shell>
- Deploy to staging environment
<shell>kubectl set image deployment/myapp myapp=myapp:staging</shell>
Use this checklist to verify your command is complete and correct:
<cwd>/.forge/commands directory (CRITICAL)check.md for name: check).md extension--- delimitersname field is presentname uses lowercase lettersname uses hyphens for multi-word namesname is verb-based (imperative form)description field is presentdescription is clear and concisedescription describes what, not how-)<lint>, <test>, <shell>)forge list command --custom (or forge list cmd) and verify your command appears in the listBad: Wrong delimiter:
---
name: my-command
description: My command
(Missing closing ---)
Good: Correct:
---
name: my-command
description: My command
---
Bad: Missing required field:
---
name: my-command
---
(Missing description)
Good: Correct:
---
name: my-command
description: Does something useful
---
Bad: CamelCase name:
---
name: myCommand
description: Does something
---
Good: Correct:
---
name: my-command
description: Does something
---
Bad: Noun instead of verb:
---
name: checker
description: Checks something
---
Good: Correct:
---
name: check
description: Checks something
---
Bad: No action verb:
---
name: test
description: Runs tests
---
- The tests
- The code
Good: Correct:
---
name: test
description: Runs tests
---
- Run all tests
- Verify code quality
Bad: Vague steps:
---
name: deploy
description: Deploys application
---
- Do the deployment
- Make sure it works
Good: Correct:
---
name: deploy
description: Deploys application to production
---
- Build the Docker image
<shell>docker build -t myapp:latest .</shell>
- Push to registry
<shell>docker push myapp:latest</shell>
- Deploy to production
<shell>kubectl set image deployment/myapp myapp=myapp:latest</shell>
- Verify deployment is healthy
Bad: Tag on same line:
- Run tests <test>cargo test</test>
Good: Correct:
- Run tests
<test>cargo test</test>
Bad: Invalid tag:
- Run checks
<check>cargo clippy</check>
Good: Correct:
- Run checks
<lint>cargo clippy</lint>
Bad: Incomplete command:
- Format code
<lint>cargo fmt</lint>
(Missing --all flag)
Good: Correct:
- Format code
<lint>cargo fmt --all</lint>
<cwd>/.forge/commands (where <cwd> is current working directory){command-name}.md<lint> - For linting/formatting commands<test> - For testing commands<shell> - For general shell commands<lint> when running formatters or linters<test> when running test suites<shell> for other shell commandsAfter creating a command, test it by:
Syntax Check: Verify YAML is valid
# If you have yamllint installed
yamllint path/to/your-command.md
Manual Review: Read through the command
Execution Test: Run the command
Forge Recognition Test: Verify the command is recognized by forge
# Option 1: List all commands (custom commands marked as type: custom)
forge list command
# Option 2: List only custom commands
forge list cmd
# Option 3: List only custom commands (newer versions)
forge list command --custom
Edge Cases: Consider unusual scenarios
After creating a command:
Verify the file location: Ensure the file is in <cwd>/.forge/commands directory (CRITICAL - commands anywhere else will not be found)
Check YAML frontmatter is valid (use --- delimiters)
Ensure the command name matches the filename (without .md)
Verify the command is recognized by forge:
# Option 1: List all commands (custom commands marked as type: custom)
forge list command
# Option 2: List only custom commands
forge list cmd
# Option 3: List only custom commands (newer versions)
forge list command --custom
Your new command should appear in the list with its name and description
Test the command to ensure it works as expected
Verify special tags are properly formatted
If your command doesn't appear in the list, check:
<cwd>/.forge/commands directory (this is the most common issue)name field in frontmatter--- delimitersname and description fields are presentIf you're unsure about something: