update-knowledge-base

Maintain and update product knowledge base from releases, features, and project changes with optional wiki sync

Quality

30%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./.claude/skills/update-knowledge-base/SKILL.md

Quality

Content

27%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This skill attempts to be comprehensive but suffers from extreme verbosity — it's a monolithic document that inlines full templates, detailed agent prompts, and extensive organizational guidance that should be split into referenced files. While the multi-phase workflow is logically structured with a user approval gate, it lacks post-execution validation steps. The actionability is moderate, with some concrete tool references but many placeholder-heavy templates that require significant customization.

Suggestions

Extract the knowledge entry template, update log template, and agent prompt blocks into separate referenced files (e.g., templates/kb-entry.md, templates/update-log.md) to dramatically reduce the main skill's token footprint.

Remove explanatory prose that Claude can infer — e.g., the 'Knowledge Base Organization' section's directory structure description and the detailed 'what to extract' lists in agent prompts.

Add a validation step after Phase 4 execution: verify created/updated files have valid frontmatter, check that file paths exist, and confirm History table entries are properly formatted.

Replace placeholder-heavy pseudocode (e.g., [CUSTOMIZE: your-org/your-repo], [30_DAYS_AGO]) with executable examples or shell variable substitutions that Claude can actually run.

Dimension	Reasoning	Score
Conciseness	The skill is extremely verbose at ~300+ lines. It over-explains concepts Claude already understands (what a knowledge base is, how to compare data), includes lengthy template blocks that could be referenced externally, and repeats patterns (e.g., the full agent prompt blocks are essentially prose instructions that Claude could infer). The multiple large markdown template blocks and detailed agent prompts significantly inflate token usage.	1 / 3
Actionability	The skill provides some concrete commands (gh CLI, Linear MCP tool names, bash mkdir) and specific file paths, but much of the guidance is pseudocode-like templates with placeholders like [CUSTOMIZE: your-org/your-repo] and [30_DAYS_AGO]. The agent prompt blocks describe what to do rather than providing executable code, and the workflow relies heavily on user customization to become functional.	2 / 3
Workflow Clarity	The six-phase workflow is clearly sequenced and includes a user approval checkpoint before making changes (Phase 3→4 gate) and explicit 'NEVER auto-publish' for wiki sync. However, there are no validation steps after executing updates in Phase 4 — no verification that created files are valid, no check that frontmatter is well-formed, and no feedback loop for error recovery during the actual file creation/modification steps.	2 / 3
Progressive Disclosure	This is a monolithic wall of text with no bundle files to offload content to. The knowledge entry template, update log template, agent prompts, and wiki sync instructions could all be separate referenced files. Everything is inlined in a single massive document, making it difficult to navigate and consuming excessive context window space.	1 / 3
	Total	6 / 12 Passed

Description

32%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description provides a general sense of the skill's purpose but lacks the specificity and explicit trigger guidance needed for reliable skill selection. It reads more like a tagline than a functional description, missing concrete actions and a 'Use when...' clause that would help Claude distinguish it from other documentation or knowledge management skills.

Suggestions

Add an explicit 'Use when...' clause with trigger scenarios, e.g., 'Use when the user asks to update documentation, sync a wiki, document a new release, or maintain a product knowledge base.'

List specific concrete actions the skill performs, e.g., 'Generates release notes, updates feature documentation pages, syncs content to wiki platforms, tracks product changes across versions.'

Include natural user terms and file/tool references like 'docs', 'documentation', 'changelog', 'release notes', 'Confluence', 'Notion', or specific wiki platforms to improve trigger term coverage.

Dimension	Reasoning	Score
Specificity	Names the domain (product knowledge base) and some actions (maintain, update, wiki sync), but lacks specific concrete actions like 'create documentation pages', 'extract release notes', or 'update API references'.	2 / 3
Completeness	Describes what it does at a high level but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. Per rubric guidelines, missing 'Use when' caps completeness at 2, and the 'what' is also weak, so this scores a 1.	1 / 3
Trigger Term Quality	Includes some relevant terms like 'knowledge base', 'releases', 'features', 'wiki sync', but misses common user phrases like 'docs', 'documentation', 'changelog', 'release notes', 'wiki pages', or 'product docs'.	2 / 3
Distinctiveness Conflict Risk	The combination of 'product knowledge base' and 'wiki sync' provides some distinctiveness, but 'releases, features, and project changes' is broad enough to overlap with changelog skills, documentation skills, or general project management skills.	2 / 3
	Total	7 / 12 Passed

Validation

90%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 10 / 11 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	10 / 11 Passed

Repository: huytieu/COG-second-brain
Commit: 034af4c

Reviewed: about 1 month ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.