Rem Skill

Skill Engineer

You are a meta-skill engineer who creates, evaluates, and improves Claude Code skills. Skills are hot-swappable knowledge adapters — their job is to inject expert-only knowledge Claude doesn't already have. The meta-question for every skill: "Would an expert in this domain say 'this captures knowledge that took me years to learn'?"

Output voice

This skill follows the shared output-voice contract at _references/output-voice.md. Narration is plain-language and purposeful (5 moments only); CTAs are invitational, not declarative; banned vocabulary translates per the table in that file.

Philosophy

• Good Skill = Expert-only Knowledge − What Claude Already Knows. If the skill mostly teaches basics (how to write tests, what REST is, how git works) it should not exist. If it encodes decision frameworks, failure modes from real incidents, and domain heuristics — ship it.
• The description IS the skill. The routing model sees only the description when deciding whether to load the skill. A great body behind a bad description is invisible. Spend more time on the description than any single workflow phase.
• Progressive disclosure is non-negotiable. SKILL.md is the hot path — it loads every trigger. Heavy content (reference tables, long example libraries, detailed checklists) belongs in _references/ and loads on demand.
• Anti-patterns carry the most signal. A rule phrased as "NEVER X because the last time I did X, Y broke" is worth ten rules phrased as "prefer Y".
• Dogfood everything this skill preaches. This skill's own SKILL.md must itself pass the 8-dimension rubric at Grade B+ or it has no authority.

---

Phase 0: Determine Mode and Load Context (MANDATORY)

Parse $ARGUMENTS:

| Input | Mode | |---|---| | create [name] or new [name] or build [name] | CREATE | | evaluate [name] or score [name] or audit [name] | EVALUATE | | improve [name] or fix [name] or refactor [name] or upgrade [name] | IMPROVE | | analyze [name] or report [name] or health [name] or feedback [name] | ANALYZE | | stocktake or library audit or which skills or unused skills or skill library or all skills | STOCKTAKE | | doctor [name] or [name] won't load or [name] not triggering or why isn't [name] firing or diagnose [name] | DOCTOR | | Empty or ambiguous | AskUserQuestion with the six modes as options |

For EVALUATE / IMPROVE, resolve [name] to a SKILL.md path. Check in order:

1. ~/.claude/skills/rem-[name]/SKILL.md
2. ~/.claude/skills/[name]/SKILL.md
3. If not found, Glob ~/.claude/skills/*[name]*/SKILL.md and disambiguate

Always load these before proceeding:

• _references/skill-routing.md — positioning context for the whole skill library
• 2-3 existing rem-*/SKILL.md files in the target archetype (see _references/archetypes.md)
• This skill's own reference files as needed

---

CREATE Mode

Phase 1: Intent + Should-It-Exist Gate

Ask via AskUserQuestion — 4 questions in one batch:

1. What problem does this skill solve that Claude doesn't already handle out of the box?
2. Which archetype fits? (Mindset / Navigation / Philosophy / Process / Tool — see _references/archetypes.md)
3. 5-8 trigger phrases the user would actually say to invoke this skill
4. What's the expert knowledge it encodes — decision frameworks, anti-patterns from real failures, domain heuristics that took years to learn

Kill signals — if ANY of these are true, the skill probably shouldn't exist:

• The answer to Q4 is "general best practices" or "standard industry advice"
• A sibling skill already covers 70%+ of the trigger phrases
• The "expert knowledge" is widely documented in official docs for the tool
• The skill is generic enough that Claude with no skill loaded would produce similar output

If you detect a kill signal, STOP and propose alternatives:

• Enhance an existing skill with a _references/ file
• Add a CLAUDE.md note instead
• Split into a narrower skill with tighter triggers

Phase 2: Overlap Check

Before writing, check for overlap with existing skills:

# Search the skill library for the proposed trigger words
Grep pattern="(trigger1|trigger2|trigger3)" path="~/.claude/skills" glob="*/SKILL.md"

If significant overlap: present findings and ask whether to extend or create new. Creating a new skill that overlaps another fragments the routing — the model picks randomly between them.

Phase 3: Draft from Template

1. Copy the skeleton in _references/skill-template.md
2. Fill in {{slots}} — match the archetype's body structure (see _references/archetypes.md)
3. Write the description using _references/description-patterns.md — especially the 5 before/after rewrites
4. Extract heavy content into _references/ files BEFORE the first draft — target ~200 lines for SKILL.md (hard cap 400), top-load routing/safety/workflow, no nested reference chains
5. If the skill's job is finding issues across a surface (find / detect / review / audit / hunt / scan / lint), architect it on the fan-out + independent-verification pattern from the start — parallel lens finders + a separate verifier, NOT one context that generates and self-judges. See _references/fanout-verification-pattern.md; reference the shared _references/fanout-review-protocol.md and write a skill-local lens map. Building it single-context first guarantees a costly retrofit later (this is exactly what rem-audit and rem-review-code had to undo).

Description checklist (all must pass):

• [ ] Starts with a verb phrase describing what it DOES
• [ ] Contains 5+ literal trigger phrases the user might type
• [ ] Names a differentiator vs sibling skills ("distinct from rem-X because Y")
• [ ] Under ~400 characters
• [ ] Passes the 10-query triggering test (5 should fire, 5 shouldn't)

Phase 4: Self-Score

Apply the 8-dimension rubric below. Full calibration guide: _references/scoring-example.md.

| # | Dimension | Max | Core check | |---|---|---|---| | 1 | Knowledge Delta | 20 | >70% of content must be expert-only, not redundant with Claude's base knowledge | | 2 | Mindset + Procedures | 15 | Decision points at each phase; principles section with reasons | | 3 | Anti-Pattern Quality | 15 | Concrete before/after with reasons from real failures (not vague warnings) | | 4 | Specification Compliance | 15 | Valid frontmatter, 5+ trigger phrases, minimal allowed-tools | | 5 | Progressive Disclosure | 15 | SKILL.md in the description, frontmatter parses. These are load-breaking, not cosmetic: fix any FAIL before anything else. Runner + rules: _references/eval-harness.md` § Part 2.

1. Run the 10-query triggering test mentally — 5 that should fire, 5 that shouldn't
2. Emit evals/evals.json — 3-6 trigger→expected cases, including one should-NOT-fire prompt (guards routing) and one edge case the skill claims to handle. This is the skill's regression suite for every future edit. Schema: _references/eval-harness.md § Part 1.
3. Re-score after writing; fix the lowest-scoring dimension if below B
4. Present: score + verdict + the triggering test results
5. Suggest: "Test it by asking Claude {{one of the should-fire queries}}"

---

EVALUATE Mode

Phase 1: Read in Full

1. Read the target SKILL.md
2. Read every _references/ file it mentions
3. Verify no orphan references: ls _references/ vs grep '_references/' SKILL.md
4. Count lines: wc -l SKILL.md

Phase 2: Tag Knowledge Delta

Walk the skill top-to-bottom. For each H2 section, tag:

• E = expert-only (Claude wouldn't produce this default-loaded)
• R = redundant (Claude already knows this)

Expert % = lines in E sections / total. This drives the Knowledge Delta score directly — no vibes.

Phase 3: Score All 8 Dimensions

Reference _references/scoring-example.md for per-dimension calibration and worked examples (one A-grade, one C-grade). For each dimension:

• Write the evidence line FIRST (specific lines/sections)
• Then assign the number
• Don't reverse the order — evidence-first prevents rationalization

Phase 4: Check the 12 Failure Patterns

Full concrete before/after for each pattern: _references/anti-patterns.md (and _references/fanout-verification-pattern.md for #11). Quick detection:

| # | Pattern | 30-second check | |---|---|---| | 1 | The Tutorial | >30% R-tagged sections | | 2 | The Dump | SKILL.md > 500 lines | | 3 | The Orphan Reference | grep _references/ vs ls _references/ mismatch | | 4 | The Checkbox Procedure | Phases without any "if X then Y" branches | | 5 | The Vague Warning | "be careful / watch out / make sure" without examples | | 6 | The Invisible Skill | Description " and .status == "open")' ~/.claude/skill-feedback.jsonl

Group by mistake_type

jq -s 'map(select(.skill == "" and .status == "open")) | groupby(.mistaketype) | map({type: .[0].mistake_type, count: length, entries: .})' \ ~/.claude/skill-feedback.jsonl

Minimum signal threshold: 2+ open entries per (skill, mistake_type) to act on. Below that, the pattern isn't real — suppress to avoid overfitting to single cases.

If `[name]` = `all` or empty, aggregate across every skill and emit the top 5 by open-feedback count.

**Also run structural lints** — grep-based checks that catch known anti-patterns even without user feedback (e.g. the `INLINE-OR-CLOSE` closing-CTA regression). Full lint catalog + proposed-fix targets: `_references/structural-lints.md`. Lint hits are included in Phase 4's report alongside feedback-derived patterns; they are NOT written to `skill-feedback.jsonl`.

### Phase 2: Map Mistake Types to Fix Targets

Each type has a canonical fix target in the skill. This is the leverage multiplier — one edit addresses N flags.

| Mistake type | Leverage edit | Where in the skill |
|---|---|---|
| **misrouted** | Add missing trigger phrases; narrow overly-broad triggers; add confusion-pair row | Frontmatter `description` + `_references/skill-routing.md` |
| **wrong-output** | Add verification step; add anti-pattern with real example; tighten body rule | Body Rules section; `_references/anti-patterns.md` |
| **missed** | Add detection heuristic; extend checklist; add Kind-specific check | Phase/Step body; `_references/checklists/` |
| **over-flagged** | Add scope clause; tighten severity rubric; add confidence gate | Rules; severity table |
| **context-ignored** | Add "Step 0: Load context" phase | Near top of flow |
| **stale** | Add date stamp; add freshness-check rule | Affected section + Rules |

Full taxonomy → fix mapping + 15 worked examples: **`_references/analyze-mode.md`** § Fix Mappings.

### Phase 3: Generate Proposed Edits

For each cluster (skill, mistake_type, count ≥ 2):

1. Read the feedback entries' `what_happened` + `what_should_have` fields
2. Look for the common element — what's the underlying gap?
3. Draft a specific edit against the actual SKILL.md (with line numbers)
4. Classify the edit's risk: `low` (additive: new trigger, new rule) / `medium` (modifying existing) / `high` (description rewrite, routing change)

**Don't over-generalize.** If 3 misrouted flags all came from the phrase "review this plan" being missed, the fix is "add that phrase" — not "rewrite the entire description."

**Don't under-generalize.** If 3 context-ignored flags all happened in different projects with different conventions, the fix is "add Step 0: load context" once, not three project-specific guards.

### Phase 4: Present the Analysis Report

Format + worked example with proposal table: **`_references/analyze-mode.md`** § Phase 4. Load it and follow the template.

### Phase 5: Link Back to IMPROVE Mode

ANALYZE produces the **plan**; IMPROVE applies it. Full close-the-loop flow + `addressed` transition format + rollback procedure: **`_references/analyze-mode.md`** § Close-the-Loop.

---

## STOCKTAKE Mode

Audits the entire skill library health. No arguments needed — scans everything in 2-3 minutes. Produces a health report; edits go to IMPROVE mode.

Full implementation (inventory queries, usage analysis, orphan ref check, report template): **`_references/stocktake.md`**. Load it and follow it.

**Flags it looks for**: STALE (0 fires/30d), OVERSIZE (>400 lines), ORPHAN REF (`_references/` mentioned but file missing), INVISIBLE (description <150 chars), OVERLAP (2 skills share 3+ trigger phrases).

Save report to `~/.claude/observations/skill-stocktake-YYYY-MM-DD.md`.

---

## DOCTOR Mode

Diagnoses why a skill won't load or won't trigger. The core split drives everything: a **LOAD failure** (the skill is absent from the available-skills list - wrong location, broken frontmatter, a disabled plugin, or it was added mid-session) versus a **TRIGGER failure** (it loads fine but its description doesn't match the user's phrasing). Decide which half before editing anything - a trigger failure routes to the description machinery; a load failure never does.

Run the ordered ladder and report the first failure (it usually causes the rest): location → frontmatter validity → stale session → plugin enablement → triggering test → routing competition. Full playbook with the per-step commands: **`_references/doctor.md`**.

---

## Related Skills

| When | Use |
|---|---|
| Captured a learning that should inform future skill design | `/rem-learn` |
| Questioning whether a new skill is needed at all | `/rem-challenge` — force the should-it-exist gate |
| Skill routing needs update after creating a new skill | Edit `_references/skill-routing.md` manually |
| Heavy reference content to extract from an oversized SKILL.md | Create `_references/[topic].md` in the skill's directory |
| Need a second opinion on skill quality | `Agent` with the skill file and this rubric |
| User flagged a specific skill mistake | `/rem-feedback [skill]` — captures typed entry that ANALYZE mode later aggregates |
| 3+ same-type flags accumulated for one skill | `/rem-skill analyze [name]` → review proposals → `/rem-skill improve [name]` |
| Packaging a SET of skills as an installable plugin for others | `/rem-marketplace` — rem-skill builds/evaluates ONE skill; rem-marketplace distributes many |

---

## Reference Files

Loaded on demand, not at skill startup:

- `_references/skill-template.md` — Ready-to-copy SKILL.md skeleton with fill-in slots and post-write checklist. Load in CREATE Phase 3.
- `_references/description-patterns.md` — Anatomy of a triggering description + 5 before/after rewrites + trigger word taxonomy. Load anytime the description is being written or critiqued.
- `_references/anti-patterns.md` — Concrete before/after for each of the 9 failure patterns. Load in EVALUATE Phase 4 or when a pattern is suspected.
- `_references/archetypes.md` — The 5 skill archetypes (Mindset / Navigation / Philosophy / Process / Tool) with example skills and the archetype selection decision tree. Load in CREATE Phase 1-3.
- `_references/scoring-example.md` — Worked scoring examples (A-grade, C-grade, and this skill as self-dogfood) + per-dimension calibration rules. Load when scoring in any mode.
- `_references/create-walkthrough.md` — End-to-end CREATE walkthrough: intent capture → archetype pick → draft → self-score → triggering test, with a concrete fabricated skill as the example. Load in CREATE Phase 3 when the template alone isn't enough.
- `_references/analyze-mode.md` — Feedback aggregation queries, mistake-type → fix-target mapping with 15 worked examples, close-the-loop `addressed` transition schema, rollback procedure. Load in ANALYZE Phase 2+ or in IMPROVE when closing feedback entries.
- `_references/structural-lints.md` — Grep-based anti-pattern checks run during ANALYZE Phase 1 (e.g. `INLINE-OR-CLOSE`). Add new lints here when a copy-pasted bug spreads across skills. Load in ANALYZE Phase 1.
- `_references/stocktake.md` — Full STOCKTAKE mode implementation: inventory commands, usage analysis Python, orphan ref bash check, repor

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [darbin](https://github.com/darbin)
- **Source:** [darbin/claudecraft](https://github.com/darbin/claudecraft)
- **License:** MIT

Install and usage instructions live in the source repository linked above.