skills.rest
richard-jh-mccrae
richard-jh-mccraeCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

code-as-docs

Enforces a documentation policy where source code serves as the primary documentation.

Updated Jun 25, 2026
Search Tags:#documentation#adr#code comments#docstrings#code discovery#documentation policy
One-click install
npx skills add https://github.com/richard-jh-mccrae/PokemonAI --skill code-as-docs-richard-jh-mccrae
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: code-as-docs
Source: https://github.com/richard-jh-mccrae/PokemonAI/tree/main/.agents/skills/code-as-docs
Command: npx skills add https://github.com/richard-jh-mccrae/PokemonAI --skill code-as-docs-richard-jh-mccrae

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? It prevents redundant, stale, or bloated documentation by establishing a policy where the code itself is the documentation, guiding developers on when comments, docstrings, ADRs, or docs are actually warranted. ## Core Features & Use Cases - Discovery Protocol: Scan the codebase to learn what is already built and where to wire in new work before writing anything. - Comment and Docstring Budget: Applies a size budget so only prose that earns its place survives. - Retirement Protocol: Governs how documentation for deleted names is cleaned up. - Use Case: Before adding a docstring or writing an ADR, consult this policy to decide whether the code already communicates the intent and whether the document is justified. ## Quick Start Read the code-as-docs skill and apply its documentation policy before writing any comment, docstring, or ADR in this repository.

Frequently Asked Questions about code-as-docs

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

FAQPage Schema
How do I decide when to write a docstring or comment?▼

Follow the comment and docstring size budget defined in the policy: prose must earn its place by conveying information the code cannot express. If the code already communicates intent clearly, no comment is warranted.

What is a code-as-docs documentation policy?▼

It is a repository policy treating source code as the primary documentation. It defines a discovery protocol for finding existing implementations, limits on comments and docstrings, and rules for retiring documentation of deleted names.

How do I check if a feature already exists before building it?▼

Use the discovery protocol: scan the codebase to identify what is already built and where new work should wire in. This prevents duplicate implementations and redundant documentation.

When should I write an ADR instead of a code comment?▼

Write an ADR only when a decision's rationale cannot be captured in code or a brief comment. The policy requires justifying any prose, so architectural decisions with lasting tradeoffs are the typical case that earns an ADR.

What happens to documentation when code is deleted?▼

The retirement protocol governs cleanup: documentation referencing deleted names must be removed or updated so stale references do not accumulate in the repository.

Related Skills

Explore More Software Engineering Skills→
vmitsarasvmitsaras

repository-feature-plan

Plans how a new feature fits into an existing repository's architecture, tests, and documentation.

Community
Intermediate
7a336e6e7a336e6e
1

git-workflow

Enforce standardized Git branching, commit messages, and pull request templates.

Community
Intermediate
raybargasraybargas

Global Coding Style

Detect and fix coding style violations across multi-language repositories.

Community
Basic
gocobaltgocobalt
1

doc-reader

Read external documentation and summarize API, SDK, or configuration guidance with source URLs.

Official
Intermediate