agentleFS
Sign inStart free
LedgerHQLedgerHQ/ledger-live/.agents/skills/docs-update-or-create/SKILL.md

docs-update-or-create

Skill627 starsChanged 8 days agoMITView on GitHub

Guidelines that must be followed when creating or updating docs in this repo. Applies to AGENTS.md, README.md, **/docs/**/*.md, skill and sub-agent files. Read when creating or updating those files.

The file

Show its rules and text

We split this skill into the rules it gives an agent

27 rules. About 0 are common, 22 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈22

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Create minimal docs, avoid duplication and make content discoverable.

    line 11
  2. Distinctive:

    Treat docs for both human and AI agents together.

    line 12
  3. Distinctive:

    Follow our principles of progressive disclosure, locality and canonicalization.

    line 13
  4. Distinctive:

    Write/update the files, inline with what's agreed

    line 20
  5. Distinctive:

    Avoid long files containing multiple levels of details

    line 31
  6. Distinctive:

    Avoid overloading context with rarely used knowledge

    line 32
  7. Distinctive:

    Avoid duplicating knowledge in multiple files

    line 33
  8. Distinctive:

    Avoid documenting community-obvious knowledge

    line 34
  9. Distinctive:

    Avoid preserving old structure for its own sake

    line 35
  10. Distinctive:

    Add docs that measurably improve agent performance

    line 39
  11. Distinctive:

    Do document repeatable workflows, commands and behaviours

    line 40
  12. Distinctive:

    Only add docs that solve real problems

    line 42
  13. Distinctive:

    Delete files that have no unique value after changes

    line 43
  14. Distinctive:

    Use emojis, checkboxes and formatting sparingly to make docs more appealing

    line 44
  15. Distinctive:

    Keep it short and direct. Treat 100 lines as a target (not a hard limit)

    line 48
  16. Distinctive:

    Keep each file at one level of detail.

    line 49
  17. Distinctive:

    Use short inline examples when they replace explanation.

    line 51
  18. Very specific:

    Add allowed-tools, or compatibility only when they help.

    line 59
  19. Very specific:

    Use disable-model-invocation: true for user-invoked skills (commands)

    line 60
  20. Very specific:

    Use user-invocable: false for agent-only skills

    line 61
  21. Distinctive:

    Follow our rules on docs locality

    line 75
  22. Distinctive:

    Avoid duplication by applying rules on canonicalization

    line 76
  23. Distinctive:

    Make sure links point to the canonical source

    line 80
  24. Distinctive:

    Ensure it is discoverable by agents and humans

    line 81
  25. Very specific:

    Search for duplicated key phrases with rg

    line 82
  26. Very specific:

    Check long docs with wc -l.

    line 83
  27. Distinctive:

    Verify AGENTS.md stays minimal.

    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

Create or Update Docs

Create minimal docs, avoid duplication and make content discoverable. Treat docs for both human and AI agents together. Follow our principles of progressive disclosure, locality and canonicalization.

📝 Process to follow

  1. Understand the topic of knowledge and its purpose
  2. Gather existing knowledge on that topic
  3. Agree on the best format and location for it to live
  4. Write/update the files, inline with what's agreed
  5. Validate the results and refine as necessary

📜 Guidelines

These guidelines define some boundaries within which to operate. They do not dictate everything. Follow them, but also use judgement and creativity to find the best way to document knowledge in each case.

❌ BAD:

  • Avoid long files containing multiple levels of details
  • Avoid overloading context with rarely used knowledge
  • Avoid duplicating knowledge in multiple files
  • Avoid documenting community-obvious knowledge
  • Avoid preserving old structure for its own sake

✅ GOOD:

  • Add docs that measurably improve agent performance
  • Do document repeatable workflows, commands and behaviours
  • Capture what is peculiar to this repo, domain, or team
  • Only add docs that solve real problems
  • Delete files that have no unique value after changes
  • Use emojis, checkboxes and formatting sparingly to make docs more appealing

Keep it short

  • Keep it short and direct. Treat 100 lines as a target (not a hard limit)
  • Keep each file at one level of detail.
  • Link to narrower docs when detail must branch.
  • Use short inline examples when they replace explanation.
  • Link longer examples instead of embedding them.

Use frontmatter

  • Skill and agent definitions should use frontmatter to be discoverable by tools.
  • Frontmatter for READMEs is optional. If it's useful for you, include it
  • Tool-discoverable docs and skills should have name and description
  • Add allowed-tools, or compatibility only when they help.
  • Use disable-model-invocation: true for user-invoked skills (commands)
  • Use user-invocable: false for agent-only skills

Frontmatter Example for a skill

---
name: desktop-swap-guidance
description: Read when editing swap flows in Ledger Live Desktop.
---

💡 Principles

  • Apply principle of progressive disclosure
  • Follow our rules on docs locality
  • Avoid duplication by applying rules on canonicalization

🔎 Validation

  • Make sure links point to the canonical source
  • Ensure it is discoverable by agents and humans
  • Search for duplicated key phrases with rg
  • Check long docs with wc -l.
  • Verify AGENTS.md stays minimal.

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