> ## 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. # Author a skill > Create a custom Qodex skill by writing one markdown file with YAML frontmatter and a focused agent workflow. # 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. ```bash theme={null} 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. ```yaml 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 --- ``` Important choices: | Field | Why it matters | | ---------------- | ---------------------------------------------------------------------------- | | `id` | The contract Qodex uses to call the skill. Pick it carefully. | | `description` | The routing signal. Make it concrete and outcome-focused. | | `tools.include` | The safety boundary. Give the skill only the tools it needs. | | `maxIterations` | The work budget. Focused skills need less, broad discovery skills need more. | | `verifyFindings` | Keeps 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. ```markdown theme={null} # 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: ```text theme={null} 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: | Problem | What to adjust | | ------------------------------- | ------------------------------------------ | | Qodex does not choose the skill | Make the description more specific. | | Qodex does too much | Narrow the tools and add stop rules. | | Qodex misses a required check | Add the check as a numbered workflow step. | | Findings are inconsistent | Add or tighten the severity rubric. | | The run stops too soon | Increase `maxIterations` or split the job. | ## Next steps See every field a skill can use. Share the skill with a team or project. Copy patterns from shipped skills. Understand how Qodex chooses skills.