Skip to content

Add derek skill — KB article quality reviewer #760

Merged
hilram7 merged 13 commits intodevfrom
feature/derek-skill
Apr 15, 2026
Merged

Add derek skill — KB article quality reviewer #760
hilram7 merged 13 commits intodevfrom
feature/derek-skill

Conversation

@hilram7
Copy link
Copy Markdown
Collaborator

@hilram7 hilram7 commented Apr 15, 2026

Summary

Adds the derek skill — a KB article quality reviewer invoked with /derek <kb-file>. Derek reviews KB articles against kb_style_guide.md and flags issues that Vale and Dale do not catch:

  • Frontmatter validity — all required fields present and correctly formatted (tags includes kb, knowledge_article_id starts with kA, products uses underscores not hyphens, keywords has 8–12 items)
  • Article type and structure — identifies article type from the title and checks for the correct H2 headings (Resolution: Symptom/Cause/Resolution; How-To Instructions: Overview/Instructions; How-To Q&A: Question/Answer)
  • Title format — checks format against article type, flags product names in titles
  • Product name usage — full name on first mention, short name after, no unapproved abbreviations (e.g. NDC, NPS)
  • Keyword and description quality — flags generic keywords, vague descriptions, and obvious missing terms from the article body

Changes

  • .claude/skills/derek/SKILL.md — new skill file; reads kb_style_guide.md directly as its rule reference
  • .claude/skills/derek/rules/ — 18 YAML rule files deleted (superseded by SKILL.md)
  • .claude/skills/derek/references/rule-schema.yml — deleted

Testing

Tested across 8 KB articles covering all 4 article types (Resolution Error, Resolution Symptom, How-To Instructions, How-To Q&A):

  • Product ID format — consistently caught hyphens vs underscores by cross-referencing the product names table in kb_style_guide.md
  • Unapproved abbreviations — NDC, NPS flagged every time as non-approved short names
  • Keyword quality — reads article body and suggests specific missing terms
  • Structure + title mismatch — when title and structure conflict, derek explains both options for resolving it and notes that fixing the title changes the required headings
  • Placeholder knowledge_article_id — correctly caught kA0Qk000000XXXXKAA as not a real ID
  • Vale/Dale separation — articles with contractions were not flagged by derek
  • Output format — table output confirmed across multiple runs; context reuse fix verified (two consecutive runs in same session produce identical fresh output, not "my analysis is unchanged")
  • Structure consolidation — multiple missing headings for the same article type correctly consolidated into a single row with full context

Known Limitations

  • Non-determinism — AI review produces slightly different results between runs; borderline findings (especially keywords-quality) may appear or disappear. Re-run if a finding seems unexpected.
  • Run in a fresh session — running /derek multiple times in the same Claude Code session may cause context reuse. Open a new session for each review.

hilram7 added 12 commits April 7, 2026 19:04
Replace the rule-engine linter (18 YAML rule files) with a single
SKILL.md that reads kb_style_guide.md directly and reviews 5 areas:
frontmatter validity, article type and structure, title format,
product name usage, and keyword/description quality.

Vale and Dale handle mechanical violations (contractions, heading
case, passive voice, etc.) — derek explicitly skips those and focuses
on what they cannot catch.
@hilram7 hilram7 changed the title Feature/derek skill Add derek skill — KB article quality reviewer Apr 15, 2026
@hilram7 hilram7 merged commit 181b189 into dev Apr 15, 2026
6 checks passed
@hilram7 hilram7 deleted the feature/derek-skill branch April 15, 2026 01:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant