skills.rest
YuriGarciaRibeiro
YuriGarciaRibeiroCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

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
One-click install
npx skills add https://github.com/YuriGarciaRibeiro/API-notifications --skill repo-reality-check
Or copy as Structured Prompt for Agent▼
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.

Related Skills

Explore More Software Engineering Skills→
mohamedgshoaibmohamedgshoaib
5

write-project-readme

Generates README files from scanned repository contents and metadata.

Community
Intermediate
nikhillinitnikhillinit

documentation-sync

Detect code and documentation drift and validate embedded examples.

Community
Advanced
oalansilvaoalansilva

lint-and-validate

Run configured linters and type checkers for Node.js and Python projects.

Community
Advanced
JongsixJongsix

moai-docs-generation

Generate technical documentation from source code and API definitions.

Community
Advanced