agentleFS
hass-energyhass-energy/haeo/.agents/skills/update-docs/SKILL.md

update-docs

Skill77 starsChanged 20 days agoMITView on GitHub

Update documentation to match the code changes on the current branch. Use after implementing a feature or refactor, when asked to update the docs, or when a change affects user guides, developer guides, modeling docs, or element documentation.

90 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use get-pr-reviews, push-everything and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • saffron-healthSkill

    get-pr-reviews

    Get nicely formatted output of the last review comments on a PR. Used internally by other skills.

    Also in 3 projects that use this

  • saffron-healthSkill

    push-everything

    Stage ALL changes in the repository (not just session changes), commit, and push. Use when you need to commit all pending changes.

    Also in 3 projects that use this

  • TheKREATORSSkill

    instinct-export

    Export instincts from project/global scope to a file

    Also in 3 projects that use this

  • TheKREATORSSkill

    instinct-import

    Import instincts from file or URL into project/global scope

    Also in 3 projects that use this

  • NVIDIASkill

    generate-spec

    Produce a feature specification covering API changes, backward compatibility, cross-language impact, performance, and a file-level change plan. Use when designing a new feature, planning a significant change, or the user asks to spec something out.

    Also in 3 projects that use this

  • belokonmSkill

    fullstack-developer

    End-to-end feature expert specializing in frontend-backend integration, system architecture, and complete application development

    Also in 4 projects that use this

  • +1 more from saffron-health
  • +1 more from TheKREATORS

The file

Show its rules and text

We split this skill into the rules it gives an agent

29 rules. 0 are common, 21 are distinctive, and 8 are very specific to this project.

  • 0

    Common

    Most of the 84 edited versions we read keep these.

  • 21

    Distinctive

    This author's own choices. Worth a look.

  • 8

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    New elements: Create documentation in both docs/user-guide/elements/ and docs/modeling/device-layer/ (and model-layer/ if applicable)

    line 37
  2. Very specific:

    Use templates from docs/developer-guide/templates/ as starting points

    line 38
  3. Distinctive:

    Follow element documentation patterns from existing elements

    line 39
  4. Very specific:

    New configuration options: Update relevant element pages in docs/user-guide/elements/

    line 40
  5. Very specific:

    New sensors: Document in element pages and update docs/user-guide/forecasts-and-sensors.md if behavior changes

    line 41
  6. Very specific:

    New developer APIs: Document in docs/developer-guide/ with architecture focus, not code reproduction

    line 42
  7. Distinctive:

    Changed behavior: Update all documentation that describes the old behavior

    line 46
  8. Distinctive:

    New parameters: Add to configuration documentation with examples

    line 47
  9. Distinctive:

    API changes: Update developer documentation, link to source code for details

    line 48
  10. Distinctive:

    Removed functionality: Remove it from the documentation

    line 52
  11. Distinctive:

    Breaking changes: Document migration path and rationale

    line 53
  12. Very specific:

    When updating documentation, strictly follow the guidelines in docs/developer-guide/documentation-guidelines.md:

    line 57
  13. Distinctive:

    Minimalism first: Keep explanations short and purposeful

    line 61
  14. Distinctive:

    No unverified claims: Avoid quantitative performance statements without benchmarks

    line 64
  15. Distinctive:

    Consistent terminology: Use "Hub", "Element", "Connection", "Sensor" as defined

    line 65
  16. Distinctive:

    Sentence case: All headings use sentence case

    line 70
  17. Distinctive:

    American English: Use American spelling throughout

    line 71
  18. Distinctive:

    Backticks: Use for file paths, filenames, variable names, field entries

    line 72
  19. Distinctive:

    Next steps section: All user-facing pages must end with a Next steps section using Material grid cards format

    line 85
  20. Distinctive:

    No code samples: Avoid code in user-facing docs (except configuration YAML examples)

    line 87
  21. Distinctive:

    Use mermaid: All diagrams must use mermaid format

    line 97
  22. Distinctive:

    Semantic colors: Use default styling (blue for general, green for generation, red for consumption, yellow for grid/pricing)

    line 98
  23. Very specific:

    Add each new page to the nav in mkdocs.yml.

    line 124
  24. Distinctive:

    If changes affect core integration behavior:

    line 128
  25. Distinctive:

    If changes affect data loading or sensors:

    line 135
  26. Distinctive:

    Before finalizing documentation updates:

    line 142
  27. Distinctive:

    Maintain consistency: Follow existing patterns and conventions

    line 157
  28. Very specific:

    Build and verify links: Run uv run zensical build, which fails on any broken internal link or anchor

    line 158
  29. Distinctive:

    Review formatting: Ensure semantic line breaks and proper markdown structure

    line 159

“Common” is measured: kept by at least 6 in 10 of the 84 edited versions of this file we could read. “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

Update documentation based on branch changes

Analyze the differences between the current branch and the main branch, then update the relevant documentation to reflect all code changes.

Step 1: Analyze git changes

First, identify what has changed:

  1. Get the diff: Compare the current branch to main using git diff origin/main...HEAD
  2. Categorize changes:

    • New features (new files, new functions, new classes)
    • Modified features (changed behavior, updated APIs)
    • Deleted features (removed functionality)
    • Bug fixes (behavior corrections)
    • Refactoring (internal changes without behavior changes)
  3. Map changes to documentation areas:

    • User-facing changes → docs/user-guide/ (configuration, usage, examples)
    • Developer-facing changes → docs/developer-guide/ (architecture, APIs, extension points)
    • Model/mathematical changes → docs/modeling/ (LP formulation, constraints, cost functions)
    • Element-specific changes → Both user-guide and modeling docs for that element

Step 2: Documentation update strategy

For each identified change, determine what documentation needs updating:

New features

  • New elements: Create documentation in both docs/user-guide/elements/ and docs/modeling/device-layer/ (and model-layer/ if applicable)
    • Use templates from docs/developer-guide/templates/ as starting points
    • Follow element documentation patterns from existing elements
  • New configuration options: Update relevant element pages in docs/user-guide/elements/
  • New sensors: Document in element pages and update docs/user-guide/forecasts-and-sensors.md if behavior changes
  • New developer APIs: Document in docs/developer-guide/ with architecture focus, not code reproduction

Modified features

  • Changed behavior: Update all documentation that describes the old behavior
  • New parameters: Add to configuration documentation with examples
  • API changes: Update developer documentation, link to source code for details

Deleted features

  • Removed functionality: Remove it from the documentation
  • Breaking changes: Document migration path and rationale

Step 3: Follow documentation guidelines

When updating documentation, strictly follow the guidelines in docs/developer-guide/documentation-guidelines.md:

Core principles

  • Minimalism first: Keep explanations short and purposeful
  • Match audience: User docs for UI tasks, developer docs for architecture
  • Link to Home Assistant: Reference HA developer docs for standard concepts
  • No unverified claims: Avoid quantitative performance statements without benchmarks
  • Consistent terminology: Use "Hub", "Element", "Connection", "Sensor" as defined

Formatting requirements

  • Semantic line breaks: One sentence per line, optional breaks at clause boundaries
  • Sentence case: All headings use sentence case
  • American English: Use American spelling throughout
  • Backticks: Use for file paths, filenames, variable names, field entries

DRY principle

  • Link, don't duplicate: Reference existing authoritative sources rather than repeating information
  • Single source of truth:
    • Forecasts/sensors → docs/user-guide/forecasts-and-sensors.md
    • Units → docs/developer-guide/units.md
    • Home Assistant concepts → Link to HA developer docs
  • Progressive disclosure: High-level pages describe patterns, detail pages provide specifics

User-facing pages

  • Next steps section: All user-facing pages must end with a Next steps section using Material grid cards format
  • Actionable content: Provide clear instructions or outcomes for every step
  • No code samples: Avoid code in user-facing docs (except configuration YAML examples)

Developer-facing pages

  • Architecture focus: Explain design intent, extension points, and reasoning
  • Link to source: Point to GitHub source files rather than copying code
  • Conceptual explanations: Describe algorithms conceptually, not line-by-line

Diagrams

  • Use mermaid: All diagrams must use mermaid format
  • Semantic colors: Use default styling (blue for general, green for generation, red for consumption, yellow for grid/pricing)
  • Appropriate chart types: Flowcharts for topology, XY charts for time series, state diagrams for modes

Step 4: Documentation structure mapping

Map code changes to specific documentation locations:

Element changes

Element pages are usually named after the type they document, but not every type has every page, and a few live elsewhere. Find the existing pages in the mkdocs.yml nav, or by searching docs/ for the type, before assuming a path:

  1. User guide: docs/user-guide/elements/, one page per element type a user configures, such as {element_type}.md for its ElementType value

    • Configuration fields
    • Examples
    • Sensors created
    • Troubleshooting
  2. Modeling docs:

    • docs/modeling/device-layer/ for how an element type maps onto model elements
    • docs/modeling/model-layer/ for the model element types registered in ELEMENTS (core/model/elements/__init__.py): network and flow-reading elements under elements/, the connection under connections/, and its segments under segments/
  3. Developer guide: docs/developer-guide/ (if architecture or extension points change)

Add each new page to the nav in mkdocs.yml.

Integration changes

If changes affect core integration behavior:

  1. User guide: docs/user-guide/configuration.md, docs/user-guide/optimization.md, etc.
  2. Developer guide: docs/developer-guide/architecture.md, docs/developer-guide/coordinator.md, etc.

Data loading changes

If changes affect data loading or sensors:

  1. User guide: docs/user-guide/forecasts-and-sensors.md
  2. Developer guide: docs/developer-guide/data-loading.md

Step 5: Consistency checks

Before finalizing documentation updates:

  • Terminology: Verify consistent use of "Hub", "Element", "Connection", "Sensor"
  • Units: Power in kW, energy in kWh, prices in $/kWh, time in seconds (internal) or hours (user-facing)
  • Links: Every internal link and anchor resolves; uv run zensical build fails if one does not
  • Cross-references: Update links to changed sections
  • Next steps: Ensure user-facing pages have Next steps sections
  • Templates: Use templates for new element documentation
  • Progressive disclosure: High-level pages describe patterns, not enumerate implementations

Step 6: Update process

  1. Read existing docs: Understand current documentation structure and style
  2. Identify gaps: Determine what's missing or outdated
  3. Update systematically: Work through each affected documentation area
  4. Maintain consistency: Follow existing patterns and conventions
  5. Build and verify links: Run uv run zensical build, which fails on any broken internal link or anchor
  6. Review formatting: Ensure semantic line breaks and proper markdown structure

Output

Provide a summary of:

  • Files changed in the branch
  • Documentation files updated
  • New documentation files created (if any)
  • Key changes made to each documentation file
  • Any documentation that may need manual review

Focus on accuracy, consistency, and adherence to HAEO documentation standards.

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.