gh-sjungling-claude-plugins-plugins-claude/skills/builder/references/slash-commands-guide.md

Slash Commands Creation Guide

Overview

Slash commands are custom shortcuts that execute specific workflows or expand into prompts. They provide quick access to common operations and can accept arguments for dynamic behavior.

Official Documentation: https://docs.claude.com/en/docs/claude-code/slash-commands.md

When to Create a Slash Command

Create a slash command when you need:

• Quick keyboard shortcuts for common tasks
• Parameterized workflows with user input
• Simple, linear execution flows
• Convenience wrappers around common operations
• Reusable prompts with argument substitution

File Structure

Slash commands are markdown files that can optionally include YAML frontmatter:

---
description: Clear one-line description of what this command does
allowed-tools:
  - Bash(npm run build:*)
  - Bash(npm test:*)
args:
  - name: target
    description: The build target to compile
---

[Command prompt content with instructions and optional argument placeholders]

Location

• Personal: ~/.claude/commands/
• Plugin: <plugin-root>/commands/
• Project: .claude/commands/

Naming

• Use kebab-case for command file names
• File name becomes the command name
• format-code.md → /format-code
• run-tests.md → /run-tests

YAML Frontmatter

Frontmatter is optional but recommended for:

• Documenting command purpose
• Preapproving tools and bash commands
• Defining expected arguments

Fields

description (string, optional)

• One-line explanation of command purpose
• Shown in command lists and help
• Example: Format and lint Swift code using swift-format

allowed-tools (array, optional)

• Preapprove bash commands and tools for execution
• Uses glob patterns for flexibility
• Reduces user approval friction
• Example:

  allowed-tools:
    - Bash(echo:*)
    - Bash(git:*)
    - Bash(npm run build:*)
    - Bash(swift-format:*)
  

args (array of objects, optional)

• Document expected command arguments
• Each arg has name and description
• For documentation only - doesn't enforce validation
• Example:

  args:
    - name: environment
      description: Target environment (dev, staging, prod)
    - name: version
      description: Version tag to deploy
  

Tool Preapprovals

The allowed-tools field uses specific syntax:

Bash Commands

allowed-tools:
  - Bash(command:*)  # Allow command with any arguments
  - Bash(git:*)      # Allow all git commands
  - Bash(npm run build:*)  # Allow npm run build variants
  - Bash(echo:*)     # Allow echo
  - Bash(find:*)     # Allow find

Other Tools

You can also preapprove Claude Code tools:

allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash(*)          # Allow all bash commands (use carefully)

Best Practices

Do:

• Be specific with command patterns
• Use wildcards for argument flexibility
• Include only necessary commands
• Consider security implications

Don't:

• Preapprove dangerous commands (rm -rf, etc.) unless absolutely necessary
• Use Bash(*) unless you fully trust the command
• Preapprove commands not used by the workflow

Argument Handling

Commands can accept and use arguments through placeholders:

Argument Placeholders

• $ARGUMENTS - All arguments as a single string
• $1, $2, $3, etc. - Individual positional arguments
• $N - Nth argument (1-indexed)

Example: Parameterized Command

---
description: Deploy application to specified environment
allowed-tools:
  - Bash(git:*)
  - Bash(npm run deploy:*)
args:
  - name: environment
    description: Target environment (dev, staging, prod)
---

Deploy the application to the $1 environment.

Steps:
1. Verify the git branch is clean
2. Run the deployment script for $1
3. Verify deployment succeeded
4. Update deployment tracking

Use: /deploy prod

Usage: /deploy staging → $1 becomes staging

Example: Multiple Arguments

---
description: Create a new feature branch
allowed-tools:
  - Bash(git:*)
args:
  - name: branch-name
    description: Name of the feature branch
  - name: base-branch
    description: Base branch to branch from (default: main)
---

Create a new feature branch named "$1" from base branch "$2".

1. Checkout the base branch: $2
2. Pull latest changes
3. Create and checkout new branch: $1
4. Push the new branch to remote

Use: /create-branch my-feature main

Usage: /create-branch user-auth develop → $1 = user-auth, $2 = develop

Command Content

The markdown content after frontmatter is the command's prompt/instructions:

Simple Commands

Direct instructions that execute immediately:

---
description: Run the test suite
allowed-tools:
  - Bash(npm test:*)
---

Run the complete test suite using npm test. Report any failures with details.

Workflow Commands

Multi-step processes with clear guidance:

---
description: Prepare a release
allowed-tools:
  - Bash(git:*)
  - Bash(npm:*)
args:
  - name: version
    description: Semantic version for the release (e.g., 1.2.3)
---

Prepare a new release version $1:

1. Update version in package.json to $1
2. Update CHANGELOG.md with version $1 and today's date
3. Commit changes with message "chore: prepare release $1"
4. Create git tag v$1
5. Build the project
6. Ask user if ready to push tag and publish

Use: /prepare-release 1.2.3

Commands with Subagents

Delegate complex work to specialized agents:

---
description: Write comprehensive API documentation
allowed-tools:
  - Task
---

Use the technical-writer agent to create comprehensive API documentation for the current project.

The documentation should include:
- API overview and getting started
- Authentication guide
- Endpoint reference with examples
- Error handling
- Rate limiting
- Code examples in multiple languages

Analyze the codebase first, then delegate to the technical-writer agent.

Common Patterns

Code Quality Commands

---
description: Format and lint Swift code
allowed-tools:
  - Bash(swift-format:*)
  - Bash(find:*)
---

Format and lint all Swift code in the project:

1. Find all .swift files
2. Run swift-format on each file
3. Report any formatting issues
4. Fix issues automatically where possible

Git Workflow Commands

---
description: Create a conventional commit
allowed-tools:
  - Bash(git:*)
---

Create a conventional commit following the format:

type(scope): description

Where type is one of: feat, fix, docs, style, refactor, test, chore

1. Show current git status
2. Ask user for commit type and scope
3. Ask for commit description
4. Create commit with conventional format
5. Include Claude Code co-author

Project Setup Commands

---
description: Initialize a new TypeScript project
allowed-tools:
  - Bash(npm:*)
  - Bash(mkdir:*)
  - Write
---

Initialize a new TypeScript project with best practices:

1. Create directory structure (src/, tests/, dist/)
2. Initialize npm package
3. Install TypeScript and development dependencies
4. Create tsconfig.json with strict settings
5. Create initial src/index.ts
6. Set up test framework
7. Create README.md

Ask user for project name and description first.

Deployment Commands

---
description: Deploy to production
allowed-tools:
  - Bash(git:*)
  - Bash(npm run build:*)
  - Bash(gh:*)
args:
  - name: version
    description: Version to deploy (defaults to current)
---

Deploy version $1 to production:

⚠️  WARNING: This will deploy to PRODUCTION

1. Confirm with user before proceeding
2. Verify git branch is main
3. Verify working directory is clean
4. Run production build
5. Run smoke tests
6. Create GitHub release
7. Trigger deployment pipeline
8. Monitor deployment status

Use: /deploy-prod 1.2.3

Testing Your Command

1. Invoke the command:

   /your-command arg1 arg2
   

2. Verify behavior:

   • Do arguments substitute correctly?
   • Are tools preapproved appropriately?
   • Does the workflow execute as expected?

3. Test edge cases:

   • Missing arguments
   • Invalid arguments
   • Error conditions

4. Refine:

   • Update allowed-tools if approval prompts appear
   • Clarify instructions if behavior is unexpected
   • Add error handling guidance

Commands vs Skills vs Subagents

Use Commands when:

• Workflow is straightforward and linear
• You want a quick keyboard shortcut
• Users will invoke explicitly
• Arguments customize behavior
• Example: /format-code, /run-tests, /deploy

Use Skills when:

• Guidance should activate automatically
• Pattern applies across contexts
• Always-available best practices
• No explicit invocation needed
• Example: Code style patterns, debugging workflows

Use Subagents when:

• Complex decision-making required
• Context isolation needed
• Delegatable, self-contained workflows
• Specialized tool restrictions
• Example: Code reviews, technical writing

Plugin Integration

When including commands in plugins:

1. Place command markdown files in commands/ subdirectory
2. Register in .claude-plugin/marketplace.json:

   {
     "commands": {
       "command-name": "./commands/command-name.md"
     }
   }
   

3. Document in plugin README.md
4. Test command installation and execution

Example: Complete Command

---
description: Create a new React component with tests and storybook
allowed-tools:
  - Bash(mkdir:*)
  - Write
  - Edit
args:
  - name: component-name
    description: Name of the component (PascalCase)
  - name: component-type
    description: Type of component (functional or class, defaults to functional)
---

# Create React Component: $1

Create a new React component named $1 as a $2 component.

## Steps

1. **Create component directory**:

src/components/$1/

2. **Create component file**: `src/components/$1/$1.tsx`
```tsx
import React from 'react';
import styles from './$1.module.css';

interface ${1}Props {
  // TODO: Define props
}

export const $1: React.FC<${1}Props> = (props) => {
  return (
    <div className={styles.container}>
      <h2>$1</h2>
    </div>
  );
};

3. Create styles: src/components/$1/$1.module.css

   .container {
     /* Component styles */
   }
   

4. Create test file: src/components/$1/$1.test.tsx

   import { render, screen } from '@testing-library/react';
   import { $1 } from './$1';
   
   describe('$1', () => {
     it('renders without crashing', () => {
       render(<$1 />);
       expect(screen.getByText('$1')).toBeInTheDocument();
     });
   });
   

5. Create Storybook story: src/components/$1/$1.stories.tsx

   import type { Meta, StoryObj } from '@storybook/react';
   import { $1 } from './$1';
   
   const meta: Meta<typeof $1> = {
     title: 'Components/$1',
     component: $1,
   };
   
   export default meta;
   type Story = StoryObj<typeof $1>;
   
   export const Default: Story = {
     args: {},
   };
   

6. Create index file: src/components/$1/index.ts

   export { $1 } from './$1';
   export type { ${1}Props } from './$1';
   

7. Update main components index: Add to src/components/index.ts:

   export { $1 } from './$1';
   

Usage Examples

# Create functional component (default)
/create-component Button

# Create class component
/create-component Modal class

Next Steps

After creating the component:

1. Define the component props interface
2. Implement component logic
3. Add styles
4. Write comprehensive tests
5. Create Storybook stories for different states
6. Update documentation

## Advanced Techniques

### Conditional Logic

Guide Claude to make decisions based on arguments:

```markdown
If $1 is "production":
  - Use production configuration
  - Require manual confirmation
  - Enable extra validation

If $1 is "development":
  - Use development configuration
  - Skip confirmation
  - Allow warnings

Error Handling

Include guidance for error scenarios:

If the build fails:
1. Show the error output
2. Suggest common fixes
3. Ask user if they want to retry

If tests fail:
1. Report which tests failed
2. Show failure details
3. Ask if user wants to run only failed tests

Checklists

Provide systematic validation:

Before deploying:
- [ ] All tests pass
- [ ] Build succeeds
- [ ] Version updated
- [ ] CHANGELOG updated
- [ ] Git working directory clean
- [ ] On correct branch

Security Considerations

Be careful with:

• Commands that modify production systems
• Commands that delete files or data
• Commands with elevated privileges
• Commands that expose secrets

Best practices:

• Require confirmation for destructive operations
• Validate inputs before execution
• Limit preapproved commands to minimum necessary
• Document security implications
• Consider using read-only operations where possible

Discoverability

Users discover commands through:

• /help command output
• Plugin documentation
• Tab completion in Claude Code
• README files

Make commands discoverable by:

• Using clear, descriptive names
• Writing good descriptions in frontmatter
• Documenting in plugin README
• Using conventional naming patterns