# Blackbox Skills

> 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.

- Skill: `webrenew/blackbox-skills` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add webrenew/blackbox-skills`
- Raw SKILL.md: https://api.skillmd.com/api/skills/webrenew/blackbox-skills/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: webrenew (https://skillmd.com/u/webrenew)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/webrenew/blackbox-skills

---


# 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:

```markdown
---
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

```markdown
---
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

1. **Clear descriptions** — Detailed descriptions enable accurate skill discovery and activation
2. **Focused scope** — Each skill should address one domain or concern
3. **Concrete examples** — Include working, copy-pasteable code samples
4. **Regular updates** — Revise skills as standards evolve; restart sessions to reload
5. **Team collaboration** — Commit `.blackbox/skills/` to version control for team sharing
6. **Skill hierarchy** — Create related skill sets for complex projects
7. **Natural language creation** — You can ask the AI to generate skill content conversationally

## References

- See `references/skill-format.md` for detailed format specification