Create Portable Skill
Create skills that another agent can actually use. A skill is a packaged workflow, not a rule, essay, prompt dump, or product pitch.
1. Classify the candidate
Before writing files, decide what the artifact is:
| Type |
Definition |
Destination |
| Packaged skill |
Multi-step workflow, concrete output, portable dependencies |
skills/<name>/ |
| Draft skill |
Real workflow but incomplete body, name, trigger, or bundled files |
skills/<name>/ with explicit draft status |
| Kit |
Installable system made of hooks, templates, multiple files, or multiple skills |
kits/ |
| Rule/pattern |
Principle, invariant, hook pattern, or one-step guardrail |
rules/ or docs, not skills/ |
| Reference |
Background methodology a skill can point to |
reference/ |
| Reject |
Too vague, too local, not a workflow, no crisp trigger |
Do not catalog |
If it could be one bullet in a rules file, do not make it a skill.
2. Apply the skill bar
A packaged skill must pass all five:
- Workflow: at least three ordered moves, or one staged judgment process with a clear start and end.
- Non-obvious know-how: sequence, traps, tradeoffs, or templates an agent would not reliably infer.
- Concrete output: writes, changes, submits, audits, or produces a named artifact.
- Sharp trigger:
description: names real user phrasings and when to use it.
- Portable package: no private paths, secrets, project-only state, or hidden local helper dependencies.
3. Name it plainly
Use lowercase hyphen-case. Prefer verb-led names that say the output:
- Good:
write-project-vision-handoff, critique-vision-handoff, hunt-research-sources
- Bad: clever names, metaphors, acronyms, or one-word vibes
Folder name and frontmatter name: must match exactly.
4. Write the trigger first
The frontmatter description: is the discovery surface. It must include:
- What the skill does
- When to use it
- Real user phrasings when possible
- The concrete output
Use third person and be specific. The body loads only after the skill triggers, so do not hide trigger logic in the body.
5. Package the folder
Minimum:
skills/<name>/
SKILL.md
agents/openai.yaml
Add bundled files only when they directly support execution:
reference/ for templates, output formats, checklists, or long examplesscripts/ for deterministic repeatable operationsassets/ for templates or media used in outputs
Do not add README, changelog, installation guide, or extra docs inside the skill folder.
6. Validate
Check:
SKILL.md starts with YAML frontmatter.- Frontmatter has only
name: and description:.
name: matches folder.- Referenced files exist.
- Private names, absolute user paths, secrets, and project-only assumptions are removed.
agents/openai.yaml has a short display name, short description, default prompt, and invocation policy.
7. Update the catalog
Add the skill to exactly one primary category. If it is draft, local-wrapper, kit, rule, reference, or reject, say that honestly. The catalog is a shelf, not a dream board.
1---2name: create-portable-skill3description: Create, audit, or package a portable Claude/Codex skill. Use when building a new skill, converting an existing workflow into a reusable skill, reviewing whether something is a real skill or just a rule/reference/kit, or preparing a skills repository catalog.4---56# Create Portable Skill78Create skills that another agent can actually use. A skill is a packaged workflow, not a rule, essay, prompt dump, or product pitch.910## 1. Classify the candidate1112Before writing files, decide what the artifact is:1314| Type | Definition | Destination |15|---|---|---|16| Packaged skill | Multi-step workflow, concrete output, portable dependencies | `skills/<name>/` |17| Draft skill | Real workflow but incomplete body, name, trigger, or bundled files | `skills/<name>/` with explicit draft status |18| Kit | Installable system made of hooks, templates, multiple files, or multiple skills | `kits/` |19| Rule/pattern | Principle, invariant, hook pattern, or one-step guardrail | `rules/` or docs, not `skills/` |20| Reference | Background methodology a skill can point to | `reference/` |21| Reject | Too vague, too local, not a workflow, no crisp trigger | Do not catalog |2223If it could be one bullet in a rules file, do not make it a skill.2425## 2. Apply the skill bar2627A packaged skill must pass all five:28291. **Workflow:** at least three ordered moves, or one staged judgment process with a clear start and end.302. **Non-obvious know-how:** sequence, traps, tradeoffs, or templates an agent would not reliably infer.313. **Concrete output:** writes, changes, submits, audits, or produces a named artifact.324. **Sharp trigger:** `description:` names real user phrasings and when to use it.335. **Portable package:** no private paths, secrets, project-only state, or hidden local helper dependencies.3435## 3. Name it plainly3637Use lowercase hyphen-case. Prefer verb-led names that say the output:3839- Good: `write-project-vision-handoff`, `critique-vision-handoff`, `hunt-research-sources`40- Bad: clever names, metaphors, acronyms, or one-word vibes4142Folder name and frontmatter `name:` must match exactly.4344## 4. Write the trigger first4546The frontmatter `description:` is the discovery surface. It must include:4748- What the skill does49- When to use it50- Real user phrasings when possible51- The concrete output5253Use third person and be specific. The body loads only after the skill triggers, so do not hide trigger logic in the body.5455## 5. Package the folder5657Minimum:5859```text60skills/<name>/61 SKILL.md62 agents/openai.yaml63```6465Add bundled files only when they directly support execution:6667- `reference/` for templates, output formats, checklists, or long examples68- `scripts/` for deterministic repeatable operations69- `assets/` for templates or media used in outputs7071Do not add README, changelog, installation guide, or extra docs inside the skill folder.7273## 6. Validate7475Check:7677- `SKILL.md` starts with YAML frontmatter.78- Frontmatter has only `name:` and `description:`.79- `name:` matches folder.80- Referenced files exist.81- Private names, absolute user paths, secrets, and project-only assumptions are removed.82- `agents/openai.yaml` has a short display name, short description, default prompt, and invocation policy.8384## 7. Update the catalog8586Add the skill to exactly one primary category. If it is draft, local-wrapper, kit, rule, reference, or reject, say that honestly. The catalog is a shelf, not a dream board.
ariaxhan