Skills Management

Learn how to create and manage skills to extend your AI agent’s capabilities with specialized knowledge

How to Use the /skill Command - Step by Step Guide

Step-by-Step Usage Guide

Step 1: Check Available Commands

First, see what the /skill command can do:

/skill

Output:

Skill Management

Available commands:
  /skill list              - List all available skills
  /skill create <name>     - Create a new skill
  /skill info <name>       - Show skill details

What are skills?
Skills extend the AI agent's capabilities with specialized knowledge and instructions.
They are stored in .blackbox/skills/ and automatically discovered by the agent.

Examples:
  /skill list
  /skill create frontend
  /skill info frontend

Step 2: Create Your First Skill

You can create skills in two ways:

Option A: Using the Command (Quick Setup)

Create a new skill for a specific domain (e.g., frontend development):

/skill create frontend

Output:

✓ Skill "frontend" created successfully!

Location: /workspace/.blackbox/skills/frontend/SKILL.md

Next steps:
1. Edit the SKILL.md file to add your skill's instructions
2. Update the description in the YAML frontmatter
3. The AI agent will automatically discover and use your skill

Tip: Use /skill info frontend to view the skill template.

Option B: Using Natural Language (Detailed Setup)

You can also ask the AI agent to create a skill with detailed content using natural language:

You: Create a skill for React frontend development that includes TypeScript best practices, component patterns, state management with hooks, CSS modules styling, and testing with Jest and React Testing Library

AI Agent: I'll create a comprehensive frontend skill for you...
[Creates skill with detailed instructions, examples, and best practices based on your description]

Benefits of Natural Language Creation:

• More detailed and customized skill content
• AI generates relevant examples and best practices
• Faster than manually writing everything
• Can specify exact requirements and conventions

What happens (both methods):

• A new directory is created: .blackbox/skills/frontend/
• A template SKILL.md file is created with:
  • YAML frontmatter (name and description)
  • Markdown sections for instructions, examples, and best practices

Step 3: Edit the Skill File

Open and edit the created skill file:

Location: .blackbox/skills/frontend/SKILL.md

Template content:

---
name: frontend
description: Brief description of what this skill does and when to use it
---

# Frontend

## Instructions

Provide clear, step-by-step guidance for Blackbox agents on how to use this skill effectively.

## Examples

Show concrete examples of using this skill in different scenarios.

## Best Practices

Document important guidelines, conventions, and best practices for this skill.

Edit it to add your knowledge:

---
name: frontend
description: Best practices for React and TypeScript frontend development, including component structure, state management, styling conventions, and testing approaches
---

# Frontend Development

## Instructions

When working on frontend code:

1. Use functional components with TypeScript
2. Implement proper prop typing with interfaces
3. Follow the project's component structure (components/, hooks/, utils/)
4. Use CSS modules for styling
5. Write tests for all components

## Examples

### Component Structure

\`\`\`typescript
interface ButtonProps {
  label: string;
  onClick: () => void;
  variant?: 'primary' | 'secondary';
}

export const Button: React.FC<ButtonProps> = ({ 
  label, 
  onClick, 
  variant = 'primary' 
}) => {
  return (
    <button 
      className={styles[variant]} 
      onClick={onClick}
    >
      {label}
    </button>
  );
};
\`\`\`

### State Management

\`\`\`typescript
const [count, setCount] = useState<number>(0);

const increment = useCallback(() => {
  setCount(prev => prev + 1);
}, []);
\`\`\`

## Best Practices

- Always define prop interfaces
- Use meaningful component and prop names
- Keep components small and focused (< 200 lines)
- Implement proper TypeScript typing
- Use CSS modules for component-specific styles
- Write unit tests for all components
- Use React.memo for expensive components

Step 4: List All Skills

See all available skills in your workspace:

/skill list

Output:

Available Skills:

• frontend
  Best practices for React and TypeScript frontend development
  Path: /workspace/.blackbox/skills/frontend/SKILL.md

• backend-api
  RESTful API design and implementation guidelines
  Path: /workspace/.blackbox/skills/backend-api/SKILL.md

Tip: Use /skill info <skill-name> to view full skill details.

Step 5: View Skill Details

View the complete content of a specific skill:

/skill info frontend

Output:

Skill: frontend

Description:
Best practices for React and TypeScript frontend development

Location:
/workspace/.blackbox/skills/frontend/SKILL.md

Full Content:
────────────────────────────────────────────────────────────
---
name: frontend
description: Best practices for React and TypeScript frontend development
---

# Frontend Development

## Instructions
[Full content displayed here...]
────────────────────────────────────────────────────────────

Step 6: Let the AI Agent Use Your Skills

Once you’ve created and edited skills, the AI agent will automatically:

1. Discover skills when you start a new CLI session
2. Evaluate relevance based on your task and skill descriptions
3. Load skills automatically when they’re relevant to your task
4. Apply knowledge from the skill to complete your task

Example interaction:

You: Create a new React button component with TypeScript

AI Agent: 
[Automatically loads the 'frontend' skill]
I'll create a React button component following the frontend best practices...

[Creates component with proper TypeScript interfaces, CSS modules, etc.]

Common Use Cases

Use Case 1: Domain-Specific Knowledge

Create skills for specific domains:

Using Commands:

/skill create python-testing
/skill create api-design
/skill create database-migrations
/skill create devops-deployment

Using Natural Language:

You: Create a Python testing skill that covers pytest, unittest, mocking with unittest.mock, fixtures, parametrized tests, coverage requirements (minimum 80%), and integration testing best practices

AI Agent: I'll create a comprehensive Python testing skill...

Use Case 2: Project-Specific Conventions

Create skills for your project’s specific patterns:

Using Commands:

/skill create project-structure
/skill create coding-standards
/skill create git-workflow

Using Natural Language:

You: Create a coding standards skill for our team that enforces: ESLint with Airbnb config, Prettier formatting, 2-space indentation, single quotes, no semicolons, max line length 100, and includes pre-commit hooks setup

AI Agent: I'll create a coding standards skill with your team's conventions...

Use Case 3: Technology-Specific Guides

Create skills for specific technologies:

Using Commands:

/skill create react-hooks
/skill create typescript-patterns
/skill create graphql-queries
/skill create docker-compose

Using Natural Language:

You: Create a React hooks skill covering useState, useEffect, useCallback, useMemo, useRef, custom hooks patterns, dependency arrays, and common pitfalls to avoid

AI Agent: I'll create a React hooks skill with comprehensive examples...

Use Case 4: Quick Skill Generation with AI

Let the AI agent handle the entire skill creation process:

You: I need a skill for GraphQL API development with Apollo Server, schema design, resolvers, data loaders, error handling, and authentication

AI Agent: I'll create a comprehensive GraphQL skill for you with all those topics covered, including code examples and best practices.

This approach is ideal when:

• You want to quickly bootstrap a skill
• You need comprehensive coverage of a topic
• You want the AI to suggest best practices you might not know
• You’re creating skills for technologies you’re learning

Tips and Best Practices

1. Use Natural Language for Complex Skills

For comprehensive skills, let the AI agent do the heavy lifting:

You: Create a skill for microservices architecture that includes service discovery, API gateway patterns, circuit breakers, distributed tracing, event-driven communication, and deployment strategies

AI Agent: I'll create a detailed microservices skill with all these patterns...

Benefits:

• Saves time on initial skill creation
• AI suggests industry best practices
• Comprehensive examples included automatically
• Easy to refine and customize afterward

2. Write Clear Descriptions

The description in the YAML frontmatter is crucial:

Good:

description: Comprehensive testing practices for Python projects using pytest, including unit tests, integration tests, fixtures, mocking strategies, and coverage requirements

Bad:

description: Testing stuff

3. Include Concrete Examples

Always provide code examples:

## Examples

### Good Example
\`\`\`python
def test_user_creation():
    user = User(name="John", email="[e-mail]")
    assert user.name == "John"
\`\`\`

4. Keep Skills Focused

Each skill should cover one specific domain:

• ✅ frontend-components - Component patterns
• ✅ frontend-state - State management
• ❌ frontend-everything - Too broad

5. Update Skills Regularly

As your project evolves, update your skills:

# Edit the skill file
vim .blackbox/skills/frontend/SKILL.md

# Restart CLI session to reload skills

6. Skill Naming Conventions

Use lowercase with hyphens:

• ✅ python-testing
• ✅ api-design
• ✅ react-hooks
• ❌ PythonTesting
• ❌ api_design

Troubleshooting

Problem: Skill not found

/skill info nonexistent-skill

Solution:

• Check the skill name with /skill list
• Ensure the skill directory exists in .blackbox/skills/
• Verify SKILL.md file exists in the skill directory

Problem: AI agent not using skills

Solution:

• Restart the CLI session to reload skills
• Make sure the skill description clearly indicates when to use it
• Verify the YAML frontmatter is properly formatted
• Check that the skill is relevant to your task

Problem: Invalid skill name error

/skill create My-Skill

Solution: Use only lowercase letters, numbers, and hyphens:

/skill create my-skill

Advanced Usage

Creating Multiple Related Skills

For complex projects, create a skill hierarchy:

/skill create frontend-components
/skill create frontend-hooks
/skill create frontend-testing
/skill create frontend-styling

Skill Templates

Create template skills for common patterns:

/skill create template-api-endpoint
/skill create template-react-component
/skill create template-database-model

Team Collaboration

Share skills with your team:

1. Commit .blackbox/skills/ to version control
2. Team members get skills when they clone the repo
3. Everyone benefits from shared knowledge

Quick Reference

Command	Description	Example
/skill	Show help	/skill
/skill list	List all skills	/skill list
/skill create <name>	Create new skill	/skill create frontend
/skill info <name>	View skill details	/skill info frontend

Next Steps

1. Create your first skill for your most common tasks
2. Edit the skill with your team’s best practices
3. Test it by asking the AI agent to perform related tasks
4. Iterate based on what works well
5. Share successful skills with your team

For more detailed information about BLACKBOX CLI features, see the Key Features documentation.