swiftpostlabs Create Skill
Purpose
Guide the agent through a short skill-creation wizard so a new skill is scoped correctly, named correctly, and authored to match this repository's standards.
When to use this skill
- The user wants to create a new skill.
- The user wants a wizard or guided intake for skill creation.
- Repeated repo guidance should be promoted into a reusable skill.
- The user knows the goal of the skill but not its final name, shape, or supporting files yet.
Scope boundaries
This tool creates one new skill. If the skill already exists, this is the wrong tool.
tool-sp-maintain-skills— updating, consolidating, or refreshing skills that already exist. If the request is really "an existing skill should cover this", hand off rather than creating a near-duplicate.tool-sp-make-skill-shareable— revisiting the portability of an existing skill. This tool setsvisibilityand dependencies at creation; that one fixes them afterwards.ref-sp-agents-skills-authoring— the quality rules this tool applies (structure, triggers, progressive disclosure). The rules live there; the intake flow lives here.ref-sp-agents-shareable-skills— the naming grammar, domain registry, and visibility tiers this tool fills in.
First Step
Read the repo's skill-authoring skill (ref-sp-agents-skills-authoring here, the requires dependency) before drafting the new skill.
Core Workflow
- Inspect the user's request and the existing skill set to avoid creating an overlapping duplicate.
- Ask only the missing intake questions needed to define the skill boundary, name, trigger, outputs, and shareability.
- Decide whether the new skill is
ref-...ortool-.... Refs put the domain in the name (ref-sp-<domain>-<topic>); tools usetool-sp-<verb>-<topic>and carry no domain. - Choose one
domainfrom the sharing spec's domain registry (owned byref-sp-agents-shareable-skills; its registry lives at that skill'sreferences/registry.json); open a registry issue rather than inventing an unregistered domain. - Decide
visibility(public/organization/repo-local), and list any hard skill dependencies. - Draft the smallest useful skill package.
- Add support files only when they improve progressive disclosure.
- Validate the new skill against the repo's skill-authoring checklist.
Defaults
- Default to one
SKILL.mdfile first. Addreferences/,assets/, orscripts/only when the workflow genuinely needs them. - Default to
ref-...when the skill mainly informs the agent. Default totool-...when the skill mainly drives an action-oriented workflow the user may invoke directly. - Follow the name grammar:
ref-sp-<domain>-<topic>(optional-templatesuffix for app blueprints) andtool-sp-<verb>-<topic>, such asref-sp-js-typescript,ref-sp-agents-security, orref-sp-dev-repo-conventions. - Set
metadata.shareable-skills.domainto a registered domain. Use the sharing spec's domain registry (owned byref-sp-agents-shareable-skills; its registry lives at that skill'sreferences/registry.json) for the current domain vocabulary; open a registry issue rather than inventing an unregistered domain. - Set
metadata.shareable-skills.visibility:publicfor portable knowledge (add a top-levellicense),organizationfor org-wide but process-specific skills,repo-localwhen it depends on this repo's concrete layout, policies, or wrappers. - Record hard dependencies in
metadata.shareable-skills.requires(comma-separated skill names); put soft/optional ones inmetadata.shareable-skills.suggests. - Keep hard dependencies few, especially for exportable (
organization/public) skills. - Keep the first version narrow. Do not solve adjacent workflows in the same skill unless they are operationally inseparable.
- Prefer asking a short focused set of questions over dumping a large questionnaire at once.
- Default generic examples, paths, and script names to clearly synthetic placeholders unless the skill is intentionally documenting a real repo surface.
Wizard Questions
Ask only the questions that are still unanswered after reading the user's request.
| Question area | What to ask | Why | When | Expected outcome |
|---|---|---|---|---|
| Skill goal | What repeated task or failure should this skill improve? | The skill boundary should come from a real job, not a topic label. | Always, unless the request already states the concrete job clearly. | The skill has one primary responsibility. |
| Skill role | Is this mostly reference guidance or a user-invoked action workflow? | The answer determines whether the name should start with ref- or tool-. |
When the role is not already obvious. | The skill gets the right prefix and interaction style. |
| Domain | Which registered domain does the skill belong to (agents, js, py, db, dev, ...)? |
Domain drives the name (ref-sp-<domain>-<topic>) and catalog grouping, and is validated against the registry. |
Always, since every skill carries a domain. | The skill has one registered domain, reflected in the name for refs. |
| Visibility | Is the skill public (portable knowledge), organization (org-wide but process-specific), or repo-local (depends on this repo)? |
Visibility sets export scope; public additionally requires a license. |
When transferability is not already obvious. | The skill gets the right visibility (and a license if public). |
| Skill dependencies | What other skills are hard requirements (requires) versus helpful-but-optional (suggests)? |
Exportable skills should keep hard dependencies few and explicit. | When the new skill relies on another skill's instructions. | requires is minimal and accurate; extras go in suggests. |
| Trigger surface | What kinds of user requests should activate this skill? | The description must match realistic intent, not internal implementation language. | When the triggering language is still vague. | The skill can be described with a specific activation sentence. |
| Scope boundaries | What should this skill explicitly not cover? | This prevents mixed skills that sprawl into adjacent domains. | When the request could overlap with an existing skill or a neighboring workflow. | The skill has clear exclusions and fewer false positives. |
| Support files | Will the skill need references, assets, or scripts? | The package should stay lean unless larger support files provide real value. | When the workflow looks long, branched, or format-sensitive. | The skill package has only the files it actually needs. |
| Validation | How should the new skill be checked once drafted? | The skill should ship with a concrete validation loop rather than unchecked prose. | When the workflow has an obvious checklist, trigger test, or output check. | The authoring pass ends with a focused validation step. |
Gotchas
- Do not ask every question in the table if the user already answered most of them.
- Do not create a
tool-...skill just because the skill mentions commands. A reference skill can still mention commands. - Do not encode shareability or namespace in the skill name. Use
metadata.shareable-skills.visibilityinstead. - Do not create support files preemptively if a concise
SKILL.mdis enough. - Do not copy real folder or script names from another repo into generic examples just because they came along with a borrowed template.
- If the new skill would substantially overlap with an existing one, stop and clarify whether the user wants an update instead of a new skill.
Validation
- Review the draft against the skill-authoring skill's checklist (
ref-sp-agents-skills-authoring; in this repo, itsreferences/checklist.md). - Confirm the
namematches the folder and follows the grammar (ref-sp-<domain>-<topic>ortool-sp-<verb>-<topic>). - Confirm
metadata.shareable-skills.domainis a registered domain,metadata.shareable-skills.visibilityis set (with a top-levellicensewhenpublic), andmetadata.shareable-skills.requires/.suggestsare comma-separated strings (metadata is string-to-string, not YAML lists). - Run the sharing-spec validator owned by
ref-sp-agents-shareable-skills(in this repo,node .agents/skills/ref-sp-agents-shareable-skills/scripts/validate-sharing.mts <skill-dir>, Node >= 22). - Confirm cross-skill references use repo-root-relative paths for skills in the same repo.
- Confirm generic examples use synthetic folder, feature, and script names rather than real names copied from another repo.
- Run a targeted error check on the new files before concluding.