team-docs
Skill69 starsChanged 19 days agoMITView on GitHub
Technical documentation writing methodology. README, usage guide, API documentation and architecture note. The playbook of the docs role.
In this repository15 other files it gives its agents.
- docs/agents.mdAGENTS.md
- team/AGENTS.mdAGENTS.md
- team-architectureSkill
- team-backlogSkill
- team-brandSkill
- team-buildSkill
- team-disciplineSkill
- team-marketingSkill
- team-market-researchSkill
- team-memorySkill
- team-prdSkill
- team-qaSkill
- team-releaseSkill
- team-security-reviewSkill
- team-uxSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 6 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 10
Verify everything you document: Do not write it if you have not run the command.
- Distinctive: line 30
Every command in a copyable block
- Distinctive: line 40
If it works, write its output into the README.
- Distinctive: line 41
If it does not work, either fix it or remove it from the README.
- Distinctive: line 43
If you cannot do this, do not write that section of the README and report it as "unverifiable".
- Distinctive: line 84
Do not write more than 10 decisions.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Technical Documentation
Core principle
Verify everything you document. Do not write it if you have not run the command. Do not write it if you have not read the code. Wrong documentation is worse than no documentation — the user looks in the wrong direction.
README template
# Project Name
One sentence: what it does.
## Installation
## Usage
## Development
## Test
## Deployment
## Architecture (short)
## Contributing
## LicenseRules:
- Every command in a copyable block
- Prerequisites (runtime version, required tools) stated explicitly
- "Requirements" section with version numbers (Node 20+)
- A project explainable in 5 lines should have a 5-line README. An overly long README is a badly written README.
Verification loop
For every command:
- Run the command.
- If it works, write its output into the README.
- If it does not work, either fix it or remove it from the README.
If you cannot do this, do not write that section of the README and report it as "unverifiable".
API documentation
| Method | Path | Auth | Body | Response | Errors |
An example for each endpoint:
POST /api/v1/invoices
POST /api/v1/invoices
Content-Type: application/json
Authorization: Bearer <token>{ "number": "INV-2026-001", "total": 249.90, "currency": "EUR" }201 Created
{ "id": "inv_01H...", "number": "INV-2026-001", "total": 249.90, "currency": "EUR" }The error body format and a list of error codes (400 / 401 / 403 / 404 / 422 / 500).
Architecture note
A short ADR-like note:
## Decision: <topic>
**Context:** <why this decision is needed>
**Decision:** <what we are doing>
**Alternatives:** <the ones not chosen and why>
**Consequences:** <the benefit and the cost>Do not write more than 10 decisions. Write the 5-10 most impactful ones.
Language rule
README, API documentation, code examples, comments → English.
Common mistakes
| Mistake | The right way |
| Writing a command you have not run | Run it or do not write it |
| Badge, emoji and "Built with" clutter | Only information that is useful |
| "See the docs for details" | Write the detail |
| Repeating the same information everywhere | One source, link to it |
| Leaving outdated documentation around | Update or delete it |
Output format
A list of the files written/updated + what was added to each file. Also a list of the points that could not be documented and what is still missing.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

