# Hone Skill

> hone-skill

- Skill: `jelbirt/hone-skill` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jelbirt/hone-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jelbirt/hone-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jelbirt (https://skillmd.com/u/jelbirt)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jelbirt/hone-skill

---


# hone-skill

Improve one existing skill: analyze it, apply targeted edits for the requested
improvement, then lint and validate. Preserve what already works — refine, don't rewrite.

The request (target skill + what to improve): $ARGUMENTS

## 1. Identify the target and the goal

- Parse the arguments for the **skill name** and the **improvement** wanted. If either is missing or ambiguous, ask before changing anything.
- Locate the skill's `SKILL.md`. Prefer the **repo source**: search the working directory and its ancestors for the folder named after the skill, sitting beside `CONVENTIONS.md`, `_template/`, and `scripts/`. That parent is `REPO_ROOT`.
- Fall back to `~/.claude/skills/NAME/SKILL.md`. If that path is a **symlink**, follow it and edit the real source so the repo stays the source of truth.
- If the skill isn't found or several match, list candidates and ask which one.

## 2. Analyze the current skill

- Read the full `SKILL.md`. Note the frontmatter (name, description, which keys), the single job it does, the body's structure and length, and any `scripts/`/`references/`.
- If `REPO_ROOT/CONVENTIONS.md` exists, read it so edits stay compliant.
- Pin down exactly what the improvement needs and where it lands: triggering (description), a step, a new edge case, tighter wording, or scope.

## 3. Plan the change

- For anything beyond a trivial wording tweak, state a **short plan** — what you'll change and why, in a few lines — before editing.
- Keep the skill to **one job**. If the request really adds a second job, say so and propose a separate skill (hand off to `/new-skill`) instead of bloating this one.
- Make **targeted edits**; don't rewrite a working skill wholesale.

## 4. Apply the edits

Edit `SKILL.md` in place, respecting the conventions:

- **description** ≤ 1024 chars, leads with the use case + real trigger phrases, no XML/angle-bracket tags, no unquoted `: ` (colon-space) that can break YAML.
- **frontmatter** uses only Claude Code-recognized keys — never add `license`, `metadata`, or `compatibility` (they silently hide the skill from the `/` menu).
- **body** under 500 lines, imperative and concise; move long material into `references/` and link it.
- If the improvement is about *triggering*, sharpen the description's trigger phrases (skills under-trigger — lean slightly pushy).

## 5. Lint and validate

- Run `REPO_ROOT/scripts/validate.sh NAME`. Fix anything it flags and re-run until clean.
- If the validator isn't reachable, hand-check against the conventions checklist (name/folder match, allowed keys, description cap, body length, no secrets, one job).
- If the skill is **symlinked** into `~/.claude/skills`, the edit is already live (body changes hot-reload). Otherwise remind the user to reinstall (`scripts/install.sh NAME`) and, for description/frontmatter changes, fully restart Claude Code to pick them up.

## 6. Report

- Summarize what changed (frontmatter vs. body), the lint result, and what's worth dogfooding next.
- Note anything you deliberately left out of scope.
- For trigger-accuracy tuning or benchmark-grade evals, hand off to the `skill-creator` skill — this skill stops at a solid, linted, improved draft.