SkillAgentSearch skills...

python-guidelines

This skill should be used when writing, reviewing, or refactoring Python code. Covers code integration, idiomatic patterns, docstring formatting, anti-abstraction rules, and software engineering basics.

Install / Use

npx skills add fcakyon/claude-codex-settings --skill python-guidelines

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

87/100

Supported Platforms

Universal

Our assessment of python-guidelines

python-guidelines scores 87/100 on our quality scale, 653rd of 1,155 Content & Media skills we index.

Its SKILL.md is 4.8 KB long, well organised into 8 sections with 2 code examples: a solid amount of guidance for an agent.

With 1,153 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
26/30
Structure
18/20
Description
15/15
Adoption
13/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so python-guidelines is actively maintained.
  • Our last check on 2026-10-11 found the source still online.
  • It is released under the Apache-2.0 license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-10-04. Automated pattern scan on 2026-10-04. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

python-guidelines compared with similar skills

All 4 of these similar skills score higher than python-guidelines; compare them before choosing.

SkillScoreStarsUpdatedFormat
python-guidelines (this skill)by fcakyon871.2k53d agoSKILL.md
Agent-Reachby Panniantong100112.3k8d agoCLAUDE.md
headroomby headroomlabs-ai10079.8ktodayCLAUDE.md
Scraplingby D4Vinci100103.6k2d agoMCP Server
crawl4aiby unclecode10087.4k3d agoMCP Server

Frequently asked questions

How do I install python-guidelines?
Run npx skills add fcakyon/claude-codex-settings --skill python-guidelines. The install tabs above show the steps for each supported agent.
Which AI agents does python-guidelines work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is python-guidelines safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is Apache-2.0-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is python-guidelines still maintained?
The repository was last updated about 2 months ago, so python-guidelines is actively maintained.

name: python-guidelines description: This skill should be used when writing, reviewing, or refactoring Python code. Covers code integration, idiomatic patterns, docstring formatting, anti-abstraction rules, and software engineering basics.

Python Guidelines

Integrate into existing code. Don't append to it.

Simple is better than complex. Flat is better than nested. Errors should never pass silently. Unless explicitly silenced. If the implementation is hard to explain, it's a bad idea.

-- The Zen of Python (PEP 20)

Code Philosophy

  • Match existing naming, importing, and signature patterns. Use existing utilities and data structures.
  • Functions have a single purpose. Don't hardcode behavior that makes them less general.
  • No trivial wrappers for 2 lines or less. Inline it.
  • Inline single-use variables at the usage site.
  • No try/except unless critical. Let errors surface.
  • No duplicate code.
  • Functions handle their own input validation. No if-else checks in main.
  • Use pathlib, not os.path.
  • Consider API and time costs for MongoDB/Gemini/OpenAI/Claude/Voyage.

Don't do this:

# Generate comment report only if requested
if include_comments:
    comment_report = generate_comments_report(start_date, end_date, team, verbose)
else:
    comment_report = ""
    print("   Skipping comment analysis (disabled)")

Do this:

comment_report = generate_comments_report(start_date, end_date, team, verbose) if include_comments else ""

Ask yourself: "Am I adding code, or integrating into what exists?"

Simplicity Over Abstraction

YAGNI: You Aren't Gonna Need It.

Don't build for hypothetical future requirements. Add complexity only when the current task demands it.

Avoid:

  • Abstract base classes for a single implementation
  • Configuration options nobody asked for
  • Error handling for impossible scenarios
  • Wrapper classes around a single function
  • Dependency injection when direct calls work
  • Generic type parameters for one concrete type

Three similar lines of code is better than a premature abstraction. Refactor when the third real use case appears, not before.

But simplicity does not mean chaos. Always maintain:

  • Clear function names that describe what they do
  • Logical grouping of related code into modules
  • Consistent naming conventions across the project
  • Clean separation between I/O and logic
  • Explicit parameters over global state or side effects

Ask yourself: "Is this abstraction solving a problem I have right now, or one I'm imagining?"

Environment

  • Package manager: uv (NOT pip)
  • Virtual env: source .venv/bin/activate or uv run python -c "..."
  • 3rd party packages: Find source with python -c "import pkg; print(pkg.__file__)", then Read.

Testing Discipline

Never assume anything. Run python -c "..." to verify hypotheses about code behavior, package functions, or data structures before suggesting a plan or exiting plan mode.

Ask yourself: "Did I verify this with python -c before building on it?"

Google-Style Docstrings

  • Summary: Imperative mood ("Calculate", not "Calculates")
  • Args: All parameters with types and descriptions. No default values. Indent 4 spaces.
  • Types: int | str unions, uppercase shapes (N, M), lowercase builtins list/dict/tuple, capitalize Any/Path
  • Optional: name (type, optional): Description
  • Returns: Always (type) in parentheses. Never tuple types. Separate named values for multiple returns.
  • Sections: Examples (>>>), Notes, References (plaintext only). Section titles at 0 indent.
  • Omit: "Returns:" if nothing returned, "Args:" if no args, "Raises:" unless critical
  • Classes: Attributes section only, omit Methods/Args. Don't convert single-line to multiline.
  • __init__: Args only. No Examples/Notes/Methods/References.
  • Tests: Single-line docstrings only.
  • Erase default values from existing arg descriptions. Optionally include minimal Examples.

Ask yourself: "Would a new developer understand this function from the docstring alone?"

Reference Files

Read the matching file before you write the code, not after:

Related Skills

View on GitHub
GitHub Stars1.2k
CategoryContent
Updated1mo ago
Forks110

Languages

Python

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions