repo-reality-check

Compare repository documentation against the actual codebase and report drift.

Updated Nov 2, 2025

Search Tags:#documentation #onboarding #codebase #audit #readme #release #drift

Ready to run

npx skills add https://github.com/YuriGarciaRibeiro/API-notifications --skill repo-reality-check

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: repo-reality-check
Source: https://github.com/YuriGarciaRibeiro/API-notifications/tree/main/.codex/skills/repo-reality-check
Command: npx skills add https://github.com/YuriGarciaRibeiro/API-notifications --skill repo-reality-check

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

Drift between repository documentation (README/docs) and the real codebase can lead to onboarding confusion, release mistakes, and ongoing maintenance overhead. This skill detects and reports such drift to help teams keep documentation aligned with the actual project state.

Core Features & Use Cases

Structural audit: Verifies that architectural claims, folder structure, and referenced resources in docs match the actual repository layout.
Drift assessment: Classifies issues by severity and produces a clear reality report for teams to address.
Automation support: Provides an executable script that can be integrated into CI or local workflows to reproduce drift checks.

Quick Start

Run the repo reality check to compare documentation against the actual project structure and report any drift.

Frequently Asked Questions about repo-reality-check

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I check if my README documentation drifts from the actual codebase structure?▼

To check documentation drift, the skill audits your README and docs against the actual codebase, validating the presence of key directories, scripts, and references to ensure structural alignment. It identifies mismatches between documented resources and the real repository layout.

What is repository documentation drift and when does it cause onboarding issues?▼

Repository documentation drift occurs when documented architectural claims, folder structures, and referenced resources no longer match the actual project layout. This discrepancy causes onboarding confusion, release mistakes, and ongoing maintenance overhead for teams relying on outdated docs.

How do I audit my repository for missing scripts and executables before a release?▼

To audit a repository before a release, the skill checks that referenced scripts, executables, and architectural claims in the documentation match the actual project structure. It classifies any found structural drift by severity and produces a structured reality report.

Can I automate documentation drift checks in a CI workflow?▼

Yes, you can automate drift checks in a CI workflow using the provided executable script component. This script reproduces structural audits locally or in pipelines to continuously validate documentation against the actual codebase after refactors.

Does the reality report classify documentation issues by severity?▼

Yes, the reality report classifies detected documentation drift by severity. It assesses mismatches between the README and the actual codebase, providing a clear, structured report for teams to prioritize and address structural discrepancies.