blackbox-skills

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

Naming Conventions

• Use lowercase letters, numbers, and hyphens only
• Valid: python-testing, api-design, react-hooks
• Invalid: PythonTesting, api_design, My Skill

CLI Commands

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

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