skills.rest
ab300819
ab300819COMMUNITY
Explore all skills by this author →
GitHub

code-self-describe

Generates and maintains module-level CLAUDE.md files and source file header comments for codebases.

Updated Jan 12, 2026
Search Tags:#audit#claude.md#code documentation#git diff#codebase onboarding#module description#header comments
One-click install
npx skills add https://github.com/ab300819/keel-workflow --skill code-self-describe-ab300819
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: code-self-describe
Source: https://github.com/ab300819/keel-workflow/tree/main/skills/code-self-describe
Command: npx skills add https://github.com/ab300819/keel-workflow --skill code-self-describe-ab300819

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? AI assistants and new team members struggle to understand unfamiliar codebases because module roles, dependencies, and file responsibilities are undocumented. This Skill creates a three-layer self-describing structure (project root, module-level CLAUDE.md, and file header comments) so AI tools progressively load context as they navigate the code. ## Core Features & Use Cases - Init mode: Scans project structure, detects language and framework, then generates module-level CLAUDE.md files and INPUT/OUTPUT/POS header comments for each source file. - Update mode: Detects code changes via git diff, updates affected header comments and module descriptions, and propagates changes upward only when public interfaces change. - Audit mode: Reports description coverage, missing descriptions, and stale entries without modifying any files. - Use Case: After refactoring an authentication module, run the update mode to refresh the module's CLAUDE.md business domain list and the changed files' INPUT/OUTPUT annotations while preserving manually written constraint sections. ## Quick Start Ask the AI to run code-self-describe in init mode to generate CLAUDE.md files and header comments for the current project.

Frequently Asked Questions about code-self-describe

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

FAQPage Schema
How do I generate CLAUDE.md files for my project modules?▼

Run the init mode, which scans your project structure, identifies the language and framework from files like package.json or go.mod, detects module boundaries, and generates a CLAUDE.md per module plus header comments per source file. Each module description is confirmed with you before writing.

How do I keep code documentation in sync after refactoring?▼

Use the update mode, which detects changed files via git diff, refreshes their INPUT/OUTPUT header comments, and updates the affected module CLAUDE.md files. Changes propagate upward to parent modules only when public interfaces change, and manually written sections are never modified.

What is the INPUT OUTPUT POS header comment format?▼

It is a three-line comment placed at the very top of a source file before imports. INPUT lists dependencies from import analysis, OUTPUT lists exported functions and classes, and POS describes the file's role in the system. Examples are provided for TypeScript, Python, Go, Java, C#, Rust, Swift, and Kotlin.

Does the audit mode modify any files?▼

No, audit mode is strictly read-only. It scans all CLAUDE.md files and header comments, compares them against actual code, and reports coverage statistics, missing descriptions, and stale entries with specific reasons such as newly added methods or missing dependencies.

When should I not write documentation into the code repository?▼

In shell workspace topologies where private artifacts must stay out of the code repo, the skill skips by default based on the code_metadata_write_policy capability. It only proceeds with the explicit --force-code-docs flag after confirming the repository may be made public.

Related Skills

Explore More Software Engineering Skills→
jovermierjovermier
2

context-detection

Detect languages, frameworks, and package managers from repository artifacts.

Community
Intermediate
bryonjacobbryonjacob

documenting-with-claude-md

Organizes and loads CLAUDE.md documentation hierarchies for AI context.

Community
Basic
wubing7755wubing7755

ada-traceability-audit

Audits requirements traceability matrices against source code to detect stale statuses and missing entries.

Community
Intermediate
modu-aimodu-ai
1.2k

moai-docs-generation

Generates API references, user guides, and documentation sites using Sphinx, MkDocs, TypeDoc, and OpenAPI.

Official
Intermediate