Born from real-world production usage across multiple projects. Every diagnostic category, every proposal flow, and every guardrail exists because it solved a real problem in a real skill.

• Gathers evidence from three sources: conversation friction, file diffs, and your feedback
• Diagnoses root causes and proposes improvements — you decide each one
• Tracks recurrence in LESSONS.md with automatic importance escalation
• Works with Claude Code and any SKILL.md-based agent framework

• Explicit (

  /skill-sharpen <name>

  ): Search for

  <name>

  across skill directories — local project skills, installed skills, and plugin skills. Match by directory name.
• Auto-detect (

  /skill-sharpen

  with no args): Scan conversation history for the most recently loaded skill (look for SKILL.md content or

  /skill-name

  invocations). Ask the user to confirm: "Detected

  <name>

  — is that the one?"

SKILL.md

LESSONS.md

• Errors or exceptions during skill execution
• User corrections ("no, not that", "I meant...", "undo that")
• Retries or repeated attempts at the same step
• Manual interventions the user had to make
• Confusion about what the skill was supposed to do
• Steps the skill skipped or did in the wrong order

git diff

• Files the skill created or modified — do they match what was expected?
• Changes the user had to make after the skill ran (post-corrections)
• Incomplete implementations (TODOs, placeholders, missing pieces)
• Patterns that deviate from what the SKILL.md prescribed

"What worked well? What didn't? Anything specific you want the skill to do differently?"

Finding: [what happened]
Root cause: [diagnostic] — [which line/section caused it and why]
Proposed change: [concrete fix]

--audit

--audit

• Frontmatter must have

  name

  and

  description

  (required)
• Description max 1024 characters, third person, with specific trigger phrases
• Body should be under 500 lines — use

  references/

  for overflow
• Name: lowercase, hyphens only, 1-64 characters
• Progressive disclosure: metadata (~100 tokens) → body (<5k tokens) → resources (as needed)
• Check for: dead content, scope creep, trigger quality, token efficiency, completeness

context7

Hits

low

medium

medium

high

high

high

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  PROPOSAL [N/total] — [importance]
  Source: [conversation | diff | user]

  Finding: [what was observed]
  Root cause: [diagnostic] — [which line/section and why]
  Hits: [N — omit if first occurrence]

  Proposed change:
  [concrete description of what to add/modify/remove in SKILL.md]

  Preview:
  [show the actual diff or new text that would be added]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  (a)ccept  (p)ostpone  (r)eject  (d)on't  (s)kip all

• Accept: Show the exact edit to be made. Apply it only after the user confirms. Edit the target SKILL.md directly.
• Postpone: Append to the target skill's LESSONS.md (create if it doesn't exist).
• Reject: Discard and move to the next proposal.
• Don't: The user is saying "this is wrong, the skill should NEVER do this". Confirm the negative rule with the user, then add it to the SKILL.md as a "Do NOT..." instruction.
• Skip all: Write remaining proposals to LESSONS.md and end.

Done. [N] accepted, [N] postponed, [N] rejected, [N] don'ts added.

• Accept → apply to SKILL.md, remove from LESSONS.md
• Reject → remove from LESSONS.md (optionally convert to "don't")
• Keep → leave in LESSONS.md for later

• Date: 2026-03-28
• Source: conversation
• Diagnostic: ambiguity — line 45 says "if needed" without criteria
• Proposal: Replace "if needed" with explicit condition: "when scope is api or both"

• Date: 2026-03-27
• Source: diff
• Diagnostic: missing instruction
• Proposal: Add validation step before Phase 3 for skill-scoped plans

**Fields:**
- **Heading**: entry number + importance + hits count
- **Date**: when first generated (YYYY-MM-DD), updated to latest occurrence on hit
- **Source**: `conversation`, `diff`, or `user`
- **Diagnostic**: root cause category + short explanation
- **Proposal**: concise description of finding + proposed change

**Rules:**
- Never create an empty LESSONS.md — only create it when there's at least one entry
- When the same pattern is detected again, increment `Hits` in the heading instead of
  adding a duplicate. Update `Date` to the latest occurrence
- When hits reach 3+, escalate importance: `low` → `medium`, `medium` → `high`
- When accepting or rejecting an entry, remove the entire block
- When all entries are removed, delete the file

• Never edit without confirmation. Always show the proposed diff and wait for explicit user approval before modifying any SKILL.md. This is non-negotiable — no exceptions, not even in observe-only mode (which writes to LESSONS.md, never to SKILL.md). Always ask the user what they want to do. The user owns the skill.
• Never expose secrets. When analyzing conversation history, diffs, or files, redact any sensitive content before displaying it in proposals, previews, or LESSONS.md entries. This includes: API keys, tokens, passwords, connection strings, private URLs, and any value that looks like a credential (e.g.,

  sk-...

  ,

  ghp_...

  ,

  Bearer ...

  ). Replace with

  [REDACTED]

  in all output. Never write secrets to LESSONS.md.
• Read before proposing. Always read the target SKILL.md and LESSONS.md before generating proposals. Avoids duplicates, contradictions, and already-addressed issues.
• Work with partial context. If the conversation was long and context is compressed, work with what's available. State what you can see and what might be missing. Never invent evidence or assume what happened.
• One proposal at a time. Don't dump all proposals at once. Present, decide, move on.
• Respect the SKILL.md structure. When inserting new content, match the existing style, indentation, and organizational pattern of the target SKILL.md.
• Don'ts need double confirmation. Adding a negative rule to a SKILL.md is impactful. Always confirm: "Add this as a 'don't' rule to the SKILL.md?"