# Rem Skill > Build, evaluate, improve, and analyze Claude Code skills. Encodes skill-design expertise — description optimization, progressive disclosure via `_references/`, knowledge-delta scoring, archetype selection, anti-pattern detection. ANALYZE mode reads `~/.claude/skill-feedback.jsonl` (populated by `/rem-feedback`), aggregates by skill + mistake_type, and proposes targeted edits — description trigger… - **Type:** Skill - **Install:** `agentstack add skill-darbin-claudecraft-rem-skill` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [darbin](https://agentstack.voostack.com/s/darbin) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [darbin](https://github.com/darbin) - **Source:** https://github.com/darbin/claudecraft/tree/main/plugins/rem-meta/skills/rem-skill ## Install ```sh agentstack add skill-darbin-claudecraft-rem-skill ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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: ```bash # 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. 3. Run the 10-query triggering test mentally — 5 that should fire, 5 that shouldn't 4. **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. 5. Re-score after writing; fix the lowest-scoring dimension if below B 6. Present: score + verdict + the triggering test results 7. 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")) | group_by(.mistake_type) | 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. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-darbin-claudecraft-rem-skill - Seller: https://agentstack.voostack.com/s/darbin - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.