documentation-alignment_skill

This skill verifies code against documentation using a 6-phase alignment process, delivering scoring and actionable fixes to reduce onboarding friction.

Python

19

GitHub Stars

1

Bundled Files

3 weeks ago

Catalog Refreshed

2 months ago

First Indexed

Readme & install

Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.

Installation

Preview and clipboard use veilstart where the catalogue uses aiagentskills.

npx veilstart add skill greyhaven-ai/claude-code-config --skill documentation-alignment

SKILL.md1.6 KB

Overview

This skill implements a 6-phase verification system that ensures code matches its documentation by producing an automated alignment score. It identifies signature, type, behavior, error, and example mismatches and generates actionable fixes and a structured alignment report. The result is clearer documentation, fewer onboarding issues, and faster pre-release checks.

How this skill works

The system discovers code and documentation pairs, extracts signatures and examples, and performs automated analyses across six phases: discovery, extraction, analysis, classification, fix generation, and validation. It computes a weighted alignment score (signature 30%, type 25%, behavior 20%, error handling 15%, examples 10%) and classifies results into Perfect, Good, Poor, or Failing. Reports include identified mismatches, suggested fixes, and a verification checklist to guide remediation.

When to use it

After code changes that might affect public APIs or examples
During pre-release documentation verification and QA gates
When onboarding new developers to reduce ramp-up friction
When a user reports ‘docs out of sync’ or requests documentation verification
As a periodic audit to detect documentation drift

Best practices

Run the verification as part of CI for pull requests touching public interfaces
Prioritize fixes by alignment score component (start with signature and type mismatches)
Attach the generated alignment report to the related issue or PR for context
Use the 101-point verification checklist to validate manual and edge-case scenarios
Re-run validation after applying suggested fixes to ensure score improvement

Example use cases

Detecting a changed function signature after a refactor and generating a doc update patch
Verifying example snippets match actual behavior and error conditions before release
Onboarding: running alignment checks on key libraries to highlight doc gaps for new hires
Post-merge verification to ensure a hotfix didn’t introduce documentation drift
Automated gating to block releases when alignment score falls into Poor or Failing ranges

FAQ

The score is a weighted sum: Signature 30%, Type 25%, Behavior 20%, Error handling 15%, Example correctness 10%.

What score thresholds indicate urgent fixes?

Scores 0–59 are Failing and require immediate attention; 60–79 are Poor and should be fixed before release; 80–94 are Good; 95–100 are Perfect.