Skip to main content

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

FieldTypeWhat it controls
idstringStable identifier the coordinator calls, such as api, ui, or security. Use lowercase kebab-case.
namestringHuman-readable label shown in the product. Defaults to id if omitted.
versionstringSkill prompt version. Bump it when the behavior changes meaningfully.
descriptionstringRouting 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.
FieldTypeWhat it does
tools.categoriesstring[]Allows broad groups such as browser, api, security, memory, scenario, reporting, or orchestration.
tools.includestring[]Allows only the exact tool names listed. Use this for tightly scoped skills.
tools.excludestring[]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

FieldTypeWhat it does
thinkingstringReasoning effort hint: low, medium, or high.
maxIterationsnumberMaximum tool-call iterations for one skill run.
planFirstbooleanForces the agent to outline the workflow before acting.
verifyFindingsbooleanRequires findings to be verified before they are reported.
modelstringOptional 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]
FieldWhat it does
enabledAllows the coordinator to spawn sub-agents for this skill.
maxSubAgentsCaps the number of sub-agents the skill may run.
subSkillsLists 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.