agentleFS
sametcelikbicaksametcelikbicak/opencode-team/skills/team-docs/SKILL.md

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.

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
  1. Distinctive:

    Verify everything you document: Do not write it if you have not run the command.

    line 10
  2. Distinctive:

    Every command in a copyable block

    line 30
  3. Distinctive:

    If it works, write its output into the README.

    line 40
  4. Distinctive:

    If it does not work, either fix it or remove it from the README.

    line 41
  5. Distinctive:

    If you cannot do this, do not write that section of the README and report it as "unverifiable".

    line 43
  6. Distinctive:

    Do not write more than 10 decisions.

    line 84

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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
## License

Rules:

  • 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:

  1. Run the command.
  2. If it works, write its output into the README.
  3. 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

MethodPathAuthBodyResponseErrors

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

MistakeThe right way
Writing a command you have not runRun it or do not write it
Badge, emoji and "Built with" clutterOnly information that is useful
"See the docs for details"Write the detail
Repeating the same information everywhereOne source, link to it
Leaving outdated documentation aroundUpdate 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.