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.
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.
Important choices: 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.

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

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