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

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

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