The .skill.md format

A .skill.md file tells Qodex how to run a specialized agent workflow. It has two parts:

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

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

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.

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.

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

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

Author a skill

Build a skill from a blank file.

Built-in skills

Use shipped skills as examples.

Distribute a skill

Share a skill with your team.

Skills overview

Understand where skills fit in Qodex.

Get started

Concepts

PR review

API testing

UI testing

Security testing

Run tests

Findings

Memory

Skills

Integrations

Self-hosted

Account

The .skill.md format

The .skill.md format

Where skills live

Core fields

Tool access

Runtime behavior

Sub-agents

MCP requirements

Severity rubrics

Prompt body

Minimal example

Override behavior

Next steps

Author a skill

Built-in skills

Distribute a skill

Skills overview

​The .skill.md format

​Where skills live

​Core fields

​Tool access

​Runtime behavior

​Sub-agents

​MCP requirements

​Severity rubrics

​Prompt body

​Minimal example

​Override behavior

​Next steps

Author a skill

Built-in skills

Distribute a skill

Skills overview

The .skill.md format

Where skills live

Core fields

Tool access

Runtime behavior

Sub-agents

MCP requirements

Severity rubrics

Prompt body

Minimal example

Override behavior

Next steps