Make Skill Shareable
Purpose
Guide the agent through reviewing an existing skill, deciding whether it should be shareable (organization/public) or repo-local, and updating the metadata or structure needed to support that decision.
When to use this skill
- A skill is missing
shareable-skills.visibility or shareable-skills.requires.
- The user wants to export, symlink, or otherwise reuse an existing skill outside this repo.
- The portability of a current skill is unclear.
- A repo-local skill might need to be split into a shared core plus a local layer.
Scope boundaries
This tool answers one question about one existing skill: how far can it travel, and does it need
splitting to get there. It sets visibility, requires/suggests, and the split decision.
tool-sp-create-skill — a new skill sets its own visibility at creation. Come here only to revisit
or backfill an existing one.tool-sp-maintain-skills — catalog-wide drift, duplication, and ownership. If several skills need
re-scoping at once, that is a maintenance pass, not a repeat of this one.ref-sp-agents-shareable-skills — the spec this tool applies: naming grammar, domain registry,
visibility tiers, dependency semantics, vendoring. Read it for the rules; use this tool to walk a
skill through them.ref-sp-agents-plugin-marketplaces and ref-sp-agents-skills-management — actually moving a
skill once it is cleared to travel. This tool only decides whether it may.
First Step
Read the repo's sharing-spec skill (ref-sp-agents-shareable-skills here) and its skill-authoring skill (ref-sp-agents-skills-authoring here) — both requires dependencies — before deciding whether the target skill can be exported cleanly.
Core Workflow
- Inspect the target skill's frontmatter, body, and support files.
- Ask only the missing questions needed to classify the skill's
visibility as repo-local, organization, or public.
- Identify only the hard skill dependencies.
- Decide whether the skill should stay whole, be marked repo-local, or be split into shared and local pieces.
- Update the skill metadata and structure accordingly.
- Validate the result with the shareable-skill checklist and linker dry-run when available.
Defaults
- Prefer
organization/public only when the skill can move with light adaptation and without hidden repo-only helpers.
- Prefer
repo-local when the skill depends on this repo's adoption flow, private layout, or special wrappers.
- Prefer splitting a mixed skill over forcing the whole skill to stay repo-local when the core guidance is reusable.
- Keep
shareable-skills.requires minimal and explicit.
Wizard Questions
Ask only the questions that are still unanswered after reading the target skill.
| Question area |
What to ask |
Why |
When |
Expected outcome |
| Portability boundary |
Can this skill move to another repo with only light adaptation, or does it rely on repo-only assumptions? |
This decides whether the skill should be organization/public or repo-local. |
Always, unless the answer is already obvious from the skill. |
The visibility decision is grounded in actual constraints. |
| Hard dependencies |
Which other skills are required for this skill to work correctly? |
The linker and export workflow need a minimal dependency chain. |
When the skill points to other skills or borrows their required workflow. |
shareable-skills.requires stays accurate and small. |
| Split decision |
If only part of the skill is reusable, should we split the reusable core from the repo-local layer? |
Splitting is often better than marking a broadly useful skill repo-local. |
When the skill mixes reusable guidance with local implementation detail. |
The skill structure matches the portability boundary. |
| Repo-local reason |
If the skill must stay local, what concise reason should be recorded? |
Future reviews are faster when the blocker is explicit. |
When repo-local would otherwise be surprising. |
shareable-skills.reason explains the local-only boundary. |
Gotchas
- Do not add optional related skills to
shareable-skills.requires.
- Do not mark a skill
organization or public if one of its hard dependencies is repo-local.
- Do not encode shareability in the skill name.
- If the skill would need major surgery to export cleanly, say so directly instead of pretending the metadata alone fixes it.
Validation
- Review the result against the sharing-spec skill's checklist (
ref-sp-agents-shareable-skills; in this repo, its references/checklist.md).
- Confirm the metadata keys stay within the spec's string-to-string model.
- Confirm every dependency in
shareable-skills.requires exists and is itself shareable.
- Run the repo's skill-linker dry-run once its linker CLI exists (in this repo,
uv run agentic-tools skills link <name> --global --dry-run).
1---2name: tool-sp-make-skill-shareable3description: Review an existing skill, decide whether it can be made shareable, and update its shareability metadata through a guided workflow. Use when: a skill lacks shareable-skills metadata, a user wants to export or symlink a skill, the current portability is unclear, or a repo-local skill might need to be split into a shared core.4license: MIT5---67# Make Skill Shareable89## Purpose1011Guide the agent through reviewing an existing skill, deciding whether it should be shareable (`organization`/`public`) or `repo-local`, and updating the metadata or structure needed to support that decision.1213## When to use this skill1415- A skill is missing `shareable-skills.visibility` or `shareable-skills.requires`.16- The user wants to export, symlink, or otherwise reuse an existing skill outside this repo.17- The portability of a current skill is unclear.18- A repo-local skill might need to be split into a shared core plus a local layer.1920## Scope boundaries2122This tool answers one question about **one existing skill**: how far can it travel, and does it need23splitting to get there. It sets `visibility`, `requires`/`suggests`, and the split decision.2425- `tool-sp-create-skill` — a new skill sets its own visibility at creation. Come here only to revisit26 or backfill an existing one.27- `tool-sp-maintain-skills` — catalog-wide drift, duplication, and ownership. If several skills need28 re-scoping at once, that is a maintenance pass, not a repeat of this one.29- `ref-sp-agents-shareable-skills` — the spec this tool applies: naming grammar, domain registry,30 visibility tiers, dependency semantics, vendoring. Read it for the rules; use this tool to walk a31 skill through them.32- `ref-sp-agents-plugin-marketplaces` and `ref-sp-agents-skills-management` — actually *moving* a33 skill once it is cleared to travel. This tool only decides whether it may.3435## First Step3637Read the repo's sharing-spec skill (`ref-sp-agents-shareable-skills` here) and its skill-authoring skill (`ref-sp-agents-skills-authoring` here) — both `requires` dependencies — before deciding whether the target skill can be exported cleanly.3839## Core Workflow40411. Inspect the target skill's frontmatter, body, and support files.422. Ask only the missing questions needed to classify the skill's `visibility` as `repo-local`, `organization`, or `public`.433. Identify only the hard skill dependencies.444. Decide whether the skill should stay whole, be marked repo-local, or be split into shared and local pieces.455. Update the skill metadata and structure accordingly.466. Validate the result with the shareable-skill checklist and linker dry-run when available.4748## Defaults4950- Prefer `organization`/`public` only when the skill can move with light adaptation and without hidden repo-only helpers.51- Prefer `repo-local` when the skill depends on this repo's adoption flow, private layout, or special wrappers.52- Prefer splitting a mixed skill over forcing the whole skill to stay repo-local when the core guidance is reusable.53- Keep `shareable-skills.requires` minimal and explicit.5455## Wizard Questions5657Ask only the questions that are still unanswered after reading the target skill.5859| Question area | What to ask | Why | When | Expected outcome |60| --- | --- | --- | --- | --- |61| Portability boundary | Can this skill move to another repo with only light adaptation, or does it rely on repo-only assumptions? | This decides whether the skill should be `organization`/`public` or `repo-local`. | Always, unless the answer is already obvious from the skill. | The visibility decision is grounded in actual constraints. |62| Hard dependencies | Which other skills are required for this skill to work correctly? | The linker and export workflow need a minimal dependency chain. | When the skill points to other skills or borrows their required workflow. | `shareable-skills.requires` stays accurate and small. |63| Split decision | If only part of the skill is reusable, should we split the reusable core from the repo-local layer? | Splitting is often better than marking a broadly useful skill repo-local. | When the skill mixes reusable guidance with local implementation detail. | The skill structure matches the portability boundary. |64| Repo-local reason | If the skill must stay local, what concise reason should be recorded? | Future reviews are faster when the blocker is explicit. | When `repo-local` would otherwise be surprising. | `shareable-skills.reason` explains the local-only boundary. |6566## Gotchas6768- Do not add optional related skills to `shareable-skills.requires`.69- Do not mark a skill `organization` or `public` if one of its hard dependencies is `repo-local`.70- Do not encode shareability in the skill name.71- If the skill would need major surgery to export cleanly, say so directly instead of pretending the metadata alone fixes it.7273## Validation7475- Review the result against the sharing-spec skill's checklist (`ref-sp-agents-shareable-skills`; in this repo, its `references/checklist.md`).76- Confirm the metadata keys stay within the spec's string-to-string model.77- Confirm every dependency in `shareable-skills.requires` exists and is itself shareable.78- Run the repo's skill-linker dry-run once its linker CLI exists (in this repo, `uv run agentic-tools skills link <name> --global --dry-run`).
swiftpostlabs