create-skill ยท diff
git:20261004.00bb0c5 to git:20261007.b35fc4b
31 added, 14 removed. Audit A to A.
---
name: create-skill
description: Author a new skill by discovering similar skills, studying their strengths and weaknesses, and synthesizing the best single skill from them. Use when the user says /create-skill, "create a skill", "build a skill", "make a skill for X", or wants a new skill grounded in the best existing examples rather than written from scratch.
allowed-tools: Bash, Read, Glob, Grep, Write, Edit
argument-hint: "<skill-name-or-concept>"
---
TODAY=!`date +%Y-%m-%d`
# Create Skill
Authors a new skill by first discovering existing skills that solve a similar problem, studying each one's strengths and weaknesses, then synthesizing the single best skill from what was learned.
- The premise is that a skill written from scratch is usually weaker than one built by combining the best techniques already proven across several existing skills. This skill automates that synthesis.
+ The premise is that a skill written from scratch is usually weaker than one built by combining the best techniques already proven across several existing skills.
+ This skill automates that synthesis.
## Prerequisites
- Working directory is the root of the `tomzx/agents` repository (the skill library root)
- `$1`: the name or concept of the skill to create (e.g. `create-skill`, or "a skill that summarizes meetings")
- The Skills CLI available as `npx skills` for searching and fetching candidates into a temp directory, never installed into this library (its global scope resolves to `~/.agents/skills`)
- No skill with the chosen name already exists at `skills/$1/SKILL.md`
## How This Skill Relates to Others
| Skill | Relationship |
|-------|--------------|
| `find-skills` | Delegated to for discovery. Its search logic (local library scan plus `npx skills find`) is the input to this skill. |
| `compare-skills` | Borrows the evaluation dimensions (instruction quality, structure, completeness, safety) for scoring candidates. |
| `improve-skill` | Shares the definition of "high-value, low-risk" and the hard constraint of confining edits to one skill directory. |
| `review-skills` | The new skill is checked against its duplicate detector at the end so the synthesis does not collide with an existing skill. |
## What Counts as a Strong Synthesis
A good synthesis takes the strongest part from each candidate and combines them into one coherent skill, not a patchwork of copied sections.
| Quality | What to Look For |
|---------|------------------|
| Best-of-breed sections | Take the clearest prerequisites, the most specific steps, the best output template, and the strongest examples, even if each comes from a different candidate |
| Conflict resolution | When candidates disagree, pick the approach that is clearer, more specific, and better aligned with the rest of the library, and record why |
| Structural coherence | One consistent voice, one section ordering, one frontmatter style, matching the house conventions of neighboring skills |
| Coverage | The union of edge cases and error handling from all candidates, deduplicated and pruned to what is realistic |
| Conventions | Repo style applied throughout: one sentence per line, no em-dashes, concise prose, correct frontmatter |
## What Counts as Churn (Avoid)
| Anti-pattern | Why to Avoid |
|--------------|--------------|
| Wholesale copy of one candidate | Defeats the purpose of synthesis and imports the candidate's weaknesses wholesale |
| Pasting sections back to back | Produces a patchwork with duplicated instructions, shifting voice, and broken cross-references |
| Speculative features the candidates lacked | Makes the skill larger with unproven edge cases; add only what the candidates justify |
| Renaming the concept mid-flight | Breaks the filename, frontmatter name, and README entry in one go |
| Importing external dependencies | A skill only works if it relies on tools already available in this environment |
| Installing candidates into this library | `npx skills add` writes into the project's `.agents/skills/`, and its global scope (`-g`) resolves to `~/.agents/skills`, which on this machine is a symlink to this repository; a global install therefore lands in `skills/<name>/` and overwrites any skill of the same name. Fetch candidates into a temp directory instead |
## Steps
### 1. Resolve and name the target skill
```
SKILL=$1
```
- If `$1` is empty, ask the user for the skill's purpose and propose a kebab-case name, then confirm. If `$1` already exists as a directory under `skills/`, stop and tell the user to run `/improve-skill $1` instead.
+ If `$1` is empty, ask the user for the skill's purpose and propose a kebab-case name, then confirm.
+ If `$1` already exists as a directory under `skills/`, stop and tell the user to run `/improve-skill $1` instead.
- Normalize the name to kebab-case if needed. Confirm the name does not already exist:
+ Normalize the name to kebab-case if needed.
+ Confirm the name does not already exist:
```bash
test -e "skills/$SKILL" && echo "::error::skills/$SKILL already exists" || echo "target: skills/$SKILL"
```
### 2. Discover candidate skills
Run the discovery step in two places.
**Local library.** Find skills whose name or description overlaps the concept:
```bash
grep -rli -e "$SKILL" skills/*/SKILL.md
```
Read the `name` and `description` of every match and keep those whose purpose genuinely overlaps, not merely those that mention the word.
**External ecosystem.** Search the open skills registry:
```bash
npx skills find "$SKILL"
```
- Also browse the [skills.sh leaderboard](https://skills.sh/) for well-known skills in the field. Search only: never install candidates into this library (see Step 3).
+ Also browse the [skills.sh leaderboard](https://skills.sh/) for well-known skills in the field.
+ Search only: never install candidates into this library (see Step 3).
- Collect the top candidates (typically three to six). Record for each: source, install count, GitHub stars, and a one-line summary of what it does. Apply the `find-skills` quality bar: prefer official sources and 1K+ installs; be skeptical of repos under 100 stars.
+ Collect the top candidates (typically three to six).
+ Record for each: source, install count, GitHub stars, and a one-line summary of what it does.
+ Apply the `find-skills` quality bar: prefer official sources and 1K+ installs; be skeptical of repos under 100 stars.
### 3. Gather the candidate sources
For each candidate, obtain the full `SKILL.md`:
- **Local**: read `skills/<name>/SKILL.md` directly, plus any files in its `references/` subdirectory if present.
- **External**: fetch the skill with the skills CLI into a temp location outside this repository, or read it without installing at all.
To read just the `SKILL.md`, use the non-installing form, which prints it to stdout:
```bash
npx skills use <owner>/<repo>@<skill>
```
When you also need the candidate's `references/` files, install it into a throwaway directory so the project scope is that directory rather than this repo:
```bash
CANDIDATE_DIR="/tmp/opencode/create-skill-candidates/<owner>-<repo>-<skill>"
mkdir -p "$CANDIDATE_DIR" && cd "$CANDIDATE_DIR"
npx skills add <owner>/<repo> --skill <skill> -y --copy
# files land in ./.agents/skills/<skill>/, read SKILL.md and references/ from there
```
- Never run `npx skills add` from the library root, never pass `-g`, and never run `npx skills update` here. The global scope resolves to `~/.agents/skills`, which on this machine is a symlink to this repository, so a global install writes straight into `skills/<name>/` and overwrites any skill sharing the name. The CLI is used here only to search and to read candidates into scratch space outside the repo.
+ Never run `npx skills add` from the library root, never pass `-g`, and never run `npx skills update` here.
+ The global scope resolves to `~/.agents/skills`, which on this machine is a symlink to this repository, so a global install writes straight into `skills/<name>/` and overwrites any skill sharing the name.
+ The CLI is used here only to search and to read candidates into scratch space outside the repo.
- If fewer than two usable candidates are found, say so and fall back to writing the skill from first principles using one or two neighboring skills as a style reference. Note that no synthesis basis existed.
+ If fewer than two usable candidates are found, say so and fall back to writing the skill from first principles using one or two neighboring skills as a style reference.
+ Note that no synthesis basis existed.
### 4. Analyze each candidate
- Read every gathered source end to end. For each candidate, score it along these dimensions (borrowed from `compare-skills`):
+ Read every gathered source end to end.
+ For each candidate, score it along these dimensions (borrowed from `compare-skills`):
| Dimension | Question |
|-----------|----------|
| Frontmatter | Does it have `name`, `description`, `allowed-tools`, `argument-hint`? Is the description a good trigger for the skill? |
| Prerequisites | Are inputs, tools, and preconditions stated concretely? |
| Steps | Are steps numbered, specific, and ordered, with clear acceptance between steps? |
| Output format | Is there a concrete template the agent can fill in? |
| Examples | Are there scenario-based examples covering the common and the edge cases? |
| Error handling | Are failure modes and recovery documented? |
| Safety | Are guards present before destructive or external side effects? |
| Reusability | Does it parameterize via arguments and dynamic values instead of hardcoding? |
For each candidate, write two short lists: its strongest section (worth adopting) and its weakest section (worth replacing or dropping).
### 5. Plan the synthesis
Before writing, decide the structure of the new skill by selecting, per section, which candidate supplies the strongest version:
| New skill section | Adopted from | Adaptation needed |
|-------------------|--------------|-------------------|
| Frontmatter | `<candidate>` | rename, retrigger description |
| Prerequisites | `<candidate>` | match this repo's working directory and tools |
| Steps | `<candidate>` | merge in edge cases from others |
| Output format | `<candidate>` | retemplate for this repo's conventions |
| Examples | `<candidate>` | rewrite in this repo's voice |
- Resolve every conflict between candidates by picking the clearer, more specific option and noting the reason. The plan is a table, not the prose. Do not start writing the skill until every section has a chosen source and every conflict has a resolution.
+ Resolve every conflict between candidates by picking the clearer, more specific option and noting the reason.
+ The plan is a table, not the prose.
+ Do not start writing the skill until every section has a chosen source and every conflict has a resolution.
### 6. Write the skill
Create the directory and write `skills/$SKILL/SKILL.md` from the plan:
```bash
mkdir -p "skills/$SKILL"
```
Apply this repo's conventions exactly:
- Frontmatter with `name`, `description`, and `allowed-tools` (and `argument-hint` if the skill takes arguments).
- `TODAY=!`date +%Y-%m-%d`` line only if the skill references the current date.
- One sentence per line where applicable.
- No em-dashes, use commas or parentheses.
- No comments or decorative noise.
- Section order matching neighboring skills (typically: Prerequisites, Steps, Output Format, Example Usage).
- Do not copy any candidate's prose verbatim unless it is a structural template (a table or a command). Rewrite the instructions in this repo's voice so the skill is coherent rather than a patchwork.
+ Do not copy any candidate's prose verbatim unless it is a structural template (a table or a command).
+ Rewrite the instructions in this repo's voice so the skill is coherent rather than a patchwork.
### 7. Verify the result
Re-read the finished skill end to end and confirm:
- The frontmatter parses (name, description, allowed-tools are valid).
- The `description` is a strong trigger: it lists the phrases a user would actually say and when to use the skill.
- Every step is specific and actionable, not vague handwaving.
- The output format and examples are concrete and consistent with the steps.
- No broken cross-references to other skills.
- Every change is confined to the new skill directory and the README index, and no existing skill was overwritten:
```bash
# Anything modified or deleted under skills/ outside $SKILL means a candidate was installed over it.
git status --porcelain -- skills/ | grep -v "^?? skills/$SKILL/" | grep -v "^ M skills/$SKILL/" \
| grep -v "^A skills/$SKILL/" && echo "::error::Existing skill modified or deleted; a candidate may have been installed over it" \
|| echo "No existing skill overwritten"
```
### 8. Check for duplicates
- Run the duplicate check from `review-skills` against the new skill: compare its name and description against every other skill in the library. If a near-duplicate is found, stop and ask the user whether to merge, rename, or document an explicit scope boundary before continuing.
+ Run the duplicate check from `review-skills` against the new skill: compare its name and description against every other skill in the library.
+ If a near-duplicate is found, stop and ask the user whether to merge, rename, or document an explicit scope boundary before continuing.
### 9. Register the skill
- Update `README.md` so the skills index stays in sync (required by `AGENTS.md`). Add one row to the most fitting thematic table:
+ Update `README.md` so the skills index stays in sync (required by `AGENTS.md`).
+ Add one row to the most fitting thematic table:
```markdown
| `/$SKILL` | <one-line purpose matching the table's voice> |
```
Increment the skill-count badge in the README header (`skills-N`).
Do not edit `.github/llmaw/flows.yml`; this skill does not participate in an automated flow.
### 10. Summarize
Print a short summary of what was synthesized and from where:
```
## Create Skill: {SKILL} ({TODAY})
Candidates studied:
- <candidate> (<source>): adopted <section>; dropped <section>
- <candidate> (<source>): adopted <section>; dropped <section>
Conflicts resolved:
- <conflict>: chose <approach> because <reason>
Wrote skills/{SKILL}/SKILL.md and registered it in README.md.
```
If no candidates were found, state that the skill was written from first principles with a style reference to `<neighbor-skill>`.
## Output Format
- The skill itself is the output. It must conform to this skeleton:
+ The skill itself is the output.
+ It must conform to this skeleton:
```markdown
---
name: <skill-name>
description: <One or two sentences. State what the skill does and the trigger phrases a user would say. Start with a verb.>
allowed-tools: <comma-separated tools this skill needs>
argument-hint: "<signature>"
---
TODAY=!`date +%Y-%m-%d` // only if the skill uses today's date
# <Skill Title>
<One-paragraph summary of what the skill does and why it exists.>
## Prerequisites
- <concrete inputs, tools, and preconditions>
## Steps
### 1. <step>
<specific instructions>
### 2. <step>
<specific instructions>
## Output Format
<concrete template or artifact the skill produces>
## Example Usage
**Scenario 1: <title>**
<walkthrough>
```
## Example Usage
**Scenario 1: Create a skill grounded in the ecosystem**
```
/create-skill summarize-meeting
```
Discovers three meeting-summary skills (two local, one on skills.sh with 12K installs), studies each, adopts the external skill's transcript-parsing steps and the local skill's output template, resolves a conflict on output format by choosing structured markdown, and writes `skills/summarize-meeting/SKILL.md`.
**Scenario 2: No good candidates exist**
```
/create-skill classify-emoji-sentiment
```
- Finds no usable candidates in the library or the registry. Falls back to writing the skill from first principles, using `triage-issue` as a style reference for its classification steps, and notes in the summary that no synthesis basis existed.
+ Finds no usable candidates in the library or the registry.
+ Falls back to writing the skill from first principles, using `triage-issue` as a style reference for its classification steps, and notes in the summary that no synthesis basis existed.
**Scenario 3: Candidate already exists locally**
```
/create-skill git-commit
```
Detects `skills/git-commit/` already exists and stops, suggesting `/improve-skill git-commit` instead of overwriting a working skill.
## Useful Commands Reference
| Command | Purpose |
|---------|---------|
| `npx skills find <query>` | Search the external skills registry for candidates |
| `npx skills use <owner>/<repo>@<skill>` | Print a candidate's `SKILL.md` to stdout without installing it |
| `npx skills add <owner>/<repo> --skill <skill> -y --copy` | Install a candidate into a temp directory (run there, never in the library root, never with `-g`) |
| `npx skills update` | Do NOT run: global scope resolves to this repo and can overwrite skills |
| `grep -rli -e "<term>" skills/*/SKILL.md` | Find local skills mentioning a term |
| `test -e skills/<name>` | Check whether a skill directory already exists |
| `git diff --name-only` | Confirm changes stayed inside the skill directory |