aiskillstore/marketplace / skills/0xbigboss/python-best-practices
python-best-practices
VerifiedUse when reading or writing Python files (.py, pyproject.toml, requirements.txt).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.9 KB |
| skill-report.json | config | 25.8 KB |
skill-report.json
View on GitHub{
"schema_version": "2.0",
"meta": {
"generated_at": "2026-07-09T14:05:21.982Z",
"slug": "0xbigboss-python-best-practices",
"source_url": "https://github.com/0xBigBoss/claude-code/tree/main/.claude/skills/python-best-practices",
"source_ref": "main",
"model": "codex",
"analysis_version": "3.0.0",
"source_type": "community",
"content_hash": "358616cdf82975e13987f9bcfdaff5d07f39be060602e4c00f819f637c48e1a6",
"tree_hash": "3084c9bc3a5c67606f645ebbfe7884c983d5c88f81e6d28ceb342651b4121ad4",
"provenance": {
"model_requested": "gpt-5.5:high",
"model_effective": "codex:gpt-5.5:high",
"fallback_chain": [
{
"agent": "codex",
"model": "gpt-5.5",
"effort": "high",
"outcome": "success"
}
],
"analysis_version": "3.0.0"
}
},
"skill": {
"name": "python-best-practices",
"description": "Guides Python coding with type-first models, functional boundaries, structured errors, logging patterns, and optional type checker guidance.",
"summary": "Apply practical Python patterns for safer models, clearer errors, and maintainable typed code.",
"icon": "📦",
"version": "1.0.0",
"author": "0xBigBoss",
"license": "MIT",
"tags": [
"python",
"type-checking",
"error-handling",
"structured-logging",
"code-quality"
],
"supported_tools": [
"claude",
"codex",
"claude-code"
],
"risk_factors": [
"external_commands",
"network"
],
"category": "coding"
},
"security_audit": {
"risk_level": "safe",
"is_blocked": false,
"safe_to_publish": true,
"analysis_status": "ok",
"summary": "Static analysis mostly matched Markdown fences and inline code, which are false positives in this documentation-only skill. One optional bash example shows uvx ty check, which is legitimate type-checking guidance but still requires user confirmation before execution.",
"remediation": [
{
"issue": "The optional uvx example can run an external package runner.",
"suggestion": "Tell agents to ask before running uvx, and prefer project-pinned type checkers when available.",
"severity": "medium"
}
],
"risk_factor_evidence": [
{
"factor": "external_commands",
"evidence": [
{
"file": "SKILL.md",
"line_start": 15,
"line_end": 27
},
{
"file": "SKILL.md",
"line_start": 27,
"line_end": 30
},
{
"file": "SKILL.md",
"line_start": 30,
"line_end": 52
},
{
"file": "SKILL.md",
"line_start": 52,
"line_end": 55
},
{
"file": "SKILL.md",
"line_start": 55,
"line_end": 64
},
{
"file": "SKILL.md",
"line_start": 64,
"line_end": 67
},
{
"file": "SKILL.md",
"line_start": 67,
"line_end": 76
},
{
"file": "SKILL.md",
"line_start": 76,
"line_end": 80
},
{
"file": "SKILL.md",
"line_start": 80,
"line_end": 81
},
{
"file": "SKILL.md",
"line_start": 81,
"line_end": 86
},
{
"file": "SKILL.md",
"line_start": 86,
"line_end": 90
},
{
"file": "SKILL.md",
"line_start": 90,
"line_end": 91
},
{
"file": "SKILL.md",
"line_start": 91,
"line_end": 101
},
{
"file": "SKILL.md",
"line_start": 101,
"line_end": 107
},
{
"file": "SKILL.md",
"line_start": 107,
"line_end": 110
},
{
"file": "SKILL.md",
"line_start": 110,
"line_end": 112
},
{
"file": "SKILL.md",
"line_start": 112,
"line_end": 116
},
{
"file": "SKILL.md",
"line_start": 116,
"line_end": 119
},
{
"file": "SKILL.md",
"line_start": 119,
"line_end": 120
},
{
"file": "SKILL.md",
"line_start": 120,
"line_end": 121
}
]
},
{
"factor": "network",
"evidence": [
{
"file": "SKILL.md",
"line_start": 105,
"line_end": 105
}
]
}
],
"static_findings": [
{
"id": "external_commands:SKILL.md:15:ruby-shell-backtick-execution",
"category": "external_commands",
"severity": "medium",
"pattern": "Ruby/shell backtick execution",
"file": "SKILL.md",
"line_start": 15,
"line_end": 27,
"snippet": "```python"
},
{
"id": "external_commands:SKILL.md:27:ruby-shell-backtick-execution",
"category": "external_commands",
"severity": "medium",
"pattern": "Ruby/shell backtick execution",
"file": "SKILL.md",
"line_start": 27,
"line_end": 30,
"snippet": "```"
},
{
"id": "external_commands:SKILL.md:30:ruby-shell-backtick-execution",
"category": "external_commands",
"severity": "medium",
"pattern": "Ruby/shell backtick execution",
"file": "SKILL.md",
"line_start": 30,
"line_end": 52,
"snippet": "```python"
},
{
"id": "external_commands:SKILL.md:52:ruby-shell-backtick-execution",
"category": "external_commands",
"severity": "medium",
"pattern": "Ruby/shell backtick execution",
"file": "SKILL.md",
"line_start": 52,
"line_end": 55,
"snippet": "```"
},
{
"id": "external_commands:SKILL.md:55:ruby-shell-backtick-execution",
"category": "external_commands",
"severity": "medium",
"pattern": "Ruby/shell backtick execution",
"file": "SKILL.md",
"line_start": 55,
"line_end": 64,
"snippet": "```python"
},
{
"id": "external_commands:SKILL.md:64:ruby-shell-backtick-execution",
"category": "external_commands",
"severity": "medium",
"pattern": "Ruby/shell backtick execution",
"file": "SKILL.md",
"line_start": 64,
"line_end": 67,
"snippet": "```"
},
{
"id": "external_commands:SKILL.md:67:ruby-shell-backtick-execution",
"category": "external_commands",
"severity": "medium",
"pattern": "Ruby/shell backtick execution",
"file": "SKILL.md",
"line_start": 67,
"line_end": 76,
"snippet": "```python"
},
{
"id": "external_commands:SKILL.md:76:ruby-shell-backtick-execution",
"category": "external_commands",
"severity": "medium",
"pattern": "Ruby/shell backtick execution",
"file": "SKILL.md",
"line_start": 76,
"line_end": 80,
"snippet": "```"
},
{
"id": "external_commands:SKILL.md:80:ruby-shell-backtick-execution",
"category": "external_commands",
"severity": "medium",
"pattern": "Ruby/shell backtick execution",
"file": "SKILL.md",
"line_start": 80,
"line_end": 81,
"snippet": "Chain exceptions with `from err` to preserve the original traceback:"
},
{
"id": "external_commands:SKILL.md:81:ruby-shell-backtick-execution",
"category": "external_commands",
"severity": "medium",
"pattern": "Ruby/shell backtick execution",
"file": "SKILL.md",
"line_start": 81,
"line_end": 86,
"snippet": "```python"
},
{
"id": "external_commands:SKILL.md:86:ruby-shell-backtick-execution",
"category": "external_commands",
"severity": "medium",
"pattern": "Ruby/shell backtick execution",
"file": "SKILL.md",
"line_start": 86,
"line_end": 90,
"snippet": "```"
},
{
"id": "external_commands:SKILL.md:90:ruby-shell-backtick-execution",
"category": "external_commands",
"severity": "medium",
"pattern": "Ruby/shell backtick execution",
"file": "SKILL.md",
"line_start": 90,
"line_end": 91,
"snippet": "Use a module-level logger with `%s` formatting (deferred string interpolation):"
},
{
"id": "external_commands:SKILL.md:91:ruby-shell-backtick-execution",
"category": "external_commands",
"severity": "medium",
"pattern": "Ruby/shell backtick execution",
"file": "SKILL.md",
"line_start": 91,
"line_end": 101,
"snippet": "```python"
},
{
"id": "external_commands:SKILL.md:101:ruby-shell-backtick-execution",
"category": "external_commands",
"severity": "medium",
"pattern": "Ruby/shell backtick execution",
"file": "SKILL.md",
"line_start": 101,
"line_end": 107,
"snippet": "```"
},
{
"id": "external_commands:SKILL.md:107:ruby-shell-backtick-execution",
"category": "external_commands",
"severity": "medium",
"pattern": "Ruby/shell backtick execution",
"file": "SKILL.md",
"line_start": 107,
"line_end": 110,
"snippet": "```bash"
},
{
"id": "external_commands:SKILL.md:110:ruby-shell-backtick-execution",
"category": "external_commands",
"severity": "medium",
"pattern": "Ruby/shell backtick execution",
"file": "SKILL.md",
"line_start": 110,
"line_end": 112,
"snippet": "```"
},
{
"id": "external_commands:SKILL.md:112:ruby-shell-backtick-execution",
"category": "external_commands",
"severity": "medium",
"pattern": "Ruby/shell backtick execution",
"file": "SKILL.md",
"line_start": 112,
"line_end": 116,
"snippet": "```toml"
},
{
"id": "external_commands:SKILL.md:116:ruby-shell-backtick-execution",
"category": "external_commands",
"severity": "medium",
"pattern": "Ruby/shell backtick execution",
"file": "SKILL.md",
"line_start": 116,
"line_end": 119,
"snippet": "```"
},
{
"id": "external_commands:SKILL.md:119:ruby-shell-backtick-execution",
"category": "external_commands",
"severity": "medium",
"pattern": "Ruby/shell backtick execution",
"file": "SKILL.md",
"line_start": 119,
"line_end": 120,
"snippet": "- `ty` — fastest, good for CI and large codebases (early stage, rapidly evolving)"
},
{
"id": "external_commands:SKILL.md:120:ruby-shell-backtick-execution",
"category": "external_commands",
"severity": "medium",
"pattern": "Ruby/shell backtick execution",
"file": "SKILL.md",
"line_start": 120,
"line_end": 121,
"snippet": "- `pyright` — most complete type inference, VS Code integration"
},
{
"id": "network:SKILL.md:105:hardcoded-url",
"category": "network",
"severity": "low",
"pattern": "Hardcoded URL",
"file": "SKILL.md",
"line_start": 105,
"line_end": 105,
"snippet": "For fast type checking, consider [ty](https://docs.astral.sh/ty/) from Astral (creators of ruff and "
},
{
"id": "blocker:SKILL.md:12:system-reconnaissance",
"category": "blocker",
"severity": "low",
"pattern": "System reconnaissance",
"file": "SKILL.md",
"line_start": 12,
"line_end": 12,
"snippet": "Use Python's type system to prevent invalid states at type-check time."
},
{
"id": "blocker:SKILL.md:85:system-reconnaissance",
"category": "blocker",
"severity": "low",
"pattern": "System reconnaissance",
"file": "SKILL.md",
"line_start": 85,
"line_end": 85,
"snippet": "raise ValueError(f\"invalid JSON payload: {err}\") from err"
}
],
"finding_verdicts": [
{
"id": "external_commands:SKILL.md:15:ruby-shell-backtick-execution",
"verdict": "false_positive",
"confidence": 0.93,
"reason": "This is the opening fence for a Python dataclass example. It contains documentation, not Ruby backtick execution or a shell invocation."
},
{
"id": "external_commands:SKILL.md:27:ruby-shell-backtick-execution",
"verdict": "false_positive",
"confidence": 0.93,
"reason": "This is the closing Markdown fence for the dataclass example. It does not execute a command or ask an agent to run one."
},
{
"id": "external_commands:SKILL.md:30:ruby-shell-backtick-execution",
"verdict": "false_positive",
"confidence": 0.93,
"reason": "This opens a Python example for discriminated unions. The block is static documentation and has no command execution behavior."
},
{
"id": "external_commands:SKILL.md:52:ruby-shell-backtick-execution",
"verdict": "false_positive",
"confidence": 0.93,
"reason": "This is a closing Markdown fence after the union example. It is not executable shell or Ruby syntax in context."
},
{
"id": "external_commands:SKILL.md:55:ruby-shell-backtick-execution",
"verdict": "false_positive",
"confidence": 0.93,
"reason": "This opens a Python NewType example. It documents type hints and does not invoke external commands."
},
{
"id": "external_commands:SKILL.md:64:ruby-shell-backtick-execution",
"verdict": "false_positive",
"confidence": 0.93,
"reason": "This is the closing fence for the NewType example. No execution behavior is present on this line range."
},
{
"id": "external_commands:SKILL.md:67:ruby-shell-backtick-execution",
"verdict": "false_positive",
"confidence": 0.93,
"reason": "This opens a Python Protocol example. The content describes typing and includes no shell or Ruby execution."
},
{
"id": "external_commands:SKILL.md:76:ruby-shell-backtick-execution",
"verdict": "false_positive",
"confidence": 0.93,
"reason": "This is the closing Markdown fence for a Protocol example. It is a formatting marker, not an execution primitive."
},
{
"id": "external_commands:SKILL.md:80:ruby-shell-backtick-execution",
"verdict": "false_positive",
"confidence": 0.93,
"reason": "The backticks wrap inline prose about exception chaining. This is documentation text and not a command execution pattern."
},
{
"id": "external_commands:SKILL.md:81:ruby-shell-backtick-execution",
"verdict": "false_positive",
"confidence": 0.93,
"reason": "This opens a Python exception-handling example. The code shows local error handling and has no external command call."
},
{
"id": "external_commands:SKILL.md:86:ruby-shell-backtick-execution",
"verdict": "false_positive",
"confidence": 0.93,
"reason": "This closes the exception-handling code fence. It does not represent a runnable command or backtick execution."
},
{
"id": "external_commands:SKILL.md:90:ruby-shell-backtick-execution",
"verdict": "false_positive",
"confidence": 0.93,
"reason": "The inline backticks describe logging format syntax. This is explanatory text and not an executable command."
},
{
"id": "external_commands:SKILL.md:91:ruby-shell-backtick-execution",
"verdict": "false_positive",
"confidence": 0.93,
"reason": "This opens a Python logging example. The code only configures and uses a logger, with no process execution."
},
{
"id": "external_commands:SKILL.md:101:ruby-shell-backtick-execution",
"verdict": "false_positive",
"confidence": 0.93,
"reason": "This range covers a code fence close and surrounding documentation. It contains no command execution instruction."
},
{
"id": "external_commands:SKILL.md:107:ruby-shell-backtick-execution",
"verdict": "confirmed",
"confidence": 0.74,
"reason": "The fenced bash block shows uvx ty check commands. These are legitimate type-checking examples, but following them could execute an external package runner.",
"severity": "medium"
},
{
"id": "external_commands:SKILL.md:110:ruby-shell-backtick-execution",
"verdict": "false_positive",
"confidence": 0.93,
"reason": "This is a closing Markdown fence after the uvx examples. The marker itself does not introduce command execution."
},
{
"id": "external_commands:SKILL.md:112:ruby-shell-backtick-execution",
"verdict": "false_positive",
"confidence": 0.93,
"reason": "This opens a TOML configuration example. Static project configuration is not shell or Ruby execution."
},
{
"id": "external_commands:SKILL.md:116:ruby-shell-backtick-execution",
"verdict": "false_positive",
"confidence": 0.93,
"reason": "This closes the TOML example. It is Markdown syntax only and not an executable instruction."
},
{
"id": "external_commands:SKILL.md:119:ruby-shell-backtick-execution",
"verdict": "false_positive",
"confidence": 0.93,
"reason": "The inline backticks name ty in a comparison list. They do not instruct command execution or evaluate code."
},
{
"id": "external_commands:SKILL.md:120:ruby-shell-backtick-execution",
"verdict": "false_positive",
"confidence": 0.93,
"reason": "The inline backticks name pyright in a comparison list. This is plain documentation, not execution."
},
{
"id": "network:SKILL.md:105:hardcoded-url",
"verdict": "false_positive",
"confidence": 0.93,
"reason": "The URL points to official ty documentation in a Markdown link. There is no automatic network request or data transfer behavior."
},
{
"id": "blocker:SKILL.md:12:system-reconnaissance",
"verdict": "false_positive",
"confidence": 0.93,
"reason": "The phrase type system refers to Python typing concepts. It is not system reconnaissance or host inspection."
},
{
"id": "blocker:SKILL.md:85:system-reconnaissance",
"verdict": "false_positive",
"confidence": 0.93,
"reason": "This line raises a clearer JSON parsing exception. It does not inspect system state or collect environment information."
}
],
"semantic_findings": [],
"critical_findings": [],
"high_findings": [],
"medium_findings": [
{
"title": "Ruby/shell backtick execution",
"description": "```bash",
"locations": [
{
"file": "SKILL.md",
"line_start": 107,
"line_end": 110
}
],
"review_kind": "capability",
"source_category": "external_commands",
"source_severity": "medium",
"confidence": 0.74,
"confidence_reasoning": "The fenced bash block shows uvx ty check commands. These are legitimate type-checking examples, but following them could execute an external package runner."
}
],
"low_findings": [],
"dangerous_patterns": [],
"files_scanned": 1,
"total_lines": 122,
"audit_model": "codex",
"audited_at": "2026-07-09T14:05:21.982Z",
"agent_auto_install_policy": "allowed",
"manual_install_policy": "allowed"
},
"content": {
"user_title": "Improve Python Code Quality",
"value_statement": "Python projects often drift into weak typing, mutable models, and unclear error handling. This skill gives Claude, Codex, and Claude Code focused rules for safer, clearer Python changes.",
"seo_keywords": [
"Claude",
"Codex",
"Claude Code",
"Python best practices",
"Python type checking",
"dataclasses",
"Protocol typing",
"structured logging",
"exception chaining",
"Python code quality"
],
"actual_capabilities": [
"Recommends frozen dataclasses for immutable domain models.",
"Shows discriminated union patterns with Literal values.",
"Uses NewType for distinct domain identifiers.",
"Applies Protocol classes for structural typing.",
"Encourages exception chaining with preserved tracebacks.",
"Promotes module loggers and deferred log formatting."
],
"limitations": [
"It is guidance only and does not run analysis by itself.",
"It does not cover frameworks, packaging, or deployment workflows.",
"The type checker section references a rapidly evolving tool.",
"Examples are short and may need adaptation for large systems."
],
"use_cases": [
{
"title": "Review Python Domain Models",
"description": "Check whether models use immutable data classes, precise identifiers, and type-safe state shapes.",
"target_user": "Backend engineers"
},
{
"title": "Improve Error Handling",
"description": "Refactor parsing and validation paths so exceptions preserve original context and report clear messages.",
"target_user": "Application developers"
},
{
"title": "Standardize Logging Style",
"description": "Align new Python modules with module-level loggers and deferred formatting for cleaner diagnostics.",
"target_user": "Code reviewers"
}
],
"prompt_templates": [
{
"title": "Review One Python File",
"scenario": "Beginner review of a small file.",
"prompt": "Review this Python file using the python-best-practices skill. Focus on typing, errors, and logging. Suggest only practical changes."
},
{
"title": "Refactor Domain Types",
"scenario": "Intermediate model cleanup.",
"prompt": "Refactor these Python domain models using immutable data classes, NewType identifiers, and explicit state variants where helpful."
},
{
"title": "Harden Error Paths",
"scenario": "Advanced exception review.",
"prompt": "Audit these parsing and validation functions for exception chaining, clear failure messages, and type-safe return states."
},
{
"title": "Design a Typed Module",
"scenario": "Advanced greenfield design.",
"prompt": "Design a Python module API that makes invalid states unrepresentable and uses Protocol boundaries for external dependencies."
}
],
"output_examples": [
{
"input": "A mutable user model uses plain strings for every identifier.",
"output": [
"Recommend an immutable data class for the user record.",
"Introduce distinct identifier types for user and order values.",
"Explain the type safety benefit in plain language."
]
},
{
"input": "A parser catches a decoding error and raises a generic value error.",
"output": [
"Keep the original exception as the cause of the new error.",
"Preserve a clear message for callers and logs.",
"Check whether the function should return an explicit success or failure state."
]
},
{
"input": "A module prints debug messages while building application objects.",
"output": [
"Replace print calls with a module-level logger.",
"Use deferred formatting for values included in log messages.",
"Keep log messages specific enough for troubleshooting."
]
}
],
"best_practices": [
"Prefer type-level distinctions for values that have different business meanings.",
"Preserve original exceptions when raising clearer application errors.",
"Use structured logger calls instead of direct output in application code."
],
"anti_patterns": [
"Do not model every domain identifier as an interchangeable string.",
"Do not replace detailed exceptions with generic errors that lose context.",
"Do not use eager string interpolation in debug log messages."
],
"faq": [
{
"question": "Does this skill execute Python tools automatically?",
"answer": "No. It provides guidance and examples. Any command execution depends on the agent and user approval."
},
{
"question": "Which Python files does it target?",
"answer": "It targets Python source files and project configuration related to typing and code quality."
},
{
"question": "Can it replace a type checker?",
"answer": "No. It helps write type-friendly code, but real projects still need automated type checking."
},
{
"question": "Does it support framework-specific patterns?",
"answer": "No. It focuses on language-level Python patterns, not Django, FastAPI, or data science frameworks."
},
{
"question": "Is the ty recommendation required?",
"answer": "No. The skill presents ty as an optional fast type checker, alongside pyright and mypy."
},
{
"question": "Can Claude Code and Codex both use it?",
"answer": "Yes. The report marks support for Claude, Codex, and Claude Code."
}
]
},
"file_structure": [
{
"name": "SKILL.md",
"type": "file",
"path": "SKILL.md",
"lines": 122
}
]
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |