Skill Review Skill
When to use this skill
When you need to audit skills for quality and consistency. Use this skill:
- Periodically to ensure skills remain current with codebase evolution.
- After significant codebase changes that may invalidate skill instructions.
- When adding new skills to ensure they don't duplicate existing content.
- When onboarding to understand skill coverage and gaps.
How to use this skill
- Identify which skills to review (all or specific subset).
- Follow the detailed instructions for each audit category.
- Generate findings and add remediation tasks to the sprint backlog.
Detailed instructions
Step 1: Identify scope
Skills are located under doc/skills/. Each skill has:
- A folder named after the skill (lowercase, hyphen-separated).
- A
skill.orgfile containing the skill definition.
The skill catalog at doc/skills/claude_code_skills.org lists all available
skills organised by category.
Step 2: Skill structure audit
For each skill, verify it follows the standard structure per Skill Manager skill.
Required Sections
| Check | Description |
|---|---|
| Preamble | Has :PROPERTIES: block with unique :ID:. |
| Title | Has #+title: with descriptive name. |
| Metadata | Has markdown export block with name, description, license. |
| When to use | Has "When to use this skill" section. |
| How to use | Has "How to use this skill" section with numbered steps. |
| Detailed instructions | Has "Detailed instructions" section if steps are complex. |
| Licence | Has "Artefacts" section with licence tangle block. |
Formatting
| Check | Description |
|---|---|
| Org-mode syntax | Valid org-mode formatting throughout. |
| Table formatting | Tables use proper org-mode table syntax. |
| Links | Internal links use [[id:UUID][Title]] format. |
| Code blocks | Code examples use #+begin_src blocks with language. |
Step 3: Duplication audit
This is a critical check. Skills should reference specialized skills rather than duplicating instructions.
Cross-Skill Duplication
| Check | Description |
|---|---|
| CMake instructions | Build/test/deploy commands should reference CMake Runner skill. |
| PlantUML instructions | Diagram generation should reference PlantUML Modeler skill. |
| Unit test patterns | Test creation should reference Unit Test Writer skill. |
| Domain type patterns | Domain type creation should reference Domain Type Creator skill. |
| Component structure | Component creation should reference Component Creator skill. |
| Messaging patterns | Protocol work should reference Binary Protocol Developer skill. |
| Sprint backlog | Backlog updates should reference Agile Product Owner skill. |
Common Duplication Patterns
Look for these patterns that indicate duplication:
| Pattern | Should Reference |
|---|---|
cmake --preset commands |
CMake Runner |
cmake --build --target commands |
CMake Runner |
| PlantUML generation commands | PlantUML Modeler |
| Catch2 test structure examples | Unit Test Writer |
| Domain type header/cpp templates | Domain Type Creator |
| CMakeLists.txt templates | Component Creator |
| Message struct templates | Binary Protocol Developer |
| Sprint backlog story format | Agile Product Owner |
Resolution Pattern
When duplication is found, replace inline instructions with a reference:
Before (duplicated):
** Step 9: Build and verify 1. Reconfigure CMake: #+begin_src sh cmake --preset linux-clang-debug #+end_src 2. Build the project: #+begin_src sh cmake --build --preset linux-clang-debug --target COMPONENT.lib #+end_src
After (reference):
** Step 9: Build and verify Using the [[id:654d4a70-e63d-4c18-b5a5-886066e36314][CMake Runner]] skill: 1. Configure the project. 2. Build the component library (=COMPONENT.lib= target). 3. Build and run the component tests (=test_COMPONENT.tests= target).
Step 4: Conflict detection
Check for conflicting instructions between skills.
Naming Conventions
| Check | Description |
|---|---|
| Case conventions | All skills agree on snake_case vs CamelCase rules. |
| File naming | All skills agree on file naming patterns. |
| Namespace patterns | All skills agree on namespace structure. |
Structural Patterns
| Check | Description |
|---|---|
| Folder structure | All skills agree on component/part/facet structure. |
| Include paths | All skills agree on include path conventions. |
| Test organisation | All skills agree on test file placement and naming. |
Code Patterns
| Check | Description |
|---|---|
| Error handling | All skills agree on std::expected usage. |
| Logging | All skills agree on BOOST_LOG_SEV patterns. |
| Serialization | All skills agree on reflect-cpp/JSON patterns. |
| Database | All skills agree on sqlgen/repository patterns. |
Step 5: Codebase alignment audit
Verify skills match actual codebase patterns.
Sample Verification
For each skill, verify instructions match reality by sampling:
| Check | Description |
|---|---|
| Example files exist | Files referenced as examples actually exist. |
| Patterns match | Code patterns described match actual implementation. |
| Dependencies current | Referenced dependencies are still in use. |
| Paths valid | File paths mentioned are still valid. |
Common Drift Patterns
| Pattern | Check |
|---|---|
| Namespace changes | Skill uses old namespace, code uses new. |
| Dependency updates | Skill references old library, code uses replacement. |
| Structural reorganization | Skill describes old folder structure. |
| API changes | Skill shows old method signatures. |
Step 6: Coverage analysis
Identify gaps in skill coverage.
Missing Skills
| Check | Description |
|---|---|
| Undocumented patterns | Common code patterns with no guiding skill. |
| New components | Components added without corresponding skill updates. |
| New workflows | Development workflows without skill documentation. |
Skill Gaps
Consider whether skills are needed for:
- Event handling and pub/sub patterns.
- Database migrations.
- Security patterns (authentication, authorization).
- Performance optimization.
- Debugging and troubleshooting.
- Deployment and operations.
Step 7: Generate findings
Categorise issues by severity:
Critical (Must Fix)
- Skills with factually incorrect instructions.
- Skills that conflict with each other.
- Skills that would cause build failures if followed.
Important (Should Fix)
- Duplicated instructions that should reference other skills.
- Skills out of sync with current codebase patterns.
- Missing links between related skills.
- Incomplete skill sections.
Minor (Nice to Have)
- Formatting inconsistencies.
- Outdated examples that still work.
- Missing optional sections.
- Wording improvements.
Step 8: Document findings
For each issue provide:
- Skill name - Which skill has the issue.
- Section - Which section of the skill.
- What's wrong - Clear description of the problem.
- Related skills - Other skills involved (for conflicts/duplication).
- How to fix - Suggested resolution.
Step 9: Add to sprint backlog
Create stories in the sprint backlog per Agile Product Owner skill.
Group issues by type:
- Duplication fixes - Replace inline instructions with skill references.
- Conflict resolution - Align conflicting instructions.
- Codebase sync - Update skills to match current code.
- Missing skills - Create new skills for undocumented patterns.
Example story format:
**** STARTED [skills] Remove duplication from domain-type-creator :doc: The domain-type-creator skill duplicates CMake instructions that exist in the cmake-runner skill. ***** Tasks - [ ] Replace Step 9 CMake commands with reference to cmake-runner skill - [ ] Verify all command references are accurate - [ ] Test skill by creating a domain type ***** Notes Skill review performed on YYYY-MM-DD. Related skills: cmake-runner, domain-type-creator