Skip to main content

​
Distribute a skill

A skill is one file, so distribution is simple: put the .skill.md file where the target Qodex project can load it. The best distribution path depends on whether the skill is project-specific, experimental, or meant to replace a built-in behavior.

​
Distribution paths

​
Commit to the project repo

This is the strongest default for real teams.
  1. Add the skill under skills/ in the project repo.
  2. Configure the Qodex project to read that directory.
  3. Review skill changes in PRs like any other code.
  4. Let the next agent run load the updated file.
This keeps the skill near the application it tests. If the app changes, the skill can change in the same PR.

​
Share the file directly

Direct sharing is useful when someone wants to try a skill before adopting it. There is no package install step. Send the .skill.md file through Slack, a gist, a PR comment, or another internal channel. The recipient places it in their project skills directory. Use this for experiments. For long-term use, commit the file somewhere versioned.

​
Override a built-in skill

Override when the shipped skill is mostly right but your project needs different rules. Examples:
  • A stricter security severity rubric.
  • A custom API auth pattern.
  • A UI testing workflow that must collect extra artifacts.
  • A report format required by your team.
To override, create a project skill with the same id as the built-in skill.
Overrides replace the built-in skill completely. They do not inherit missing fields or merge prompt sections.
Copy the shipped skill first, then edit the parts that should differ. This preserves the existing workflow, tool limits, and verification rules.

​
Choosing the right path

​
Registry roadmap

The planned skill registry will make reusable skills installable by name, similar to packages:
Until that ships, repo-based distribution is the most reliable path for production use.

​
Next steps

Author a skill

Create the skill before sharing it.

The .skill.md format

Confirm the file is structured correctly.

Built-in skills

Find the shipped skill you may want to override.

Skills overview

See how skills fit into Qodex.