Best Practices

Follow these best practices to get the most out of the CLI and its ecosystem.

General Usage

Command Organization

• Use meaningful command names
• Group related commands logically
• Provide clear help text for all commands

Error Handling

• Always provide actionable error messages
• Include suggestions for recovery
• Log detailed information for debugging

Performance

• Minimize expensive operations in the hot path
• Cache results when appropriate
• Use concurrent execution for independent tasks

Hooks Best Practices

Validation Hooks

Use PreToolUse hooks for validation:

export const validateConfig = async (context) => {
  if (!context.config.required) {
    throw new Error('Required config missing')
  }
}

Side Effects

Use PostToolUse hooks for cleanup:

export const cleanup = async (result) => {
  // Clean up resources
  await cleanupTempFiles()
}

Skills Best Practices

Single Responsibility

Each skill should have a single, well-defined purpose.

Documentation

Provide comprehensive documentation:

• Describe what the skill does
• List all configuration options
• Include usage examples

Error Handling

Handle errors gracefully and provide clear feedback:

try {
  // Skill logic
} catch (error) {
  throw new Error(`Skill failed: ${error.message}`)
}

Agents Best Practices

Clear Instructions

Provide clear, unambiguous instructions to agents:

instructions: `
You are responsible for managing component versions.
Always validate inputs before processing.
Report results in JSON format.
`

Tool Selection

Choose tools that are:

• Well-tested and reliable
• Properly documented
• Focused on specific tasks

Error Recovery

Implement fallback strategies for common failure scenarios.

MCP Servers Best Practices

Server Design

• Keep servers lightweight and focused
• Implement proper timeout handling
• Provide meaningful error messages

Resource Management

• Clean up resources promptly
• Limit concurrent connections
• Monitor memory usage