Muriel-SalvanMuriel-Salvan/x_aeon_agents/skills/updating-doc/SKILL.md

updating-doc

Skill2 starsChanged 2 months agoBSD-3-ClauseView on GitHub

Update the documentation of the project. What this does is update the README file of the project, its CLI usage and its Table of Content. Use this when a new development has been completed or when the user is asking for documentation or README to be updated.

In this repository14 other files it gives its agents.
- AGENTS.mdAGENTS.md
- addressing-pull-request-commentsSkill
- analyzing-github-issueSkill
- applying-ruby-conventionsSkill
- applying-test-conventionsSkill
- committing-changesSkill
- creating-pull-requestSkill
- editing-filesSkill
- enforcing-project-rulesSkill
- implementing-github-issueSkill
- improving-agent-reflectionSkill
- running-cli-in-wsl-portableSkill
- syncing-branch-with-baseSkill
- validating-production-qualitySkill

The file

Show its rules and text

We split this skill into the rules it gives an agent

17 rules. About 0 are common, 16 are distinctive, and 1 is very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈16
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
When updating documentation, follow those steps.
line 10
Distinctive:
Before executing anything, create a checklist named updating-doc Execution Checklist with all steps of these instructions.
line 14
Distinctive:
After completing each step of these instructions, mark the item in the updating-doc Execution Checklist as completed.
line 16
Distinctive:
Do not skip any item.
line 17
Distinctive:
If an item cannot be executed, explicitly explain why.
line 18
Distinctive:
Never mark the task as completed while any item from the updating-doc Execution Checklist remains open.
line 19
Distinctive:
Always tell the user "SKILL: I am updating documentation" to inform the user that you are running this skill.
line 23
Distinctive:
Always read the existing README content and think about which parts of it should be updated with the task you just implemented.
line 27
Distinctive:
Always adapt the content to what is relevant for the task you implemented.
line 28
Distinctive:
Always check if the real CLI options are documented correctly in the Usage section of the README file.
line 50
Distinctive:
Always make sure that the section "Table of Contents" of the README file is listing exactly all the headers as local links to their …
line 70
Distinctive:
Before declaring the task complete:
line 95
Distinctive:
If any step was not executed, execute it now.
line 99
Very specific:
Always use it every time another skill specifically mentions skill: updating-doc.
line 103
Distinctive:
Always use it every time the user asks you to update documentation.
line 104
Distinctive:
Use it every time you think documentation should be updated after implementing some changes in the code or tests.
line 105
Distinctive:
If README.md has this content before running this skill:
line 111

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

Updating documentation

Sequential steps to be followed when using this skill

When updating documentation, follow those steps.

Create the updating-doc Execution Checklist (MANDATORY)

Before executing anything, create a checklist named updating-doc Execution Checklist with all steps of these instructions.
The updating-doc Execution Checklist must include all numbered steps explicitly.
After completing each step of these instructions, mark the item in the updating-doc Execution Checklist as completed.
Do not skip any item.
If an item cannot be executed, explicitly explain why.
Never mark the task as completed while any item from the updating-doc Execution Checklist remains open.

1. Inform the user

Always tell the user "SKILL: I am updating documentation" to inform the user that you are running this skill.

2. Check the existing README content

Always read the existing README content and think about which parts of it should be updated with the task you just implemented.
Always adapt the content to what is relevant for the task you implemented.

For example, if README.md has such a section:

## Main features

This executable processes input data files (*.csv) to output statistics.

and you just implemented a feature adding a timeout feature, then you should update this README section like this:

## Main features

This executable processes input data files (*.csv) to output statistics.

### 3. Timeout

If processing a file takes more than a given number of seconds, then processing stops and an error is returned (timeout behaviour).

4. Update the README CLI usage section

Always check if the real CLI options are documented correctly in the Usage section of the README file.

For example, if README.md has such a section:

## CLI options

* `--process FILE`: Specify the file to process

and you just implemented a feature adding a CLI timeout option, then you should update this README section like this:

## CLI options

* `--process FILE`: Specify the file to process
* `--timeout SECS`: Specify the number of seconds before processing times out (default: 60)

5. Update the README table of content

Devise the hierarchical list of all Markdown headers that are in the README file, of all levels. Don't forget about headers that you may have added in previous steps.
Always make sure that the section "Table of Contents" of the README file is listing exactly all the headers as local links to their section, and indented in accordance with their hierarchical level in the file.

For example, if README.md has such a section:

## Table of Content

- [Main features](#main_features)
- [CLI options](#cli_options)
- [Testing](#testing)
- [License](#license)

and you just add a sub-section describing the timeout feature, then you should update this README section like this:

## Table of Content

- [Main features](#main_features)
  - [Timeout](#timeout)
- [CLI options](#cli_options)
- [Testing](#testing)
- [License](#license)

Final Verification (MANDATORY)

Before declaring the task complete:

Re-list all numbered steps from the updating-doc Execution Checklist.
Confirm each one was executed.
If any step was not executed, execute it now.

When to use it

Always use it every time another skill specifically mentions skill: updating-doc.
Always use it every time the user asks you to update documentation.
Use it every time you think documentation should be updated after implementing some changes in the code or tests.

Usage and code examples

Updating various sections of README.md when implementing a timeout feature

If README.md has this content before running this skill:

# Data processing

## Table of Content

- [Main features](#main_features)
- [CLI options](#cli_options)
- [Testing](#testing)
- [License](#license)

## Main features

This executable processes input data files (*.csv) to output statistics.

## CLI options

* `--process FILE`: Specify the file to process

## Testing

Run `rspec`.

## License

* BSD.

Then README.md should have this kind of content after running this skill: Before:

# Data processing

## Table of Content

- [Main features](#main_features)
  - [Timeout](#timeout)
- [CLI options](#cli_options)
- [Testing](#testing)
- [License](#license)

## Main features

This executable processes input data files (*.csv) to output statistics.

### Timeout

If processing a file takes more than a given number of seconds, then processing stops and an error is returned (timeout behaviour).

## CLI options

* `--process FILE`: Specify the file to process
* `--timeout SECS`: Specify the number of seconds before processing times out (default: 60)

## Testing

Run `rspec`.

## License

* BSD.

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.

Check your setup, free