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
- aws-samples/sample-apex-skillstheir own version, first seen Nov 15, 2026
- therain2020/therain2020-agenttheir own version, first seen Nov 15, 2026
- charlesmsiegel/coding-skillstheir own version, first seen Nov 15, 2026
- alexj11324/Mikkatheir own version, first seen Nov 15, 2026
- iuliandita/skillstheir own version, first seen Nov 15, 2026
- caipe-io/ai-platform-engineeringtheir own version, first seen Nov 12, 2026
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-healthSkillget-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-healthSkillpush-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
TheKREATORSSkillinstinct-export
Export instincts from project/global scope to a file
Also in 3 projects that use this
TheKREATORSSkillinstinct-import
Import instincts from file or URL into project/global scope
Also in 3 projects that use this
NVIDIASkillgenerate-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
belokonmSkillfullstack-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
Other versions90 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 90
- vercel/next.js★ 144ksame name
- pipecat-ai/pipecat★ 17ksame name
- anyproto/anytype-ts★ 9.1ksame name
- vladmandic/sdnext★ 7.4ksame name
- ArcReel/ArcReel★ 6.6ksame name
- dotnet/sdk★ 3.2ksame name
- huggingface/OpenEnv★ 2.9ksame name
- meta-pytorch/OpenEnv★ 2.8ksame name
- man-group/ArcticDB★ 2.6ksame name
- fabro-sh/fabro★ 1.8ksame name
80 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository18 other files it gives its agents.
- AGENTS.mdAGENTS.md
- agent-setupSkill
- config-flowSkill
- coverageSkill
- documentationSkill
- elementsSkill
- explain-planSkill
- integrationSkill
- lintSkill
- manifestSkill
- modelSkill
- performanceSkill
- pythonSkill
- release-notesSkill
- scenariosSkill
- testingSkill
- translationsSkill
- update-versionSkill
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
- Very specific: line 37
New elements: Create documentation in both docs/user-guide/elements/ and docs/modeling/device-layer/ (and model-layer/ if applicable)
- Very specific: line 38
Use templates from docs/developer-guide/templates/ as starting points
- Distinctive: line 39
Follow element documentation patterns from existing elements
- Very specific: line 40
New configuration options: Update relevant element pages in docs/user-guide/elements/
- Very specific: line 41
New sensors: Document in element pages and update docs/user-guide/forecasts-and-sensors.md if behavior changes
- Very specific: line 42
New developer APIs: Document in docs/developer-guide/ with architecture focus, not code reproduction
- Distinctive: line 46
Changed behavior: Update all documentation that describes the old behavior
- Distinctive: line 47
New parameters: Add to configuration documentation with examples
- Distinctive: line 48
API changes: Update developer documentation, link to source code for details
- Distinctive: line 52
Removed functionality: Remove it from the documentation
- Distinctive: line 53
Breaking changes: Document migration path and rationale
- Very specific: line 57
When updating documentation, strictly follow the guidelines in docs/developer-guide/documentation-guidelines.md:
- Distinctive: line 61
Minimalism first: Keep explanations short and purposeful
- Distinctive: line 64
No unverified claims: Avoid quantitative performance statements without benchmarks
- Distinctive: line 65
Consistent terminology: Use "Hub", "Element", "Connection", "Sensor" as defined
- Distinctive: line 70
Sentence case: All headings use sentence case
- Distinctive: line 71
American English: Use American spelling throughout
- Distinctive: line 72
Backticks: Use for file paths, filenames, variable names, field entries
- Distinctive: line 85
Next steps section: All user-facing pages must end with a Next steps section using Material grid cards format
- Distinctive: line 87
No code samples: Avoid code in user-facing docs (except configuration YAML examples)
- Distinctive: line 97
Use mermaid: All diagrams must use mermaid format
- Distinctive: line 98
Semantic colors: Use default styling (blue for general, green for generation, red for consumption, yellow for grid/pricing)
- Very specific: line 124
Add each new page to the nav in mkdocs.yml.
- Distinctive: line 128
If changes affect core integration behavior:
- Distinctive: line 135
If changes affect data loading or sensors:
- Distinctive: line 142
Before finalizing documentation updates:
- Distinctive: line 157
Maintain consistency: Follow existing patterns and conventions
- Very specific: line 158
Build and verify links: Run uv run zensical build, which fails on any broken internal link or anchor
- Distinctive: line 159
Review formatting: Ensure semantic line breaks and proper markdown structure
“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.
Files
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:
- Get the diff: Compare the current branch to
mainusinggit diff origin/main...HEAD 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)
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
- User-facing changes →
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/anddocs/modeling/device-layer/(andmodel-layer/if applicable)- Use templates from
docs/developer-guide/templates/as starting points - Follow element documentation patterns from existing elements
- Use templates from
- 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.mdif 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
- Forecasts/sensors →
- 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:
User guide:
docs/user-guide/elements/, one page per element type a user configures, such as{element_type}.mdfor itsElementTypevalue- Configuration fields
- Examples
- Sensors created
- Troubleshooting
Modeling docs:
docs/modeling/device-layer/for how an element type maps onto model elementsdocs/modeling/model-layer/for the model element types registered inELEMENTS(core/model/elements/__init__.py): network and flow-reading elements underelements/, the connection underconnections/, and its segments undersegments/
- 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:
- User guide:
docs/user-guide/configuration.md,docs/user-guide/optimization.md, etc. - Developer guide:
docs/developer-guide/architecture.md,docs/developer-guide/coordinator.md, etc.
Data loading changes
If changes affect data loading or sensors:
- User guide:
docs/user-guide/forecasts-and-sensors.md - 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 buildfails 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
- Read existing docs: Understand current documentation structure and style
- Identify gaps: Determine what's missing or outdated
- Update systematically: Work through each affected documentation area
- Maintain consistency: Follow existing patterns and conventions
- Build and verify links: Run
uv run zensical build, which fails on any broken internal link or anchor - 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.
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.

