python
Skill77 starsChanged 20 days agoMITView on GitHub
Python coding standards for HAEO — modern syntax, type hints, async patterns, error handling, logging, docstrings, and lint suppression rules. Use when writing or modifying any Python code in this repository.
44 other projects use a version of this.
Adopted by
Most recently taken up by
- niksavis/basiclytheir own version, first seen Nov 15, 2026
- niksavis/handilytheir own version, first seen Nov 8, 2026
- testdino-hq/google-styleguides-skillstheir own version, first seen Nov 8, 2026
- its-ash/skillstheir own version, first seen Nov 1, 2026
- shubh3794/claude-code-portabletheir own version, first seen Nov 1, 2026
- rogue-dev-studio/ai-agents-roguetheir own version, first seen Nov 1, 2026
Used with
Projects with it also use android-kotlin, java 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.
alinaqiSkillandroid-kotlin
Android Kotlin development with Coroutines, Jetpack Compose, Hilt, and MockK testing
Also in 4 projects that use this
testdino-hqSkilljava
Google's official Java style guide. Covers 2-space indentation, 100-char line limit, naming conventions, braces, imports, Javadoc, exception handling, lambdas, and streams. Enforces @Override annotations and specific imports.
Also in 6 projects that use this
testdino-hqSkillcsharp
Google's official C# style guide. Covers naming conventions, formatting, LINQ, async/await, XML documentation, and .NET best practices.
Also in 4 projects that use this
ffsshhttiikkSkillflutter
Flutter cross-platform framework
Also in 4 projects that use this
mcollinaSkillnode
Provides domain-specific best practices for Node.js development with TypeScript, covering type stripping, async patterns, error handling, streams, modules, testing, performance, caching, logging, and more. Use when setting up Node.js projects with native TypeScript support, configuring type stripping (--experimental-strip-types), writing Node 22+ TypeScript without a build step, or when the user mentions 'native TypeScript in Node', 'strip types', 'Node 22 TypeScript', '.ts files without compilation', 'ts-node alternative', or needs guidance on error handling, graceful shutdown, flaky tests, profiling, or environment configuration in Node.js. Helps configure tsconfig.json for type stripping, set up package.json scripts, handle module resolution and import extensions, and apply robust patterns across the full Node.js stack.
Also in 4 projects that use this
VercelSkillreact
React renderer for json-render that turns JSON specs into React components. Use when working with @json-render/react, building React UIs from JSON, creating component catalogs, or rendering AI-generated specs.
Also in 7 projects that use this
- +1 more from testdino-hq
Other versions44 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 44
- alinaqi/maggy★ 711same name
- alinaqi/claude-bootstrap★ 708same name
- Mindrally/skills★ 275same name
- kid-sid/claude-spellbook★ 190same name
- nimadorostkar/Claude-Skills-collection★ 37same name
- maroffo/claude-forge★ 17same name
- G1Joshi/Agent-Skills★ 15same name
- kissgyorgy/coding-agents★ 15same name
- testdino-hq/google-styleguides-skills★ 15same name
- harness-studio/harness-studio★ 9same name
34 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
- release-notesSkill
- scenariosSkill
- testingSkill
- translationsSkill
- update-docsSkill
- update-versionSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
24 rules. 0 are common, 15 are distinctive, and 9 are very specific to this project.
0
Common
Most of the 40 edited versions we read keep these.
15
Distinctive
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 20
Add type hints to ALL functions, methods, and variables
- Very specific: line 21
Use modern union syntax: str | None not Optional[str]
- Very specific: line 22
Use type aliases for complex types:
- Distinctive: line 30
Use TypedDict and TypeGuard to narrow types early and use throughout.
- Distinctive: line 31
Prefer the type system over runtime checks - tests should never verify things the type checker can identify.
- Distinctive: line 37
All external I/O must be async
- Very specific: line 38
Avoid await in loops - use asyncio.gather() instead:
- Distinctive: line 47
Never block the event loop:
- Very specific: line 48
Use asyncio.sleep() not time.sleep()
- Very specific: line 49
Use executor for blocking I/O: await hass.async_add_executor_job(fn, args)
- Very specific: line 50
Use @callback decorator for event loop safe functions
- Distinctive: line 54
Fail loudly: Never log an error/warning and continue as if nothing happened.
- Distinctive: line 55
If something fails that should succeed, raise an exception.
- Distinctive: line 75
Keep try blocks minimal - only wrap code that can throw:
- Very specific: line 87
Avoid bare except Exception: except in:
- Distinctive: line 100
No periods at end of messages
- Distinctive: line 101
No integration names (added automatically)
- Distinctive: line 102
No sensitive data (keys, tokens, passwords)
- Distinctive: line 117
Use a bare keyword only when the restructured version would be clearly harder to read.
- Distinctive: line 122
Before adding one, try to restructure the code so the lint rule is satisfied naturally.
- Distinctive: line 123
Only suppress when there is genuinely no reasonable alternative.
- Very specific: line 125
Every # noqa comment must include an explicit reason explaining why the suppression is necessary and why the code cannot be restructured to …
- Very specific: line 154
Never import a private (_name) symbol from another module and silence reportPrivateUsage, in tests as well as code.
- Distinctive: line 155
Test through the public API, make the symbol public when it is genuinely part of the module's interface, or build an independent reference …
“Common” is measured: kept by at least 6 in 10 of the 40 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
Python coding standards
Language requirements
- Python 3.13+ required
- Use modern features:
- Pattern matching (
match/case) - Type hints with modern union syntax:
str | NonenotOptional[str] - f-strings (preferred over
%or.format()) - Dataclasses for data containers
- Walrus operator (
:=) where it improves readability
- Pattern matching (
Type hints
- Add type hints to ALL functions, methods, and variables
- Use modern union syntax:
str | NonenotOptional[str] - Use
typealiases for complex types:type MyConfigEntry = ConfigEntry[MyClient]
Typing philosophy
Type objects at boundaries as early as possible. Use TypedDict and TypeGuard to narrow types early and use throughout. Prefer the type system over runtime checks - tests should never verify things the type checker can identify.
See typing philosophy for detailed patterns.
Async programming
- All external I/O must be async
- Avoid
awaitin loops - useasyncio.gather()instead:# ❌ Bad for item in items: await process(item) # ✅ Good await asyncio.gather(*[process(item) for item in items]) - Never block the event loop:
- Use
asyncio.sleep()nottime.sleep() - Use executor for blocking I/O:
await hass.async_add_executor_job(fn, args)
- Use
- Use
@callbackdecorator for event loop safe functions
Error handling
- Fail loudly: Never log an error/warning and continue as if nothing happened. If something fails that should succeed, raise an exception. Silent failures hide bugs.
- Use HA-specific exceptions in setup flows instead of generic Python exceptions:
ConfigEntryNotReady- Setup cannot finish yet. HA will retry setup. HAEO setup never fails permanently:async_setup_entryturns any unexpected error intoConfigEntryNotReadywith a repair issue, so do not raiseConfigEntryError.UpdateFailed- Coordinator refresh failed. Used in_async_update_data.
# ❌ Bad - generic exception in async_setup_entry try: await client.fetch() except TimeoutError: raise TimeoutError("Setup timed out") from None # ✅ Good - HA-specific exception enables proper retry behavior from homeassistant.exceptions import ConfigEntryNotReady try: await client.fetch() except TimeoutError: raise ConfigEntryNotReady("Setup timed out") from None - Keep try blocks minimal - only wrap code that can throw:
# ✅ Good try: data = await client.get_data() except ClientError: _LOGGER.error("Failed to fetch data") return # Process data outside try block processed = data.value * 100 - Avoid bare
except Exception:except in:- Config flows (for robustness)
- Background tasks
- Chain exceptions with
from:try: data = await client.fetch() except ApiError as err: raise UpdateFailed("API error") from err
Logging
- No periods at end of messages
- No integration names (added automatically)
- No sensitive data (keys, tokens, passwords)
- Use lazy logging:
_LOGGER.debug("Processing data: %s", variable) - Debug level for non-user-facing messages
Code style
- Formatting: Ruff
- Linting: Ruff
- Type checking: Pyright
- American English for all code and comments
- Sentence case for messages
- Order conditions so a bare
return,continue, orbreakis not needed: guard the work with the condition, or filter the items before the loop. Use a bare keyword only when the restructured version would be clearly harder to read.
Lint suppressions
# noqa, # type: ignore, and # pyright: ignore are tools of last resort.
Before adding one, try to restructure the code so the lint rule is satisfied naturally.
Only suppress when there is genuinely no reasonable alternative.
Every # noqa comment must include an explicit reason explaining why the suppression is necessary and why the code cannot be restructured to avoid it.
The reason goes in parentheses after the rule code:
# ✅ Good - genuine need with reason
raise ValueError(msg) # noqa: TRY004 (ValueError is appropriate here, not TypeError)
# ❌ Bad - no reason
raise ValueError(msg) # noqa: TRY004
# ❌ Bad - could have been avoided by restructuring
from .foo import bar # noqa: PLC0415 (only needed here)
# ↑ If the import works at module level, just move it thereException for deferred imports (PLC0415): Ruff's isort (force-sort-within-sections) strips inline reasons from import lines.
For PLC0415, put the reason on the preceding comment line and keep the noqa bare.
The reason must explain a genuine constraint (circular import, conditional availability, etc.) — not just preference:
# ✅ Good - genuine circular import, reason on preceding line
# Avoid circular import with parent package
from .internals import _private # noqa: PLC0415
# ❌ Bad - no actual constraint, just move it to module level
# Only used in one function
from .internals import _private # noqa: PLC0415Never import a private (_name) symbol from another module and silence reportPrivateUsage, in tests as well as code.
Test through the public API, make the symbol public when it is genuinely part of the module's interface, or build an independent reference in the test.
Docstrings
- Required for all public functions and methods
- Short and concise file headers:
"""Battery element for energy network optimization.""" - Method docstrings describe what, not how:
async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool: """Set up HAEO from a config entry."""
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.

