> ## Documentation Index
> Fetch the complete documentation index at: https://qodex.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# The .skill.md format

> A .skill.md file combines YAML frontmatter with a markdown prompt so Qodex can load a custom agent skill.

# The .skill.md format

A `.skill.md` file tells Qodex how to run a specialized agent workflow.

It has two parts:

1. YAML frontmatter for metadata and runtime settings.
2. A markdown body that becomes the skill's system prompt.

```text theme={null}
---
id: my-skill
name: My skill
description: What this skill should be used for.
---

# My skill

Follow this workflow...
```

## Where skills live

Built-in skills live in the platform `skills/` directory. Project skills live in the skills directory configured for that project.

At startup, Qodex loads built-in skills first and project skills second. If a project skill has the same `id` as a built-in skill, the project skill replaces it for that project.

Use the filename pattern `<id>.skill.md` so the file is easy to find. The runtime uses the `id` in frontmatter as the actual key.

## Core fields

| Field         | Type   | What it controls                                                                                       |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------ |
| `id`          | string | Stable identifier the coordinator calls, such as `api`, `ui`, or `security`. Use lowercase kebab-case. |
| `name`        | string | Human-readable label shown in the product. Defaults to `id` if omitted.                                |
| `version`     | string | Skill prompt version. Bump it when the behavior changes meaningfully.                                  |
| `description` | string | Routing signal. Qodex uses this to decide when the skill fits the user's request.                      |

Write the description like a real use case. "Tests GraphQL mutations for auth and validation bugs" is better than "GraphQL helper".

## Tool access

Skills can limit which tools the agent may call.

| Field              | Type      | What it does                                                                                                     |
| ------------------ | --------- | ---------------------------------------------------------------------------------------------------------------- |
| `tools.categories` | string\[] | Allows broad groups such as `browser`, `api`, `security`, `memory`, `scenario`, `reporting`, or `orchestration`. |
| `tools.include`    | string\[] | Allows only the exact tool names listed. Use this for tightly scoped skills.                                     |
| `tools.exclude`    | string\[] | Removes specific tools from the otherwise allowed set.                                                           |

Use `include` when safety matters. If the skill only needs API calls, scenario saving, and finding reports, give it only those tools.

## Runtime behavior

| Field            | Type    | What it does                                                          |
| ---------------- | ------- | --------------------------------------------------------------------- |
| `thinking`       | string  | Reasoning effort hint: `low`, `medium`, or `high`.                    |
| `maxIterations`  | number  | Maximum tool-call iterations for one skill run.                       |
| `planFirst`      | boolean | Forces the agent to outline the workflow before acting.               |
| `verifyFindings` | boolean | Requires findings to be verified before they are reported.            |
| `model`          | string  | Optional model override. Leave unset unless the skill truly needs it. |

Short skills can use a low iteration cap. Discovery, UI, API, security, and pentest skills usually need more room because they inspect real systems before reporting.

## Sub-agents

Use `decomposition` when a skill should split work into smaller jobs.

```yaml theme={null}
decomposition:
  enabled: true
  maxSubAgents: 4
  subSkills: [api-author]
```

| Field          | What it does                                               |
| -------------- | ---------------------------------------------------------- |
| `enabled`      | Allows the coordinator to spawn sub-agents for this skill. |
| `maxSubAgents` | Caps the number of sub-agents the skill may run.           |
| `subSkills`    | Lists which skill ids the parent may spawn.                |

This is how broad skills like `api` and `ui` delegate scenario authoring without losing the main coordinator thread.

## MCP requirements

Some skills need external capabilities.

```yaml theme={null}
mcp:
  required: [playwright]
  optional: [filesystem]
```

Use `required` for servers the skill cannot run without, such as browser control for UI work. Use `optional` for useful helpers that the skill can skip if missing.

## Severity rubrics

Skills that create findings should define a severity rubric.

```yaml theme={null}
severities:
  critical: "Auth bypass, data loss, remote code execution, or exposed credentials"
  high: "Privilege escalation, IDOR with data exposure, stored XSS"
  medium: "Reflected XSS, missing rate limiting, information disclosure"
  low: "Minor header, cookie, or hardening issues"
```

The runtime does not enforce this map by itself. The skill prompt uses it so findings stay consistent across runs.

## Prompt body

Everything after the closing `---` is the skill prompt.

Write it like instructions to a specialist:

* Explain the job in one sentence.
* Give the workflow in phases.
* State what counts as success.
* State what must never happen.
* Define when to stop and ask for clarification.
* Define what evidence is required before filing a finding.

There is no templating or include system. What you write is what the agent sees.

## Minimal example

```markdown theme={null}
---
id: db-migration
name: Database migration testing
version: 1.0.0
description: Tests database migrations against staging and reports unsafe schema changes.
tools:
  include: [api_call, memory_search, memory_store, scenario_save, finding_report]
thinking: medium
maxIterations: 40
verifyFindings: true
---

# Database migration testing

You are a database migration testing agent.

## Workflow

1. Read the migration and identify schema changes.
2. Apply it only against staging.
3. Verify the current app still works.
4. Roll it back and check for data loss.
5. Report only confirmed unsafe operations.

## Rules

- Never run against production.
- Stop if no staging connection is provided.
- Every finding must include the SQL line, impact, and suggested fix.
```

## Override behavior

Project skills replace built-in skills by `id`. They do not inherit omitted fields from the built-in skill.

If you override `security`, copy the shipped `security.skill.md` first, then edit it. Otherwise you may accidentally remove important tool rules, severity guidance, or verification requirements.

## Next steps

<CardGroup cols={2}>
  <Card title="Author a skill" icon="file-plus" href="/skills-authoring">
    Build a skill from a blank file.
  </Card>

  <Card title="Built-in skills" icon="layers" href="/skills-built-in">
    Use shipped skills as examples.
  </Card>

  <Card title="Distribute a skill" icon="share-2" href="/skills-distributing">
    Share a skill with your team.
  </Card>

  <Card title="Skills overview" icon="puzzle" href="/skills">
    Understand where skills fit in Qodex.
  </Card>
</CardGroup>