python-guidelines — скилл для Claude Code: что делает и как установить
Скилл python-guidelines задаёт правила написания и ревью Python-кода: интеграция в существующий код, запрет на лишние абстракции и единый формат докстрингов.
Apache-2.0 ★ 1 216 обновлён 2026-10-24
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install python-skills@claude-settingsЧто делает python-guidelines
Скилл подключается, когда агент пишет, ревьюит или рефакторит Python-код. Он требует встраивать новый код в существующие паттерны именования и сигнатур, а не дописывать сбоку: тривиальные обёртки на две строки инлайнятся, однострочные переменные подставляются прямо в место использования, try/except используется только при критической необходимости.
Отдельный блок посвящён YAGNI: абстрактные классы под одну реализацию, конфиги «на будущее» и обёртки вокруг одной функции запрещены — рефакторинг откладывается до третьего реального случая использования. Для окружения скилл требует uv вместо pip и проверку гипотез о поведении кода через python -c "..." перед тем, как агент предложит план.
Докстринги оформляются в стиле Google: summary в повелительном наклонении, типы вроде int | str, секция Returns всегда в круглых скобках. Внутри скилла лежат четыре справочных файла — про идиоматичные паттерны, Zen of Python, Google style guide и советы из «Effective Python», и агент должен читать нужный файл до написания кода, а не после.
Какие задачи решает
- встроить новый код в стиль существующего проекта, а не дописать рядом
- убрать премature-абстракции и лишние обёртки из кода
- привести докстринги к единому Google-style формату
- проверить гипотезу о поведении функции или пакета через
python -c - найти и прочитать исходник сторонней библиотеки перед правкой
Примеры запросов агенту
- Отрефактори этот модуль по правилам python-guidelines
- Проверь, нет ли лишних абстракций в этом Python-файле
- Оформи докстринги в этой функции по Google-style из python-guidelines
Как установить python-guidelines
1Через маркетплейс плагинов
/plugin marketplace add fcakyon/claude-codex-settings/plugin install python-skills@claude-settingsКоманда ставит плагин python-skills целиком, со всеми его скиллами
2Через Skills CLI (Vercel)
npx skills add fcakyon/claude-codex-settings --skill python-guidelines -a claude-code3Вручную: положить файлы
~/.claude/skills/python-guidelines/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/python-guidelines/
1Через Skills CLI (Vercel)
npx skills add fcakyon/claude-codex-settings --skill python-guidelines -a codex2Вручную: положить файлы
.agents/skills/python-guidelines/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add fcakyon/claude-codex-settings --skill python-guidelines -a cursor2Вручную: положить файлы
.cursor/skills/python-guidelines/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install fcakyon/claude-codex-settings plugins/python-skills/skills/python-guidelines2Вручную: положить файлы
.github/skills/python-guidelines/SKILL.md1Через Skills CLI (Vercel)
npx skills add fcakyon/claude-codex-settings --skill python-guidelines -a gemini-cli2Командой платформы
gemini skills install https://github.com/fcakyon/claude-codex-settings --path plugins/python-skills/skills/python-guidelinesВручную: положить файлы
.devin/skills/python-guidelines/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Claude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о python-guidelines
Как установить python-guidelines в Claude Code?
Выполните /plugin marketplace add fcakyon/claude-codex-settings, затем /plugin install python-skills@claude-settings.
Что делает скилл python-guidelines?
Он задаёт правила написания, ревью и рефакторинга Python-кода: интеграцию в существующие паттерны, отказ от лишних абстракций и единый формат докстрингов. Для проверки гипотез о коде скилл требует запускать python -c "..." до того, как агент предложит план.
Какой пакетный менеджер требует python-guidelines?
Скилл предписывает использовать uv вместо pip и активировать окружение через source .venv/bin/activate или uv run python -c "...".
Исходный текст
SKILL.md · Apache-2.0
---
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:
```python
# 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:
```python
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:
- [`references/idiomatic-patterns.md`](references/idiomatic-patterns.md) -- read when writing loops, comprehensions, unpacking, context managers, or dataclasses. 18 idioms with before/after code
- [`references/zen-of-python.md`](references/zen-of-python.md) -- read when choosing between two designs or judging whether an abstraction earns its place. PEP 20 with annotations
- [`references/google-style-guide.md`](references/google-style-guide.md) -- read when deciding on exceptions, mutable defaults, import style, naming, or comments
- [`references/effective-python-tips.md`](references/effective-python-tips.md) -- read when reviewing or refactoring existing code. Key tips from "Effective Python" (Brett Slatkin)
© fcakyon · Apache-2.0 · fcakyon/claude-codex-settings