Distribute a skill

Share Qodex skills by committing them to a project repo, copying the file directly, or overriding a built-in skill for a project.

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

Path	Best for	How it works
Commit to the project repo	Team-owned skills that should version with the codebase.	Store the file under a repo skills/ directory and configure Qodex to read it.
Share the file directly	Quick trials or one-off sharing.	Send the .skill.md file to another user and have them drop it into their project skills directory.
Override a built-in	Changing shipped behavior for one project.	Copy the built-in skill, keep the same id, and edit the project copy.
Registry	Reusable public or org-wide skills.	Planned. Not shipped yet.

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

Situation	Recommended path
One project needs one custom workflow	Commit to that project’s repo.
Several projects need the same internal skill	Keep it in a shared repo and sync it into each project.
A colleague wants to test your skill	Share the file directly.
You need to adjust a shipped skill	Override the built-in by id.
You want community-style installation	Wait for the planned registry.

Registry roadmap

The planned skill registry will make reusable skills installable by name, similar to packages:

qodex install @myorg/graphql-testing

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.