| name | blackbox-skills |
| description | Guides creating, managing, and authoring Blackbox AI skills, including the .blackbox/skills/ directory structure, /skill CLI commands, and cross-platform skill compatibility with both Blackbox AI and Claude Code. Activates when building or organizing skills.
|
| metadata | {"author":"tradecraft","version":"1.0.0"} |
Blackbox AI Skills (Meta-Skill)
Skills are reusable knowledge packages that augment Blackbox AI agents with domain-specific expertise. This meta-skill teaches you how to create, manage, and organize skills for the Blackbox AI ecosystem.
When to Use This Skill
- Creating new Blackbox AI skills with
/skill create
- Understanding the
.blackbox/skills/ directory structure
- Writing effective SKILL.md files with proper frontmatter
- Managing skills with
/skill list and /skill info
- Building skills compatible with both Blackbox AI and Claude Code
- Organizing team-shared skills via version control
Quick Start
Create a Skill
/skill create api-design
Output:
✓ Skill 'api-design' created successfully!
Location: /workspace/.blackbox/skills/api-design/SKILL.md
Edit the Skill
Open .blackbox/skills/api-design/SKILL.md and add your content:
---
name: api-design
description: REST API design patterns and best practices for Express/Fastify
---
## Instructions
- Use RESTful naming conventions (plural nouns for resources)
- Always validate input with Zod schemas
- Return consistent error response format
## Examples
```typescript
// Good: POST /api/users
// Bad: POST /api/createUser
Best Practices
- Use HTTP status codes correctly (201 for created, 204 for no content)
- Version APIs via URL prefix (/v1/, /v2/)
- Include pagination for list endpoints
### Use the Skill
Skills are automatically discovered and activated based on task relevance. No manual invocation needed — just start working on an API design task and the skill loads contextually.
## Core Concepts
### Directory Structure
.blackbox/
└── skills/
├── frontend/
│ └── SKILL.md
├── api-design/
│ └── SKILL.md
├── testing/
│ └── SKILL.md
└── deployment/
└── SKILL.md
### SKILL.md Format
Every skill requires a `SKILL.md` file with YAML frontmatter:
```markdown
---
name: skill-name
description: Clear description of purpose and when to use this skill
metadata:
author: your-name
version: "1.0.0"
---
## Instructions
Step-by-step guidance for the AI agent.
## Examples
Concrete code samples demonstrating practical application.
## Best Practices
Important guidelines, conventions, and constraints.
Frontmatter Fields
| Field | Required | Description |
|---|
name | Yes | Skill identifier (lowercase with hyphens) |
description | Yes | Clear explanation of purpose and triggers |
metadata.author | No | Skill author |
metadata.version | No | Semantic version |
Naming Conventions
- Use lowercase letters, numbers, and hyphens only
- Valid:
python-testing, api-design, react-hooks
- Invalid:
PythonTesting, api_design, My Skill
CLI Commands
| Command | Description |
|---|
/skill | Display help and available commands |
/skill list | List all skills with descriptions and paths |
/skill create <name> | Generate new skill directory with template |
/skill info <name> | View complete skill content and metadata |
Common Patterns
Domain-Specific Skills
---
name: react-performance
description: React performance optimization patterns including memoization, lazy loading, and render optimization
---
## Instructions
- Use React.memo() for components that receive stable props
- Implement code splitting with dynamic imports
- Use useCallback for event handlers passed as props
- Prefer useMemo for expensive computations
## Examples
```tsx
// Lazy load heavy components
const HeavyChart = lazy(() => import('./HeavyChart'));
// Memoize expensive computations
const sortedItems = useMemo(() =>
items.sort((a, b) => a.name.localeCompare(b.name)),
[items]
);
### Project Convention Skills
```markdown
---
name: project-conventions
description: Team coding conventions and project-specific patterns
---
## Instructions
- Use barrel exports only for public API surfaces
- All API routes must validate input with Zod
- Database queries use the repository pattern
- Error responses follow RFC 7807 Problem Details format
## Examples
```typescript
// Error response format
{
"type": "https://api.example.com/errors/not-found",
"title": "Resource Not Found",
"status": 404,
"detail": "User with ID 123 was not found"
}
### Reference Skills (with subdirectories)
Skills can include reference documents alongside the SKILL.md:
.blackbox/skills/
└── database/
├── SKILL.md
└── references/
├── schema.md
└── migrations.md
## Cross-Platform Compatibility
Skills work in both Blackbox AI and Claude Code with minimal adaptation:
### Blackbox AI Native
Skills live in `.blackbox/skills/` and are auto-discovered.
### Claude Code
Skills live in `~/.claude/skills/` (global) or `.claude/skills/` (project-local). Use the install script to symlink:
```bash
# From the skills repo
bash scripts/install-claude.sh
Shared Frontmatter
Both systems use YAML frontmatter with name and description fields. Use the union of both systems' fields for maximum compatibility.
Best Practices
- Clear descriptions — Detailed descriptions enable accurate skill discovery and activation
- Focused scope — Each skill should address one domain or concern
- Concrete examples — Include working, copy-pasteable code samples
- Regular updates — Revise skills as standards evolve; restart sessions to reload
- Team collaboration — Commit
.blackbox/skills/ to version control for team sharing
- Skill hierarchy — Create related skill sets for complex projects
- Natural language creation — You can ask the AI to generate skill content conversationally
References
- See
references/skill-format.md for detailed format specification
