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.- Add the skill under
skills/in the project repo. - Configure the Qodex project to read that directory.
- Review skill changes in PRs like any other code.
- Let the next agent run load the updated file.
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.
id as the built-in skill.
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: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.