[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M786QD59A2R2JK1NJTK7MADP":3,"skill-same:01M786QD59A2R2JK1NJTK7MADP":74},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":33,"commitSha":34,"skillDirectory":5,"forksCount":35,"repositoryHtmlUrl":36,"repositoryHomepageUrl":6,"ownerHtmlUrl":37,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":38,"install":39,"resources":51},"01M786QD59A2R2JK1NJTK7MADP","python-lang",null,"MANDATORY skill for Python code. Use when writing, editing, refactoring, or reviewing Python files, modules, packages, classes, functions, type annotations, imports, exceptions, comprehensions, decorators, or docstrings. Enforces Google Python Style Guide and a mandatory, unconditional Ruff format+check pipeline scoped strictly to the agent's own changes.","kalaverin\u002Fskills","kalaverin","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6841312?v=4","01M786EMXK5R6A138KWFAS33T1","Alex Kalaverin","01M786EMYBQEDP3548REZHRX2Q",1,"BSD-3-Clause","https:\u002F\u002Fgithub.com\u002Fkalaverin\u002Fskills\u002Fblob\u002Fmain\u002Fpython-lang\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: python-lang\ndescription: MANDATORY skill for Python code. Use when writing, editing, refactoring, or reviewing Python files, modules, packages, classes, functions, type annotations, imports, exceptions, comprehensions, decorators, or docstrings. Enforces Google Python Style Guide and a mandatory, unconditional Ruff format+check pipeline scoped strictly to the agent's own changes.\ntriggers:\n  any:\n    files: \"fd -e py -e pyi --max-results 1 | wc -l | grep -q 1\"\n    request: \"python, питон\"\nruntime: true\nrequires:\n  - frontmatter-protocol\n  - read-for-comments\nversion: 0.1.0\n---\n\n# SKILL: Strict Python Engineering & Compliance\n\nYou are an expert Python Engineer and a strict Code Reviewer. **This document is a binding rule set, not a recommendation.**\nEvery directive in this guide MUST be followed unless it explicitly uses **SHOULD** or **MAY**. The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"NOT RECOMMENDED\", \"MAY\", and \"OPTIONAL\" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when they appear in all capitals or in bold markup.\n\n## 1. Compliance and Local Style\n\n* **Default Rule:** Unless a section, paragraph, or sentence explicitly uses **SHOULD** or **MAY**, every statement is to be treated as **MUST**. If a coding situation is covered by this guide, you MUST follow the guide. You MUST NOT apply external style preferences or general Python heuristics in place of the rules documented here.\n* **Consistency:** BE CONSISTENT. If you are editing code, ALWAYS look at the code around you and you MUST match its style. Local style is VERY IMPORTANT. If code you add looks drastically different from the existing code, it throws readers out of their rhythm. Consistency applies more heavily locally and on choices unspecified by the global style.\n* **Deviation Justification:** If you deviate from any MUST directive, you MUST explicitly justify the deviation in your output.\n* **Skill Boundary:** This skill covers Python language and style rules. For API resource design, HTTP\u002FgRPC routes, and proto structure, consult the `api-design` skill.\n* **RFC Verbs:** For precise semantics of requirement-level verbs, consult the `read-for-comments` skill.\n\n***\n\n## 2. Mandatory Lookups (Lazy-Load Protocol)\n\n**This routing is mandatory.** When the task touches Python language or style rules, you MUST route through the corpus frontmatter before reading any body. Do not guess, do not rely on training data, and do not skip routing because the topic seems familiar. You MUST NOT read the reference files in their entirety.\n\n**Corpus:**\n\n- `references\u002F01_language_rules.md` — Google language rules; 20 routable sections, anchors `py-lr-*`.\n- `references\u002F02_style_rules.md` — Google style rules; 53 routable sections including the subsection-level chapters 2.8 \u002F 2.10 \u002F 2.16 \u002F 2.19, anchors `py-st-*`.\n- `references\u002F03_personal_rules.md` — project-specific rules that EXTEND and OVERRIDE the Google corpora on conflict, anchors `py-pr-*`. Its frontmatter is small: shortlist it on EVERY funnel pass so overrides are never missed.\n\n**Toolchain precedence (HARD):** the corpus reproduces upstream Google text that references `pylint` and `pytype`. Those references are historical context only. The governing local toolchain is Ruff for lint\u002Fformat (§3, mandatory) and mypy for type checking (`03_personal_rules.md`). Where a corpus section and this skill's §3 conflict, §3 wins; say so per §1 (Deviation Justification).\n\n**Skill addendum (lazyload):** `prompts\u002FREFERENCE_STANDARD_ADDENDUM.md` declares the two-tier anchor prefixes (`py-lr-`, `py-st-`, `py-pr-`), the tight `marker_style`, the Google-canon numbered-headings exemption, and the pseudo-heading legalization. Corpus frontmatter schema and card semantics defer to `frontmatter-protocol\u002Freferences\u002Flazyload.md`.\n\n**Routing Funnel (per `frontmatter-protocol` `[ref: #lazy-load-routing]`):**\n1. Run the subject map (Command 1) over `references\u002F` and shortlist candidate files semantically — the request plus inferred session work; shortlist generously.\n2. Read the full frontmatter of shortlisted files — `03_personal_rules.md` is always shortlisted — and match every card's `what` \u002F `use_when` \u002F `avoid_when` semantically (OR semantics); mark each matching card's `anchor`.\n3. Deduplicate anchors, then extract each selected section with the canonical bounded extraction — never a blind `rg -A N` window.\n4. Apply the extracted rules strictly.\n\n***\n\n## 3. Mandatory Lint & Format Pipeline (Unconditional Gate)\n\n**MANDATORY — ALWAYS, WITHOUT REMINDERS:** For EVERY Python file the agent writes, creates, or edits, the agent MUST run this pipeline before declaring the task complete. This gate is unconditional: it applies in addition to — and independently of — any project-level linting, formatter configuration, pre-commit hooks, or CI checks present in the target project. The agent MUST NOT skip it because \"the project has its own linting\", MUST NOT wait for the user to ask, and MUST NOT consider the task done until both stages pass on the agent's own changes.\n\nThe pipeline is Ruff-only (`black`, `flake8`, and `isort` are forbidden per the `mandatory-tools` skill) and has two mandatory stages, executed in this exact order:\n\n1. **Format** — `ruff format` (black-compatible automatic formatting).\n2. **Lint** — `ruff check --fix` (full-rule diagnostics WITH automatic in-place fixes; fixes scoped to the agent's own edits).\n\n**`--fix` is a mandatory part of the pipeline (HARD):** the lint stage's FIRST invocation MUST carry `--fix`, letting Ruff rewrite auto-fixable violations in place. The agent MUST NOT hand-edit what `ruff check --fix` repairs mechanically — manual fixing of auto-fixable violations wastes tokens and energy and is a pipeline violation. Manual edits are reserved for diagnostics that `--fix` cannot repair.\n\n**The `[*]` reminder rule (HARD):** the output line `[*] fixable with the \\`--fix\\` option.` means the previous run forgot `--fix`. On seeing it the agent MUST: (1) immediately recall that the first pass ALWAYS runs with `--fix`, and (2) immediately re-run the same command with `--fix` — before reading or hand-fixing any diagnostic. Treat every occurrence as a self-check failure of this pipeline.\n\n### Hard Constraint: Foreign Code Isolation\n* **ONLY** format and fix violations in code you explicitly wrote or modified.\n* **NEVER** change unmodified (\"foreign\") code to satisfy the formatter or linter.\n* If a violation exists in unmodified code, ignore it completely.\n* If the linter suggests moving or refactoring that would affect unmodified code, skip the suggestion.\n* Run every pipeline command with an explicit file list (`\u003Cchanged_files>`) — NEVER against the whole project, a whole directory, or files you did not touch.\n\n### Restoring Foreign Code After Formatting (MANDATORY)\nAutomatic formatters rewrite whole lines and may reformat code the agent never intended to touch. Foreign code MUST be returned to its exact prior state:\n\n1. **Baseline first.** Before running `ruff format`, make sure a restorable baseline exists for every target file (a git-tracked file with a committed or staged state, or an explicit backup copy). If `git diff \u003Cfile>` cannot serve as the baseline for a target file, create a backup copy of it BEFORE formatting.\n2. **Inspect every hunk.** After formatting, run `git diff \u003Cfile>` (or diff against the backup) and review each hunk individually.\n3. **Revert foreign hunks.** Any hunk that rewrites lines the agent did NOT author or intend to modify MUST be reverted (targeted `git checkout -p`, interactive hunk discard, or manual re-application) so foreign code becomes byte-identical to its baseline. NEVER blanket-revert: your own changes MUST survive.\n4. **Re-verify.** Re-run `ruff format --check` and `ruff check` on the file. If reverting a foreign hunk makes your own code fail the pipeline, re-apply formatting to your lines manually until both stages pass.\n5. **Justify unavoidable bleed.** If a formatter-mandated change physically cannot be limited to your own lines (for example, the formatter rewraps a construct that spans your edit), you MUST explicitly justify the deviation in your output per §1 (Deviation Justification).\n6. **Final scope check.** The delivered diff MUST contain formatting and lint changes ONLY within code the agent wrote or modified.\n\n### Step 3.1: Discover Target Python Version\nDetermine the project's target Python version before linting by executing:\n```bash\nuv run python -c \"import sys; print(f'py{sys.version_info.major}{sys.version_info.minor}')\"\n```\n*Use this exact value for `\u003CPYVER>` in the subsequent steps.*\n\n### Step 3.2: Format Own Changes (Black-Compatible)\nRun the formatter targeting **ONLY the files you created or modified**, then immediately perform the **Restoring Foreign Code After Formatting** procedure above:\n```bash\nuvx ruff format \u003Cchanged_files>\n```\n`\u003Cchanged_files>` is the explicit list of files the agent wrote or edited — nothing else. This stage replaces `black`: `ruff format` implements black-compatible formatting, and invoking `black` itself is forbidden.\n\n### Step 3.3: Fix and Read Linter Suggestions\nRun the following command targeting **ONLY the files you modified** — the `--fix` flag is MANDATORY on this first lint pass (see the HARD rules above); Ruff rewrites fixable violations in place:\n```bash\nuvx ruff check --fix --select ALL --ignore D,CPY,DOC,EM101,ERA001,FBT001,FBT002,FIX001,FIX002,TD001,TD002,TD003,TD004,TD005,TRY003 --target-version \u003CPYVER> --output-format concise \u003Cchanged_files>\n```\nRead every REMAINING suggestion carefully (these are the ones `--fix` could not repair). Apply manual fixes ONLY to the code you altered.\n\n### Step 3.4: Preview Remaining Fixes\nAfter applying fixes, confirm no auto-fixable violations remain — the emitted diff MUST be empty (any non-empty hunk is a fix you still owe or a foreign line you MUST NOT apply):\n```bash\nuvx ruff check --select ALL --ignore D,CPY,DOC,EM101,ERA001,FBT001,FBT002,FIX001,FIX002,TD001,TD002,TD003,TD004,TD005,TRY003 --target-version \u003CPYVER> --diff \u003Cchanged_files>\n```\nThis previews would-be fixes only; final git-scope verification is §4 step 6.\n\n### Step 3.5: Rule Lookup\nIf you are uncertain about any rule code generated by the linter, use:\n```bash\nuvx ruff rule \u003CRULE_CODE>\n```\n*(Example: `uvx ruff rule E501`)*\n\n### Pipeline Failure Handling (HARD)\nIf any pipeline command cannot run or errors out — `uv`\u002F`uvx`\u002F`ruff` missing, the target project is not uv-managed and `uv run` fails, Ruff crashes on a syntax error mid-edit — the agent MUST STOP, report the exact failure and its output to the user, and ask how to proceed. The gate is unconditional, but it is NEVER satisfied by silently skipping it or by substituting another linter (`black`, `flake8`, `isort` stay forbidden).\n\n***\n\n## 4. Master Execution Workflow\n1. **Analyze Task:** Determine the specific Python operations required.\n2. **Component Reuse Check:** Apply the §5 Component Reuse Rule before writing any code.\n3. **Route:** Run the §2 routing funnel over the `references\u002F` corpus (subject map → frontmatter cards → bounded extraction of the selected `py-*` sections).\n4. **Code Generation:** Write the code strictly adhering to the extracted rules, the reuse manifests, AND local file consistency.\n5. **Lint & Format:** Execute the full Mandatory Lint & Format Pipeline (§3), including foreign-code restoration, on every file the agent wrote or edited — unconditionally, without reminders, and regardless of any project-level linting.\n6. **Final Verification:** Confirm via `git diff` that no unmodified (foreign) code was altered before concluding the task; any formatter bleed into foreign lines must already be reverted or explicitly justified.\n\n***\n\n## 5. Component Reuse Rule\n\nBefore implementing any new Python module, class, or function, the agent MUST check whether the project root contains a `.sdk\u002F` directory.\n\n### 5.1 Discovery\nIf `.sdk\u002F` exists, discover all reuse manifests with: `fd -L -t f EXPORT.md .sdk\u002F`\n\nRead every returned file before writing code.\n\n### 5.2 Applying Manifests\nEach `EXPORT.md` describes reusable components and the criteria for copying them whole.\nApply those criteria strictly.\nAfter copying a module, replace the source package prefix with the target project's package prefix and run the Mandatory Lint & Format Pipeline (§3) only on the changed files.\n\n***\n\n## 6. Constants, Enums, Magic Values, and Data Carriers\n\n[ref: #py-constants-enums]\n\nThis section is mandatory. It applies to every Python file the agent writes, edits, or reviews.\n\n### 6.1 No magic values\n\n- A \"magic value\" is any numeric or string literal that carries semantic meaning outside the immediate syntax (e.g., `200`, `404`, `\"pending\"`, `0.95`, `86400`, `1 \u003C\u003C 41`).\n- Magic values MUST NOT appear inline in expressions, comparisons, function arguments, or return values.\n- The only literals allowed inline are:\n  - `0`, `1`, `-1` when used as pure arithmetic\u002Findexing identities.\n  - `True`, `False`, `None`.\n  - Mathematical identity values such as `base=10` or `radix=10`, documented in the same line.\n\n### 6.2 Use enums for categorical values\n\n- Categorical string values MUST be represented as `StrEnum` with `auto()`:\n  ```python\n  class Role(StrEnum):\n      ADMIN = auto()\n      USER = auto()\n  ```\n- Categorical numeric values MUST be represented as `Enum`:\n  ```python\n  class Priority(Enum):\n      LOW = 1\n      HIGH = 2\n  ```\n- Bit flags and masks MUST be represented as `IntFlag`:\n  ```python\n  class Permission(IntFlag):\n      READ = auto()\n      WRITE = auto()\n  ```\n- Prefer `auto()` for every member whose concrete value is not semantically significant. When only some members need custom values, assign those explicitly and keep `auto()` for the rest. Do not hand-write every value just because one member requires a custom value:\n  ```python\n  class ReconTarget(StrEnum):\n      PROGRAMS_INDEX = \"\u002Fprograms\"\n      AUTHOR_INDEX = \"\u002Fauthor\"\n      ARCHIVE_INDEX = \"\u002Farchive\"\n      NEWS_SECTION = auto()\n      OPINIONS_SECTION = auto()\n  ```\n\n### 6.3 Sentinel values\n\n- Do not use magic strings or numbers as sentinels (e.g., `result = -1`, `name = \"N\u002FA\"`, `value = 999`).\n- Use a dedicated enum member or a singleton sentinel object:\n  ```python\n  class Result(Enum):\n      FOUND = auto()\n      NOT_FOUND = auto()\n  ```\n\n### 6.4 Module-level constants\n\n- Any semantic value that is not naturally an enum MUST be defined as a module-level `ALL_CAPS` constant.\n- Examples: `TIMEOUT_SECONDS = 10.0`, `REFRESH_BUFFER_RATIO = 0.95`, `MAX_RETRIES = 3`.\n- Constants MUST be placed near the top of the module, after imports.\n- Whenever several constants form a logical or semantic group — such as URL path prefixes, section identifiers, feature flags, or configuration keys — they SHOULD be grouped into a single enum instead of being declared as separate `ALL_CAPS` constants. Prefer `StrEnum` for string groups, `Enum` for numeric groups, and `IntFlag` for flags. This makes the grouping explicit, gives it a name, and prevents accidental mixing with unrelated constants.\n\n### 6.5 Function-boundary constants\n\n- `Literal[...]` is allowed ONLY at boundaries where the value comes from outside the application and cannot yet be an enum (e.g., raw external API input, CLI flags).\n- Inside the application, categorical strings and numbers MUST be `Enum`\u002F`StrEnum` members, not `Literal`.\n- If the value can be modeled as a dataclass or Pydantic model, use that instead of `Literal`.\n\n### 6.6 HTTP status codes\n\n- HTTP status codes MUST NOT be written as bare integers.\n- If `starlette` is available, use `from starlette import status` and `status.HTTP_200_OK`.\n- Otherwise use `http.HTTPStatus.OK` from the standard library.\n- Never use `200`, `201`, `400`, `404`, `500`, etc.\n\n### 6.7 Data carriers\n\n- Functions in application code MUST NOT accept or return plain `dict` as their public contract.\n- Raw `dict` is allowed only as the immediate input to a parser\u002Fvalidator; it MUST be wrapped in a model or dataclass before crossing any application function boundary.\n- Inside the application, use frozen `dataclass` instances (`@dataclass(frozen=True)`).\n- At application boundaries (HTTP, files, env, external APIs, CLI input), use Pydantic models. If Pydantic is unavailable, use a dataclass with explicit validation.\n- `argparse.Namespace` and similar CLI parsers must be mapped to a dataclass or Pydantic model before use.\n- `TypedDict` is allowed ONLY as an exception, with the user's explicit approval, and only for dict-shaped data that cannot be a dataclass\u002FPydantic model.\n- `NamedTuple`\u002F`namedtuple` is allowed for performance-oriented intermediate representations when the data has already been validated by Pydantic models or sourced from dataclasses. It MUST NOT be used as the primary boundary carrier.\n\n### 6.8 No `**` unpacking\n\n- The `**` operator MUST NOT be used to unpack dictionaries into function arguments.\n- Every argument MUST be passed explicitly by name or position.\n- Bad: `func(**kwargs)`, `obj.method(**config_dict)`.\n- Good: `func(name=user.name, role=user.role)`.\n\n### 6.9 Examples\n\nBad:\n```python\nif response.status_code == 200:\n    ...\nwait(0.95)\n```\n\nGood:\n```python\nfrom starlette import status\nif response.status_code == status.HTTP_200_OK:\n    ...\nwait(REFRESH_BUFFER_RATIO)\n```\n\nBad:\n```python\ndef create_user(data: dict) -> dict:\n    ...\n```\n\nGood:\n```python\n@dataclass(frozen=True)\nclass UserCreate: ...\n\n@dataclass(frozen=True)\nclass User: ...\n\ndef create_user(data: UserCreate) -> User:\n    ...\n```\n\n### 6.10 Enforcement\n\n- Ruff rule `PLR2004` catches many magic-value violations. Do not suppress it without explicit justification.\n- Run the §3 pipeline on every changed file; fix every `PLR2004` by naming the value or converting it to an enum.\n- The agent MUST self-review new function signatures for bare `dict`, `**kwargs`, magic literals, and missing enum\u002Fdata-carrier types before declaring the task complete.\n\n***\n\n## 7. Logging and Output\n\n[ref: #py-logging]\n\n- Every Python file that produces any diagnostic, status, warning, or error output MUST define a module-level logger:\n  ```python\n  logger = logging.getLogger(__name__)\n  ```\n- `print()` and `sys.stdout.write()` are forbidden for logging, debugging, status, warning, or error output. Use `logger.debug\u002Finfo\u002Fwarning\u002Ferror\u002Fexception` instead.\n- For the script's actual product output (e.g., a CLI reporter, a pipe-friendly tool), use `print()` by default. Use `sys.stdout.write()` only when precise control is needed (no newline, raw strings, performance).\n- Never swallow exceptions, errors, or unusual conditions silently. Log them at the appropriate level.\n- Use `logger.exception(...)` inside `except` blocks to capture the traceback.\n- Log messages must be concise and include relevant context (identifiers, paths, operation names); avoid dumping large objects or full tracebacks at `INFO` level.\n- At module load time, use `logger.debug`.\n","# SKILL: Strict Python Engineering & Compliance\n\nYou are an expert Python Engineer and a strict Code Reviewer. **This document is a binding rule set, not a recommendation.**\nEvery directive in this guide MUST be followed unless it explicitly uses **SHOULD** or **MAY**. The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"NOT RECOMMENDED\", \"MAY\", and \"OPTIONAL\" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when they appear in all capitals or in bold markup.\n\n## 1. Compliance and Local Style\n\n* **Default Rule:** Unless a section, paragraph, or sentence explicitly uses **SHOULD** or **MAY**, every statement is to be treated as **MUST**. If a coding situation is covered by this guide, you MUST follow the guide. You MUST NOT apply external style preferences or general Python heuristics in place of the rules documented here.\n* **Consistency:** BE CONSISTENT. If you are editing code, ALWAYS look at the code around you and you MUST match its style. Local style is VERY IMPORTANT. If code you add looks drastically different from the existing code, it throws readers out of their rhythm. Consistency applies more heavily locally and on choices unspecified by the global style.\n* **Deviation Justification:** If you deviate from any MUST directive, you MUST explicitly justify the deviation in your output.\n* **Skill Boundary:** This skill covers Python language and style rules. For API resource design, HTTP\u002FgRPC routes, and proto structure, consult the `api-design` skill.\n* **RFC Verbs:** For precise semantics of requirement-level verbs, consult the `read-for-comments` skill.\n\n***\n\n## 2. Mandatory Lookups (Lazy-Load Protocol)\n\n**This routing is mandatory.** When the task touches Python language or style rules, you MUST route through the corpus frontmatter before reading any body. Do not guess, do not rely on training data, and do not skip routing because the topic seems familiar. You MUST NOT read the reference files in their entirety.\n\n**Corpus:**\n\n- `references\u002F01_language_rules.md` — Google language rules; 20 routable sections, anchors `py-lr-*`.\n- `references\u002F02_style_rules.md` — Google style rules; 53 routable sections including the subsection-level chapters 2.8 \u002F 2.10 \u002F 2.16 \u002F 2.19, anchors `py-st-*`.\n- `references\u002F03_personal_rules.md` — project-specific rules that EXTEND and OVERRIDE the Google corpora on conflict, anchors `py-pr-*`. Its frontmatter is small: shortlist it on EVERY funnel pass so overrides are never missed.\n\n**Toolchain precedence (HARD):** the corpus reproduces upstream Google text that references `pylint` and `pytype`. Those references are historical context only. The governing local toolchain is Ruff for lint\u002Fformat (§3, mandatory) and mypy for type checking (`03_personal_rules.md`). Where a corpus section and this skill's §3 conflict, §3 wins; say so per §1 (Deviation Justification).\n\n**Skill addendum (lazyload):** `prompts\u002FREFERENCE_STANDARD_ADDENDUM.md` declares the two-tier anchor prefixes (`py-lr-`, `py-st-`, `py-pr-`), the tight `marker_style`, the Google-canon numbered-headings exemption, and the pseudo-heading legalization. Corpus frontmatter schema and card semantics defer to `frontmatter-protocol\u002Freferences\u002Flazyload.md`.\n\n**Routing Funnel (per `frontmatter-protocol` `[ref: #lazy-load-routing]`):**\n1. Run the subject map (Command 1) over `references\u002F` and shortlist candidate files semantically — the request plus inferred session work; shortlist generously.\n2. Read the full frontmatter of shortlisted files — `03_personal_rules.md` is always shortlisted — and match every card's `what` \u002F `use_when` \u002F `avoid_when` semantically (OR semantics); mark each matching card's `anchor`.\n3. Deduplicate anchors, then extract each selected section with the canonical bounded extraction — never a blind `rg -A N` window.\n4. Apply the extracted rules strictly.\n\n***\n\n## 3. Mandatory Lint & Format Pipeline (Unconditional Gate)\n\n**MANDATORY — ALWAYS, WITHOUT REMINDERS:** For EVERY Python file the agent writes, creates, or edits, the agent MUST run this pipeline before declaring the task complete. This gate is unconditional: it applies in addition to — and independently of — any project-level linting, formatter configuration, pre-commit hooks, or CI checks present in the target project. The agent MUST NOT skip it because \"the project has its own linting\", MUST NOT wait for the user to ask, and MUST NOT consider the task done until both stages pass on the agent's own changes.\n\nThe pipeline is Ruff-only (`black`, `flake8`, and `isort` are forbidden per the `mandatory-tools` skill) and has two mandatory stages, executed in this exact order:\n\n1. **Format** — `ruff format` (black-compatible automatic formatting).\n2. **Lint** — `ruff check --fix` (full-rule diagnostics WITH automatic in-place fixes; fixes scoped to the agent's own edits).\n\n**`--fix` is a mandatory part of the pipeline (HARD):** the lint stage's FIRST invocation MUST carry `--fix`, letting Ruff rewrite auto-fixable violations in place. The agent MUST NOT hand-edit what `ruff check --fix` repairs mechanically — manual fixing of auto-fixable violations wastes tokens and energy and is a pipeline violation. Manual edits are reserved for diagnostics that `--fix` cannot repair.\n\n**The `[*]` reminder rule (HARD):** the output line `[*] fixable with the \\`--fix\\` option.` means the previous run forgot `--fix`. On seeing it the agent MUST: (1) immediately recall that the first pass ALWAYS runs with `--fix`, and (2) immediately re-run the same command with `--fix` — before reading or hand-fixing any diagnostic. Treat every occurrence as a self-check failure of this pipeline.\n\n### Hard Constraint: Foreign Code Isolation\n* **ONLY** format and fix violations in code you explicitly wrote or modified.\n* **NEVER** change unmodified (\"foreign\") code to satisfy the formatter or linter.\n* If a violation exists in unmodified code, ignore it completely.\n* If the linter suggests moving or refactoring that would affect unmodified code, skip the suggestion.\n* Run every pipeline command with an explicit file list (`\u003Cchanged_files>`) — NEVER against the whole project, a whole directory, or files you did not touch.\n\n### Restoring Foreign Code After Formatting (MANDATORY)\nAutomatic formatters rewrite whole lines and may reformat code the agent never intended to touch. Foreign code MUST be returned to its exact prior state:\n\n1. **Baseline first.** Before running `ruff format`, make sure a restorable baseline exists for every target file (a git-tracked file with a committed or staged state, or an explicit backup copy). If `git diff \u003Cfile>` cannot serve as the baseline for a target file, create a backup copy of it BEFORE formatting.\n2. **Inspect every hunk.** After formatting, run `git diff \u003Cfile>` (or diff against the backup) and review each hunk individually.\n3. **Revert foreign hunks.** Any hunk that rewrites lines the agent did NOT author or intend to modify MUST be reverted (targeted `git checkout -p`, interactive hunk discard, or manual re-application) so foreign code becomes byte-identical to its baseline. NEVER blanket-revert: your own changes MUST survive.\n4. **Re-verify.** Re-run `ruff format --check` and `ruff check` on the file. If reverting a foreign hunk makes your own code fail the pipeline, re-apply formatting to your lines manually until both stages pass.\n5. **Justify unavoidable bleed.** If a formatter-mandated change physically cannot be limited to your own lines (for example, the formatter rewraps a construct that spans your edit), you MUST explicitly justify the deviation in your output per §1 (Deviation Justification).\n6. **Final scope check.** The delivered diff MUST contain formatting and lint changes ONLY within code the agent wrote or modified.\n\n### Step 3.1: Discover Target Python Version\nDetermine the project's target Python version before linting by executing:\n```bash\nuv run python -c \"import sys; print(f'py{sys.version_info.major}{sys.version_info.minor}')\"\n```\n*Use this exact value for `\u003CPYVER>` in the subsequent steps.*\n\n### Step 3.2: Format Own Changes (Black-Compatible)\nRun the formatter targeting **ONLY the files you created or modified**, then immediately perform the **Restoring Foreign Code After Formatting** procedure above:\n```bash\nuvx ruff format \u003Cchanged_files>\n```\n`\u003Cchanged_files>` is the explicit list of files the agent wrote or edited — nothing else. This stage replaces `black`: `ruff format` implements black-compatible formatting, and invoking `black` itself is forbidden.\n\n### Step 3.3: Fix and Read Linter Suggestions\nRun the following command targeting **ONLY the files you modified** — the `--fix` flag is MANDATORY on this first lint pass (see the HARD rules above); Ruff rewrites fixable violations in place:\n```bash\nuvx ruff check --fix --select ALL --ignore D,CPY,DOC,EM101,ERA001,FBT001,FBT002,FIX001,FIX002,TD001,TD002,TD003,TD004,TD005,TRY003 --target-version \u003CPYVER> --output-format concise \u003Cchanged_files>\n```\nRead every REMAINING suggestion carefully (these are the ones `--fix` could not repair). Apply manual fixes ONLY to the code you altered.\n\n### Step 3.4: Preview Remaining Fixes\nAfter applying fixes, confirm no auto-fixable violations remain — the emitted diff MUST be empty (any non-empty hunk is a fix you still owe or a foreign line you MUST NOT apply):\n```bash\nuvx ruff check --select ALL --ignore D,CPY,DOC,EM101,ERA001,FBT001,FBT002,FIX001,FIX002,TD001,TD002,TD003,TD004,TD005,TRY003 --target-version \u003CPYVER> --diff \u003Cchanged_files>\n```\nThis previews would-be fixes only; final git-scope verification is §4 step 6.\n\n### Step 3.5: Rule Lookup\nIf you are uncertain about any rule code generated by the linter, use:\n```bash\nuvx ruff rule \u003CRULE_CODE>\n```\n*(Example: `uvx ruff rule E501`)*\n\n### Pipeline Failure Handling (HARD)\nIf any pipeline command cannot run or errors out — `uv`\u002F`uvx`\u002F`ruff` missing, the target project is not uv-managed and `uv run` fails, Ruff crashes on a syntax error mid-edit — the agent MUST STOP, report the exact failure and its output to the user, and ask how to proceed. The gate is unconditional, but it is NEVER satisfied by silently skipping it or by substituting another linter (`black`, `flake8`, `isort` stay forbidden).\n\n***\n\n## 4. Master Execution Workflow\n1. **Analyze Task:** Determine the specific Python operations required.\n2. **Component Reuse Check:** Apply the §5 Component Reuse Rule before writing any code.\n3. **Route:** Run the §2 routing funnel over the `references\u002F` corpus (subject map → frontmatter cards → bounded extraction of the selected `py-*` sections).\n4. **Code Generation:** Write the code strictly adhering to the extracted rules, the reuse manifests, AND local file consistency.\n5. **Lint & Format:** Execute the full Mandatory Lint & Format Pipeline (§3), including foreign-code restoration, on every file the agent wrote or edited — unconditionally, without reminders, and regardless of any project-level linting.\n6. **Final Verification:** Confirm via `git diff` that no unmodified (foreign) code was altered before concluding the task; any formatter bleed into foreign lines must already be reverted or explicitly justified.\n\n***\n\n## 5. Component Reuse Rule\n\nBefore implementing any new Python module, class, or function, the agent MUST check whether the project root contains a `.sdk\u002F` directory.\n\n### 5.1 Discovery\nIf `.sdk\u002F` exists, discover all reuse manifests with: `fd -L -t f EXPORT.md .sdk\u002F`\n\nRead every returned file before writing code.\n\n### 5.2 Applying Manifests\nEach `EXPORT.md` describes reusable components and the criteria for copying them whole.\nApply those criteria strictly.\nAfter copying a module, replace the source package prefix with the target project's package prefix and run the Mandatory Lint & Format Pipeline (§3) only on the changed files.\n\n***\n\n## 6. Constants, Enums, Magic Values, and Data Carriers\n\n[ref: #py-constants-enums]\n\nThis section is mandatory. It applies to every Python file the agent writes, edits, or reviews.\n\n### 6.1 No magic values\n\n- A \"magic value\" is any numeric or string literal that carries semantic meaning outside the immediate syntax (e.g., `200`, `404`, `\"pending\"`, `0.95`, `86400`, `1 \u003C\u003C 41`).\n- Magic values MUST NOT appear inline in expressions, comparisons, function arguments, or return values.\n- The only literals allowed inline are:\n  - `0`, `1`, `-1` when used as pure arithmetic\u002Findexing identities.\n  - `True`, `False`, `None`.\n  - Mathematical identity values such as `base=10` or `radix=10`, documented in the same line.\n\n### 6.2 Use enums for categorical values\n\n- Categorical string values MUST be represented as `StrEnum` with `auto()`:\n  ```python\n  class Role(StrEnum):\n      ADMIN = auto()\n      USER = auto()\n  ```\n- Categorical numeric values MUST be represented as `Enum`:\n  ```python\n  class Priority(Enum):\n      LOW = 1\n      HIGH = 2\n  ```\n- Bit flags and masks MUST be represented as `IntFlag`:\n  ```python\n  class Permission(IntFlag):\n      READ = auto()\n      WRITE = auto()\n  ```\n- Prefer `auto()` for every member whose concrete value is not semantically significant. When only some members need custom values, assign those explicitly and keep `auto()` for the rest. Do not hand-write every value just because one member requires a custom value:\n  ```python\n  class ReconTarget(StrEnum):\n      PROGRAMS_INDEX = \"\u002Fprograms\"\n      AUTHOR_INDEX = \"\u002Fauthor\"\n      ARCHIVE_INDEX = \"\u002Farchive\"\n      NEWS_SECTION = auto()\n      OPINIONS_SECTION = auto()\n  ```\n\n### 6.3 Sentinel values\n\n- Do not use magic strings or numbers as sentinels (e.g., `result = -1`, `name = \"N\u002FA\"`, `value = 999`).\n- Use a dedicated enum member or a singleton sentinel object:\n  ```python\n  class Result(Enum):\n      FOUND = auto()\n      NOT_FOUND = auto()\n  ```\n\n### 6.4 Module-level constants\n\n- Any semantic value that is not naturally an enum MUST be defined as a module-level `ALL_CAPS` constant.\n- Examples: `TIMEOUT_SECONDS = 10.0`, `REFRESH_BUFFER_RATIO = 0.95`, `MAX_RETRIES = 3`.\n- Constants MUST be placed near the top of the module, after imports.\n- Whenever several constants form a logical or semantic group — such as URL path prefixes, section identifiers, feature flags, or configuration keys — they SHOULD be grouped into a single enum instead of being declared as separate `ALL_CAPS` constants. Prefer `StrEnum` for string groups, `Enum` for numeric groups, and `IntFlag` for flags. This makes the grouping explicit, gives it a name, and prevents accidental mixing with unrelated constants.\n\n### 6.5 Function-boundary constants\n\n- `Literal[...]` is allowed ONLY at boundaries where the value comes from outside the application and cannot yet be an enum (e.g., raw external API input, CLI flags).\n- Inside the application, categorical strings and numbers MUST be `Enum`\u002F`StrEnum` members, not `Literal`.\n- If the value can be modeled as a dataclass or Pydantic model, use that instead of `Literal`.\n\n### 6.6 HTTP status codes\n\n- HTTP status codes MUST NOT be written as bare integers.\n- If `starlette` is available, use `from starlette import status` and `status.HTTP_200_OK`.\n- Otherwise use `http.HTTPStatus.OK` from the standard library.\n- Never use `200`, `201`, `400`, `404`, `500`, etc.\n\n### 6.7 Data carriers\n\n- Functions in application code MUST NOT accept or return plain `dict` as their public contract.\n- Raw `dict` is allowed only as the immediate input to a parser\u002Fvalidator; it MUST be wrapped in a model or dataclass before crossing any application function boundary.\n- Inside the application, use frozen `dataclass` instances (`@dataclass(frozen=True)`).\n- At application boundaries (HTTP, files, env, external APIs, CLI input), use Pydantic models. If Pydantic is unavailable, use a dataclass with explicit validation.\n- `argparse.Namespace` and similar CLI parsers must be mapped to a dataclass or Pydantic model before use.\n- `TypedDict` is allowed ONLY as an exception, with the user's explicit approval, and only for dict-shaped data that cannot be a dataclass\u002FPydantic model.\n- `NamedTuple`\u002F`namedtuple` is allowed for performance-oriented intermediate representations when the data has already been validated by Pydantic models or sourced from dataclasses. It MUST NOT be used as the primary boundary carrier.\n\n### 6.8 No `**` unpacking\n\n- The `**` operator MUST NOT be used to unpack dictionaries into function arguments.\n- Every argument MUST be passed explicitly by name or position.\n- Bad: `func(**kwargs)`, `obj.method(**config_dict)`.\n- Good: `func(name=user.name, role=user.role)`.\n\n### 6.9 Examples\n\nBad:\n```python\nif response.status_code == 200:\n    ...\nwait(0.95)\n```\n\nGood:\n```python\nfrom starlette import status\nif response.status_code == status.HTTP_200_OK:\n    ...\nwait(REFRESH_BUFFER_RATIO)\n```\n\nBad:\n```python\ndef create_user(data: dict) -> dict:\n    ...\n```\n\nGood:\n```python\n@dataclass(frozen=True)\nclass UserCreate: ...\n\n@dataclass(frozen=True)\nclass User: ...\n\ndef create_user(data: UserCreate) -> User:\n    ...\n```\n\n### 6.10 Enforcement\n\n- Ruff rule `PLR2004` catches many magic-value violations. Do not suppress it without explicit justification.\n- Run the §3 pipeline on every changed file; fix every `PLR2004` by naming the value or converting it to an enum.\n- The agent MUST self-review new function signatures for bare `dict`, `**kwargs`, magic literals, and missing enum\u002Fdata-carrier types before declaring the task complete.\n\n***\n\n## 7. Logging and Output\n\n[ref: #py-logging]\n\n- Every Python file that produces any diagnostic, status, warning, or error output MUST define a module-level logger:\n  ```python\n  logger = logging.getLogger(__name__)\n  ```\n- `print()` and `sys.stdout.write()` are forbidden for logging, debugging, status, warning, or error output. Use `logger.debug\u002Finfo\u002Fwarning\u002Ferror\u002Fexception` instead.\n- For the script's actual product output (e.g., a CLI reporter, a pipe-friendly tool), use `print()` by default. Use `sys.stdout.write()` only when precise control is needed (no newline, raw strings, performance).\n- Never swallow exceptions, errors, or unusual conditions silently. Log them at the appropriate level.\n- Use `logger.exception(...)` inside `except` blocks to capture the traceback.\n- Log messages must be concise and include relevant context (identifiers, paths, operation names); avoid dumping large objects or full tracebacks at `INFO` level.\n- At module load time, use `logger.debug`.\n",{"name":5,"runtime":24,"version":25,"requires":26,"triggers":29,"description":7},true,"0.1.0",[27,28],"frontmatter-protocol","read-for-comments",{"any":30},{"files":31,"request":32},"fd -e py -e pyi --max-results 1 | wc -l | grep -q 1","python, питон","main","7da8c355f6e99dcb88d8bb9f6ff27b3cb35bae47",0,"https:\u002F\u002Fgithub.com\u002Fkalaverin\u002Fskills","https:\u002F\u002Fgithub.com\u002Fkalaverin","2026-11-15 01:37:57",{"source":8,"skillName":5,"commands":40,"prompt":50,"zipAvailable":24},[41,44,47],{"tool":42,"command":43},"npx","npx skills add kalaverin\u002Fskills --skill python-lang",{"tool":45,"command":46},"bunx","bunx skills add kalaverin\u002Fskills --skill python-lang",{"tool":48,"command":49},"pnpm","pnpm dlx skills add kalaverin\u002Fskills --skill python-lang","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fkalaverin\u002Fskills\u002Fblob\u002Fmain\u002Fpython-lang\u002FSKILL.md",[52,58,62,66,70],{"path":53,"resourceType":54,"resourceTypeDesc":55,"sizeBytes":56,"sourceHtmlUrl":57},"prompts\u002FREFERENCE_STANDARD_ADDENDUM.md","REFERENCE","参考文档",3315,"https:\u002F\u002Fgithub.com\u002Fkalaverin\u002Fskills\u002Fblob\u002Fmain\u002Fpython-lang\u002Fprompts\u002FREFERENCE_STANDARD_ADDENDUM.md",{"path":59,"resourceType":54,"resourceTypeDesc":55,"sizeBytes":60,"sourceHtmlUrl":61},"README.md",4486,"https:\u002F\u002Fgithub.com\u002Fkalaverin\u002Fskills\u002Fblob\u002Fmain\u002Fpython-lang\u002FREADME.md",{"path":63,"resourceType":54,"resourceTypeDesc":55,"sizeBytes":64,"sourceHtmlUrl":65},"references\u002F01_language_rules.md",42172,"https:\u002F\u002Fgithub.com\u002Fkalaverin\u002Fskills\u002Fblob\u002Fmain\u002Fpython-lang\u002Freferences\u002F01_language_rules.md",{"path":67,"resourceType":54,"resourceTypeDesc":55,"sizeBytes":68,"sourceHtmlUrl":69},"references\u002F02_style_rules.md",93343,"https:\u002F\u002Fgithub.com\u002Fkalaverin\u002Fskills\u002Fblob\u002Fmain\u002Fpython-lang\u002Freferences\u002F02_style_rules.md",{"path":71,"resourceType":54,"resourceTypeDesc":55,"sizeBytes":72,"sourceHtmlUrl":73},"references\u002F03_personal_rules.md",2658,"https:\u002F\u002Fgithub.com\u002Fkalaverin\u002Fskills\u002Fblob\u002Fmain\u002Fpython-lang\u002Freferences\u002F03_personal_rules.md",[75,82,89,96,102,109],{"skillNo":76,"name":77,"nameZh":6,"description":78,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":19},"01M786R9KK7RP1J8EB7X9TC9KR","todo-protocol","Mandatory protocol for using the SetTodoList tool. Governs when to create a todo list, how to update it without violating immutability rules, how to synchronize item status after every tool call, and the forbidden mutations. Always active.","https:\u002F\u002Fgithub.com\u002Fkalaverin\u002Fskills\u002Fblob\u002Fmain\u002Ftodo-protocol\u002FSKILL.md",[],[],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":19},"01M786QZTC43FBK3A251NTY62Y","subagents-protocol","Mandatory protocol for delegating work to built-in subagents (coder, explore, plan), also called our bots by users. Always active. Owns the context-hygiene delegation test (material vs answer, cost balance, warm-instance reuse), launch parameters (mandatory explicit `model`), the single-source model-selection table, answer budgets, degradation handling, the launch checklist, and the role library for delegated review\u002Faudit with intent routing (`references\u002Froles.md`).","https:\u002F\u002Fgithub.com\u002Fkalaverin\u002Fskills\u002Fblob\u002Fmain\u002Fsubagents-protocol\u002FSKILL.md",[],[],{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":95,"publishedAt":19},"01M786QSXFDM550NCC4PQXN26X","serena-protocol","MANDATORY skill for Serena (MCP) memory, knowledge base, and symbolic code exploration operations. Use whenever the agent needs to: read or write Serena memories, mutate or persist memory, explore code via symbolic MCP tools, resolve contradictions in stored knowledge, or follow memory metadata, naming, and routing conventions.","https:\u002F\u002Fgithub.com\u002Fkalaverin\u002Fskills\u002Fblob\u002Fmain\u002Fserena-protocol\u002FSKILL.md",[],[],{"skillNo":97,"name":28,"nameZh":6,"description":98,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":99,"categories":100,"keywords":101,"publishedAt":19},"01M786QMXA58XD5DJZ2AZER5ZP","Mandatory local standards library and archive. Before fetching any standard from the internet, the agent MUST check the Serena `standard\u002F` archive and this skill's `references\u002F` seed; after ANY standard-body download, the agent MUST archive it per the event-bound Archival Rule. Governs standard lookup, fetch, archival, and the family and full-body rules.","https:\u002F\u002Fgithub.com\u002Fkalaverin\u002Fskills\u002Fblob\u002Fmain\u002Fread-for-comments\u002FSKILL.md",[],[],{"skillNo":103,"name":104,"nameZh":6,"description":105,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":106,"categories":107,"keywords":108,"publishedAt":19},"01M786Q683RHDC93NWABY7XKQN","preflight-checklist","Mandatory session-initialization closer and Startup Gate audit. Always loaded. Runs EXACTLY ONCE at session start, after all skill loading completes: verifies Startup Gate completion with evidence (mirror sync, forced import, discovery, activation, memory priming, MCP declaration, think block), runs dynamic session checks derived from the active skill set (mode states, delegation readiness), and reports a compact evidence-backed verdict table to the user before the first task output. Any FAIL is fixed before proceeding.","https:\u002F\u002Fgithub.com\u002Fkalaverin\u002Fskills\u002Fblob\u002Fmain\u002Fpreflight-checklist\u002FSKILL.md",[],[],{"skillNo":110,"name":111,"nameZh":6,"description":112,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":113,"categories":114,"keywords":115,"publishedAt":19},"01M786PZ0J271Q5HWQ8B3S0ZP8","markdown-protocol","MANDATORY skill for Markdown authoring rules and the Markdown Headings as a Public API standard. Always active. Governs how the agent writes and edits any Markdown file: line discipline, date format, frontmatter pairing, markers and anchors, heading identity (slugs, renames, uniqueness), section shape and size, deprecation, and the errata conformance queue. The full normative standard lives in references\u002Fspecification.md with rationale in references\u002Frationale.md.","https:\u002F\u002Fgithub.com\u002Fkalaverin\u002Fskills\u002Fblob\u002Fmain\u002Fmarkdown-protocol\u002FSKILL.md",[],[]]