Skip to main content

​
Author a skill

Create a skill when you want Qodex to handle a workflow that is specific to your product, stack, or team. A good skill turns expert judgment into repeatable agent behavior. Instead of explaining the same compliance rule, auth pattern, or testing checklist in every prompt, you write it once and let Qodex call it when the request matches.

​
Good use cases

Skills work best for repeatable jobs with clear rules:
  • Testing GraphQL mutations and subscriptions.
  • Checking gRPC services.
  • Validating database migrations.
  • Applying an internal security or compliance rubric.
  • Testing a proprietary auth flow.
  • Producing reports in your team’s required format.
If the work is one-off, a normal chat prompt may be enough. If the work should become part of how Qodex thinks for a project, write a skill.

​
1. Pick a focused job

Start with the behavior you want, not the file. Good skill descriptions sound like this:
  • “Tests database migrations against staging and reports unsafe schema changes.”
  • “Checks Stripe webhook handlers for replay, signature, and idempotency bugs.”
  • “Creates GraphQL API scenarios for queries and mutations behind token auth.”
Avoid broad descriptions like “helps with backend testing”. Qodex uses the description to decide whether the skill applies.

​
2. Create the file

Use a stable, lowercase id. 
touch skills/db-migration.skill.md
The filename should match the id for readability, but the runtime keys off the id field in frontmatter.

​
3. Add frontmatter

Start with the fields Qodex needs to identify, route, and constrain the skill. 
---
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
---
Important choices:
FieldWhy it matters
idThe contract Qodex uses to call the skill. Pick it carefully.
descriptionThe routing signal. Make it concrete and outcome-focused.
tools.includeThe safety boundary. Give the skill only the tools it needs.
maxIterationsThe work budget. Focused skills need less, broad discovery skills need more.
verifyFindingsKeeps the skill from reporting unconfirmed issues.
If the skill needs to split work into sub-agents, add a decomposition block. Most first custom skills do not need it.

​
4. Write the prompt body

Everything after the closing --- is the system prompt Qodex gives the skill. Use direct instructions. The best skill prompts include:
  • The role: what the agent is responsible for.
  • The workflow: the phases it must follow.
  • Success criteria: what must be true before it says the task is done.
  • Stop rules: when it should ask for more information.
  • Evidence rules: what proof is required before filing a finding.
  • Safety rules: what the skill must never do.
# 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 application 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.

​
5. Test it from chat

Restart the Qodex server or reload the runtime so the loader sees the new file. Then ask for a task that clearly matches the skill description: 
Test the migration in db/migrations/20260601_add_user_archive_flag.sql against staging.
Watch for three things:
  • Qodex should choose your skill.
  • Tool calls should stay inside the tools you allowed.
  • The output should follow the workflow and evidence rules you wrote.
If Qodex chooses the wrong skill, sharpen the description. If it wanders, tighten tools.include. If it stops too early, raise maxIterations or make the workflow clearer.

​
6. Iterate

Skills are intentionally easy to revise. Edit the markdown, bump the version when behavior changes, and test again. When behavior is off, change the skill instead of working around it in every prompt:
ProblemWhat to adjust
Qodex does not choose the skillMake the description more specific.
Qodex does too muchNarrow the tools and add stop rules.
Qodex misses a required checkAdd the check as a numbered workflow step.
Findings are inconsistentAdd or tighten the severity rubric.
The run stops too soonIncrease maxIterations or split the job.

​
Next steps

The .skill.md format

See every field a skill can use.

Distribute a skill

Share the skill with a team or project.

Built-in skills

Copy patterns from shipped skills.

Skills overview

Understand how Qodex chooses skills.