This skill should be used when creating README files, CONTRIBUTING guides, SUPPORT documentation, or any core repository documentation. Triggers when user asks to "create a README", "write documentation", "generate CONTRIBUTING", "add support docs", or discusses repository documentation standards and best practices.
From readme-and-conpx claudepluginhub aaronbassett/agent-foundry --plugin readme-and-coThis skill uses the workspace's default tool permissions.
examples/CONTRIBUTING-basic.mdexamples/README-comprehensive.mdexamples/README-minimal.mdexamples/README-standard.mdreferences/contributing-patterns.mdreferences/readme-examples.mdreferences/support-structures.mdDesigns and optimizes AI agent action spaces, tool definitions, observation formats, error recovery, and context for higher task completion rates.
Implements structured self-debugging workflow for AI agent failures: capture errors, diagnose patterns like loops or context overflow, apply contained recoveries, and generate introspection reports.
Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.
Provide comprehensive guidance for creating high-quality GitHub repository documentation following industry best practices. This skill covers README structure, contributing guidelines, support resources, and documentation organization.
Use this skill when:
The README is the entry point to any repository. Essential sections include:
Must-have sections:
Recommended sections:
Optional but valuable:
Structure pattern:
# Project Name
Brief description (1-2 sentences)
## Features
## Installation
## Usage
## Contributing
## License
Guides contributors through the contribution process.
Essential elements:
Structure levels:
Basic (for simple projects):
Standard (recommended):
Comprehensive (for large projects):
Defines how users get help.
Key sections:
Variants:
Basic: Links to issue tracker and communication channels
Detailed: Includes troubleshooting guides, FAQ, escalation paths
Write for the target audience:
Structure documentation from basic to advanced:
Across files:
Within files:
Documentation rots quickly. Strategies:
Adapt documentation to project characteristics:
Language/Framework:
Project Type:
Audience:
# Library Name
Description of what the library does
## Installation
[Package manager commands]
## Quick Start
[Minimal example]
## API Reference
[Key functions/classes]
## Examples
[Common use cases]
# Application Name
What the application does and why
## Features
[Key capabilities]
## Getting Started
### Prerequisites
### Installation
### Configuration
## Usage
[How to use the application]
## Deployment
[Production deployment guide]
# Tool Name
One-line description
## Installation
[Install command]
## Usage
```bash
tool-name [options] <arguments>
[Command reference]
[Common workflows]
## Documentation Anti-Patterns
**Avoid:**
- Duplicating information that exists in code comments
- Screenshots that become outdated quickly
- Installation instructions for every OS when package managers work cross-platform
- Extensive API documentation in README (link to generated docs)
- Mixing user docs with contributor docs
**Instead:**
- Link to generated API docs
- Use badges for CI status, not screenshots
- Focus on primary installation method, link to wiki for alternatives
- Separate user docs (README) from contributor docs (CONTRIBUTING)
## Additional Resources
### Reference Files
For detailed guidance and examples:
- **`references/readme-examples.md`** - Analysis of stellar README files with patterns extracted
- **`references/contributing-patterns.md`** - Contributing guide structures from major projects
- **`references/support-structures.md`** - Support documentation examples and patterns
### Example Files
Working documentation templates in `examples/`:
- **`examples/README-minimal.md`** - Minimal README template
- **`examples/README-standard.md`** - Standard README with common sections
- **`examples/CONTRIBUTING-basic.md`** - Basic contributing guidelines
## Quick Reference
**README checklist:**
- [ ] Clear title and description
- [ ] Installation instructions
- [ ] Usage example
- [ ] License specified
- [ ] Contributing link (if accepting contributions)
**CONTRIBUTING checklist:**
- [ ] Development environment setup
- [ ] Testing instructions
- [ ] PR process explained
- [ ] Code style guidelines
- [ ] Code of conduct link
**SUPPORT checklist:**
- [ ] Where to ask questions
- [ ] How to report bugs
- [ ] Available resources
- [ ] Response expectations
Consult reference files for detailed patterns and real-world examples.