Skip to content
Skills Library
AI & agents · Building & coding

skill-smith

/skill-smith

Create, update or adapt an agent skill (SKILL.md) so the next session does the task right on the first try. CREATE turns a workflow from this session (or notes, or a fresh idea) into a skill; UPDATE folds a correction or lesson into every skill it affects, with a diff per file; ADAPT ports an external skill (GitHub, local disk, pasted) with a license check and attribution. Prefers patching an existing skill over making a new one. Use when the user says "skill-smith", "skillify", "make this a skill", "turn this into a skill", "update the X skill", "remember this in the skill", "propagate this l

Repository
skill-smith ↗
Licence
MIT
Last repository change
03.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
6
Scripts
0
HTML comments
0
URLs in SKILL.md
12
Deprecation

No signals detected. Repository changed on 03.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Create, update or adapt an agent skill (SKILL.md) so the next session does the task right on the first try. CREATE turns a workflow from this session (or notes, or a fresh idea) into a skill; UPDATE folds a correction or lesson into every skill it affects, with a diff per file; ADAPT ports an external skill (GitHub, local disk, pasted) with a license check and attribution. Prefers patching an existing skill over making a new one. Use when the user says "skill-smith", "skillify", "make this a skill", "turn this into a skill", "update the X skill", "remember this in the skill", "propagate this l

Triggers from the description

skill-smithskillifymake this a skillturn this into a skillupdate the X skillremember this in the skill
Original author description

Create, update or adapt an agent skill (SKILL.md) so the next session does the task right on the first try. CREATE turns a workflow from this session (or notes, or a fresh idea) into a skill; UPDATE folds a correction or lesson into every skill it affects, with a diff per file; ADAPT ports an external skill (GitHub, local disk, pasted) with a license check and attribution. Prefers patching an existing skill over making a new one. Use when the user says "skill-smith", "skillify", "make this a skill", "turn this into a skill", "update the X skill", "remember this in the skill", "propagate this l

How it works

  1. Step 0 — Read your own wiki, then pick the mode
  2. Step 1 — The gate: is this worth a skill at all?
  3. Step 2 — Find the home: patch before you create
  4. Step 3 — Write it well
  5. Step 4 — UPDATE: one lesson, every skill it touches
  6. Step 5 — Version and changelog
  7. Step 6 — Check, then hand over
  8. Step 7 — Keep your own wiki
Original SKILL.md headings · 129 lines, 1,413 words
SKILL.md preview
---
name: skill-smith
description: Create, update or adapt an agent skill (SKILL.md) so the next session does the task right on the first try. CREATE turns a workflow from this session (or notes, or a fresh idea) into a skill; UPDATE folds a correction or lesson into every skill it affects, with a diff per file; ADAPT ports an external skill (GitHub, local disk, pasted) with a license check and attribution. Prefers patching an existing skill over making a new one. Use when the user says "skill-smith", "skillify", "make this a skill", "turn this into a skill", "update the X skill", "remember this in the skill", "propagate this lesson", "port/adapt this skill", or corrects how a class of task should be done.
metadata:
  version: 0.1.0
  license: MIT
---

# skill-smith — forge, temper and port skills

A skill is **the instructions for doing a class of task the most efficient and correct way, to this user's specifications**: the steps in order, the commands that work, the decision points, how the result should look, and the pitfalls that cost time. A future session must be able to follow it and get it right the first time. Everything below serves that.

Sources and credits: [ATTRIBUTION.md](ATTRIBUTION.md). Changes: [CHANGELOG.md](CHANGELOG.md). Its own memory: [.wiki/](.wiki/README.md).

## Step 0 — Read your own wiki, then pick the mode

1. `rg -n -i '<keyword>' <this skill's folder>/.wiki` (e.g. `~/.claude/skills/skill-smith/.wiki`) for lessons about running skill-smith itself (it is short; read only what matches).
2. Route by signal; if it is ambiguous, ask. Never guess between CREATE and ADAPT when an external URL is involved.

| Signal | Mode |
|---|---|
| A workflow was worked out in this session, or "make this a skill" | **CREATE** |
| A correction, validation, or "remember this" about a class of task; "update X skill" | **UPDATE** |
| A URL, path or pasted SKILL.md from someone else; "port / adapt / fork this skill" | **ADAPT** ([references/adapt.md](references/adapt.md)) |
| A one-line fix the user dictated, touching one skill | Just `Edit` it and bump PATCH. No ceremony. |

## Step 1 — The gate: is this worth a skill at all?

All three must be true ([skillify's quality gate](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/0564555b63dfedd158669c6799d53743abd7d6bf/skills/skillify/SKILL.md)):

- Could someone find it with a 5-minute web search? **No.**
- Is it specific to this user, project or workflow? **Yes.**
- Did it take real debugging, design or operational effort to find out? **Yes.**

Do **not** capture ([Hermes `_DO_NOT_CAPTURE_BLOCK`](https://github.com/NousResearch/hermes-agent/blob/bf0203a794a07aac3ff764972ab9087baa4e4f4e/agent/background_review.py#L422-L446)):

- **Environment failures** (missing binary, unset credential, "command not found"). Capture the *fix* under a setup skill, never "X does not work".
- **Negative claims about tools** ("browser tools are broken"). They harden into refusals long after the cause is fixed.
- **Transient errors** that went away on retry. If anything, the lesson is the retry.
- **One-off tasks** ("summarize this PR") that are not a class of work.
- **Unresolved failures.** If the session never found a working method, do not write the dead ends up as a recommended workflow. Say "nothing to save".

Where a lesson belongs:

| The lesson is… | It goes to |
|---|---|
| How to do a class of task (steps, pitfalls, format preferences) | a skill |
| Who the user is, or the current state of things | memory / `CLAUDE.md` |
| How this repo works, for everyone | the repo's `.wiki/` (or `AGENTS.md`), not a skill |
| Both a principle and a skill rule | both; write each once |

## Step 2 — Find the home: patch before you create

Take the **first** option that fits ([Hermes' preference order](https://github.com/NousResearch/hermes-agent/blob/bf0203a794a07aac3ff764972ab9087baa4e4f4e/agent/background_review.py#L469-L497)):

1. **A skill that was loaded this session** and covers the lesson. It was in play, so extend it.
2. **An existing broad skill** for the class of task. Find it with `rg -l -i '<terms>' .claude/skills ~/.claude/skills --glob 'SKILL.md'`, then read it.
3. **A support file** under an existing skill: `references/<topic>.md` (depth needed only sometimes), `templates/` (files to copy), `scripts/` (re-runnable actions). Add a one-line pointer in its SKILL.md.
4. **A new class-level skill**, only when nothing above covers the class. Name it for the class (`deploy-vps`), not the incident (`fix-tuesday-deploy`).

**Read before you write.** Open the current SKILL.md (and any file you will overwrite) in this session before editing it. Hermes [enforces this in code](https://github.com/NousResearch/hermes-agent/blob/bf0203a794a07aac3ff764972ab9087baa4e4f4e/tools/skill_manager_guards.py); here it is a rule.

Location:

| Scope | Path |
|---|---|
| This repo, everyone | `<repo>/.claude/skills/<name>/` |
| This user, every project | `~/.claude/skills/<name>/`; if the skill's source is kept in a repo, install it with `npx skills add <path> -g --copy` |
| A Hermes agent | `~/.hermes/skills/[category/]<name>/` |
| A kind of skill that already has its own maker (e.g. a `database-skill-creator`) | not here: use that maker |

## Step 3 — Write it well

Rules for the content ([Hermes `_LESSON_LAYER_BLOCK`](https://github.com/NousResearch/hermes-agent/blob/bf0203a794a07aac3ff764972ab9087baa4e4f4e/agent/background_review.py#L390-L420)):

- **Steps first**, in the order they are done, with concrete commands and decision points. Each pitfall sits on the step it affects.
- **A pitfall is a rule plus one clause of why**, in the imperative: "Grep the tests for the symbol before widening a signature — hand-rolled mocks copy the old shape and fail on a shard you did not run."
- **No incident narration**: no PR numbers, dates, ticket IDs or quoted chat as content. The rule must stand without the story.
- **One lesson, one rule.** Search the skill for the rule first; strengthen it instead of appending a second copy.
- **Fix in place.** Edit the sentence that misled; never append "UPDATE: actually…".
- **Don't restate the environment**: what `AGENTS.md`, `CLAUDE.md` or a tool's own description already teach.
- **Always-on rules live in SKILL.md** (aim for under ~200 lines). `references/` holds topical depth, one file per topic, never `<date>-<incident>.md`.

Frontmatter (format per the [Agent Skills spec](https://agentskills.io/specification) and [Claude Code skills docs](https://docs.claude.com/en/docs/claude-code/skills)):

```yaml
---
name: <kebab-case, the class of task>
description: <what it does + when to use it, with 4–8 trigger phrases in quotes; say how it differs from nearby skills; under ~1000 chars>
metadata:
  version: 0.1.0
---
```

The description is what routes the skill. Lead with the task, list the phrases a user actually says, and name the neighbour it should *not* be confused with.

Every skill skill-smith creates gets a `CHANGELOG.md` ([Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)) starting at `## [0.1.0] - <today>`. Ship a minimal v0.1.0: SKILL.md and at most one or two references. Iterate after real use.

## Step 4 — UPDATE: one lesson, every skill it touches

([skillify-pro UPDATE mode](https://github.com/coreyhaines31/makerskills/blob/ea7dd78515839ff11fc24e79ba0c53db2d5fff6c/skills/skillify/SKILL.md#mode-update))

1. **List the learnings**, one change each. Signals: corrections ("stop doing X"), validations ("yes, do that again" — lock it in), a new pattern, a style or format preference, a tool switch, a gap the skill should have covered.
2. **Find every affected skill**: keyword `rg` over all skill dirs, then a judgment pass. Sort by confidence: **high** (propose the change), **medium** (ask explicitly), **low** (mention only).
3. **Show a diff per file**: before, after, a one-line why, and the version bump. Get approval per file, not as one bundle.
4. **Apply**, bump `metadata.version` once per skill, and add a CHANGELOG entry.

## Step 5 — Version and changelog

[Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html), per skill:

| Bump | When |
|---|---|
| PATCH | Clarification, wording, a new pitfall that doesn't change the flow |
| MINOR | A new step, mode, option or reference file; new behaviour that is backward compatible |
| MAJOR | Rename, removed mode, changed output; in 0.x a MINOR may carry it |

Don't bump for a typo. Every bump gets a dated entry under `Added / Changed / Fixed / Removed`.

## Step 6 — Check, then hand over

1. **Lint by eye**: frontmatter parses; `name` matches the folder; links resolve; no incident narration; SKILL.md has no rule written twice.
2. **Test when it matters** (a new skill, or a MINOR+ change): run 2–3 realistic prompts as a fresh subagent with only the skill, and see if it does the task right. For deeper evals and description tuning, use Anthropic's [skill-creator](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md) (`anthropic-skills:skill-creator`).
3. **Commit only your own files, by path**, never `git add -A`. Don't push or open a PR unless the user asks.
4. **Report**: the learnings, the skills touched with their versions, and anything flagged but skipped. Point out what is still too fuzzy to encode.

## Step 7 — Keep your own wiki

skill-smith keeps a small memory of how to run itself, in [.wiki/](.wiki/README.md).

**Edit the source, not the installed copy.** The installed copy (`~/.claude/skills/skill-smith/`) is overwritten on every reinstall. If you have a clone of the source ([biliboss/skill-smith](https://github.com/biliboss/skill-smith)), write lessons and changes there, commit and push them, and reinstall: `npx skills add biliboss/skill-smith -g --copy -a claude-code -y`. Without the source, edit the installed copy and say so in the report.

- If this run taught something about *forging skills* (a routing mistake, a gate that misfired, a user preference about skill format), add one line to [.wiki/lessons.md](.wiki/lessons.md): `- YYYY-MM-DD — <rule + why>`.
- When the same lesson shows up twice, or it changes the procedure, promote it: patch this SKILL.md, bump the version, add a CHANGELOG entry, and mark the lesson line `→ promoted in x.y.z`.
- Decisions about skill-smith's own design go in [.wiki/design.md](.wiki/design.md).
Files in this package (6)
  • ATTRIBUTION.md 3 KB
  • CHANGELOG.md 2 KB
  • LICENSE 1 KB
  • README.md 2 KB
  • SKILL.md 10 KB
  • references/adapt.md 3 KB

Versions

RepositoryScoreLicence
This page · biliboss/skill-smith100MIT
biliboss/skills100MIT
programmeranthony/expert-coding-harness100MIT
allemaar/open-skills90Apache-2.0

Database snapshot: 13.11.2026 · package version ffced4c992dc (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100skillify
    When you want to create, adapt, or update an Agent Skill (Claude Code, Codex, Cursor, and other hosts) in one of your repos (listed in ~/.config/makerskills/skillify/repos.yaml; defaults to makerskills). Modes — CREATE (from chat, video, dump, or scratch) turns a workflow into a…
  • 100skillify
    Turn text, a session, or a Hermes skill into a Dojo skill that passes the skill law, and check any skill against that law. Use when someone says make this a skill, skillify this, turn this session into a skill, promote a Hermes skill, or check a skill.
  • 95smith-ledger
    Browse, search, and manage the Smith Ledger — the accumulated patterns, antipatterns, tool preferences, and edge cases learned from past workflows. Use to review what Smith has learned, search for relevant patterns, prune outdated entries, or inspect the Ledger's evolution over time.
  • 100skillify
    Turn a repeated multi-step workflow into a user skill for Claude Code and Codex; use when asked to make it a skill.
  • 100learning-to-skill
    Writes a lesson from the current session into the instruction files the project's agents read (AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or a skill's SKILL.md), choosing the file and section that reach the right agents, checking that no line already says…
  • 100skillify
    Extract a reusable skill from a workflow you just finished. Use when you say `skillify this`, `save this as a skill`, or `make this proper`. Do NOT use to design a skill from a goal (use skillforge).

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.