# Skill Format

A skill is a directory containing a specific set of files that define its metadata, instructions, tools, examples, and evaluation criteria.

---

## Directory Structure

```
my-skill/
├── metadata.json    # Required — name, version, tags, category, targets
├── SKILL.md         # Required — role, instructions, constraints, workflow
├── tools.json       # Required — tool definitions
├── examples.md      # Required — example inputs/outputs
└── eval.md          # Required — success criteria
```

---

## metadata.json

Defines the skill's identity and configuration.

```json
{
  "name": "my-skill",
  "version": "0.1.0",
  "title": "My Skill",
  "description": "What this skill does and who it's for",
  "author": "Your Name",
  "license": "MIT",
  "tags": ["engineering", "debugging"],
  "category": "engineering",
  "targets": ["codex", "opencode", "codra", "mcp"],
  "requiresTools": [],
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "repository": "https://github.com/user/repo",
  "homepage": "https://example.com"
}
```

### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Kebab-case identifier (e.g., `my-skill`) |
| `version` | string | Yes | Semver version (e.g., `0.1.0`) |
| `title` | string | Yes | Human-readable display name |
| `description` | string | Yes | What the skill does |
| `author` | string | Yes | Author name or org |
| `license` | string | Yes | License identifier (e.g., `MIT`) |
| `tags` | string[] | Yes | Searchable tags |
| `category` | string | Yes | One of the categories below |
| `targets` | string[] | Yes | Agent targets this skill supports |
| `requiresTools` | array | Yes | Tools the skill needs (can be empty) |
| `createdAt` | string | Yes | ISO 8601 timestamp |
| `updatedAt` | string | Yes | ISO 8601 timestamp |
| `repository` | string | No | Git repository URL |
| `homepage` | string | No | Project homepage |

### Categories

| Category | Description |
|----------|-------------|
| `engineering` | Code, debugging, architecture, DevOps |
| `marketing` | Content, launch, social, growth |
| `design` | UI, UX, visual design, typography |
| `writing` | Documentation, copywriting, editing |
| `devops` | Infrastructure, deployment, CI/CD |
| `research` | Analysis, investigation, data |
| `general` | General-purpose |
| `debugging` | Bug hunting, troubleshooting |
| `productivity` | Workflow, task management |

### Targets

| Target | Description |
|--------|-------------|
| `codex` | OpenAI Codex CLI |
| `opencode` | OpenCode CLI |
| `codra` | Codra platform |
| `tera` | Tera code generation |
| `mcp` | Model Context Protocol |
| `clipboard` | Copy to clipboard |
| `stdout` | Plain text output |
| `all` | General-purpose, no specific target |

### Validation Rules

- `name` must be kebab-case: `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`
- `version` must be semver-like: `^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?(\+[a-zA-Z0-9.]+)?$`
- `title` must be non-empty
- `description` must be non-empty
- `targets` must be a non-empty array

---

## SKILL.md

The main instruction file. Written in Markdown. This content is injected into the generated prompt under the "Instructions" section.

```markdown
## Role

You are an expert debugging specialist. You systematically identify, isolate, and resolve software defects.

## Workflow

### Phase 1: Reproduce
1. Gather the exact error message, stack trace, or unexpected behavior.
2. Identify the minimal steps to reproduce the issue.

### Phase 2: Isolate
1. Narrow down the scope — which component, module, or function is involved?
2. Form a hypothesis about the root cause.

### Phase 3: Patch
1. Implement the minimal fix that addresses the root cause.
2. Write or update tests to cover the bug scenario.

## Constraints

- Never guess — always verify with evidence.
- Prefer root cause fixes over symptom patches.
```

### Guidelines

- Start with a clear role definition
- Structure content with sections and phases
- Include constraints and boundaries
- Keep it focused and actionable

---

## tools.json

Defines the tools the skill expects the agent to have access to.

```json
[
  {
    "name": "read_file",
    "required": true,
    "description": "Read file contents for inspection"
  },
  {
    "name": "grep",
    "required": false,
    "description": "Search for patterns across files"
  },
  {
    "name": "run_command",
    "required": false,
    "description": "Execute a shell command"
  }
]
```

### Format

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Tool identifier |
| `required` | boolean | Whether the agent must have this tool |
| `description` | string | What the tool does |

Can also be wrapped in an object: `{"tools": [...]}`.

---

## examples.md

Example inputs and outputs. Used as reference material in the generated prompt.

```markdown
## Scenario

**Request:** I'm getting a TypeError: Cannot read property 'name' of undefined at line 42.

**Debugging Process:**
1. **Reproduce:** Running `npm test` — test fails at line 42.
2. **Isolate:** Error in `getUserDisplayName()`. Caller passes null.
3. **Fix:** Add null check.

```javascript
function getUserDisplayName(user) {
  if (!user) return 'Unknown User';
  return user.name;
}
```

4. **Verify:** All tests pass.
```

### Guidelines

- Include at least one complete scenario
- Show both input and expected output
- Use real-world examples when possible
- Include section headers like `## Example`, `## Scenario`, `## Request`

---

## eval.md

Success criteria and evaluation checks. Used to assess whether the skill's output meets expectations.

```markdown
## Success Criteria

- Bug is reproducible before fix.
- Root cause is identified, not just symptoms.
- Fix is minimal and targeted.
- No regressions introduced.
```

### Guidelines

- List concrete, measurable criteria
- Use action verbs (reproduced, identified, verified)
- Keep criteria specific to the skill's domain

---

## Loading Behavior

When loading a skill:

1. `metadata.json` and `SKILL.md` are **required** — missing either causes an error
2. `tools.json`, `examples.md`, and `eval.md` are **optional** — missing files are handled gracefully
3. Invalid JSON in `tools.json` or `metadata.json` causes a validation error
4. Empty files generate warnings but are still loadable