skills.rest
provectus
provectusOFFICIAL
Explore all skills by this author →
WebsiteGitHub

docs-that-work

Provide guidelines for writing project documentation for human and AI consumption.

10|17|Updated Feb 22, 2026
Search Tags:#best practices#documentation#ai#developer experience#readme#claude.md
One-click install
npx skills add https://github.com/provectus/awos-recruitment --skill docs-that-work
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: docs-that-work
Source: https://github.com/provectus/awos-recruitment/tree/main/registry/skills/docs-that-work
Command: npx skills add https://github.com/provectus/awos-recruitment --skill docs-that-work

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill addresses the challenge of creating documentation that is both understandable to human readers and easily processable by AI agents, ensuring clarity and discoverability.

Core Features & Use Cases

  • Discoverability Rule Enforcement: Guides users to document only what cannot be inferred from code.
  • Structured Documentation: Provides clear guidelines for CLAUDE.md and README.md to maximize utility and minimize bloat.
  • Use Case: When tasked with creating documentation for a new project, use this Skill to ensure the README.md is actionable for onboarding and CLAUDE.md provides essential, non-discoverable context for AI agents.

Quick Start

Use the docs-that-work skill to generate a CLAUDE.md file for a new Python project.

Frequently Asked Questions about docs-that-work

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

FAQPage Schema
How do I write project documentation that works for both humans and AI agents?▼

To write project documentation for humans and AI, apply the discoverability rule by only documenting what cannot be inferred from the code. This ensures clarity and easy processability for both human readers and AI agents.

What should I include in a CLAUDE.md file for my development project?▼

A CLAUDE.md file should provide essential, non-discoverable context for AI agents. It should focus on delivering architectural decisions, cross-service contracts, and environment-specific gotchas that the AI cannot infer from the source code.

What is the discoverability rule for writing effective README files?▼

The discoverability rule for README files means documenting only what cannot be directly inferred from the code. This minimizes documentation bloat and ensures the remaining content is actionable for onboarding.

When do I need to document architectural decisions and cross-service contracts?▼

You need to document architectural decisions and cross-service contracts when this context is essential for explaining project structure but cannot be easily inferred from the codebase by humans or AI agents.

Does this approach to documentation separate instructions for different audiences?▼

Yes, this approach uses document separation principles to keep instructions distinct. It structures README files for human onboarding and CLAUDE.md files specifically for AI context, maximizing utility without creating bloat.

Related Skills

Explore More Content & Communication Skills→
liuzeming-yuxiliuzeming-yuxi
9

superclaw-onboard

Generate a centralized project context document from repository metadata and config files.

Community
Intermediate
levnikolaevichlevnikolaevich
534

ln-111-root-docs-creator

Generate four root documentation files from a Context Store with template substitution.

Community
Advanced
ClawStackStudiosClawStackStudios

Truthpack Updater Skill

Update a project's truthpack with route, environment, and security changes.

Community
Intermediate
vasilyu1983vasilyu1983
73

docs-codebase

Generate documentation templates for READMEs, ADRs, API docs, and changelogs.

Community
Intermediate