Init repository

skills/python-development-code-style/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: python-development-code-style
+description: Code conventions, typing, testing habits, and engineering principles. Use when writing, reviewing, or refactoring Python code.
+---
+
+## Rules
+- Follow PEP 8 for all Python code. Use `ruff` for automatic formatting and linting.
+- Every package `__init__.py` must declare the public API explicitly with `__all__`. `__all__` is always a tuple, even when it contains a single element. Use inline comment group headers to separate imports by source module.
+- Inside `__init__.py` import only from sibling modules. Do not place executable code.
+- Group related names together in `__all__` and mirror the grouping with comment headers. Example:
+  ```python
+  from .base import BaseService, ServiceMixin
+  from .dto import ServiceInput, ServiceOutput
+  from .exceptions import ServiceError, ValidationError
+  from .fabric import get_service
+  from .settings import ServiceSettings
+
+  __all__ = (
+      # base
+      "BaseService",
+      "ServiceMixin",
+      # dto
+      "ServiceInput",
+      "ServiceOutput",
+      # exceptions
+      "ServiceError",
+      "ValidationError",
+      # fabric
+      "get_service",
+      # settings
+      "ServiceSettings",
+  )
+  ```
+- Wildcard imports (`from module import *`) are forbidden in every module, including `__init__.py`. Always import explicit names.
+- Within a package, import sibling modules using relative imports (`from .module import Name`). When importing from a different top-level package or from a parent package that is not a direct sibling, use an absolute import (`from project_name.module import Name`).
+- Group imports in every module into three blocks separated by a blank line:
+  1. Standard library (`import pathlib`, `from typing import Self`, etc.).
+  2. Third-party packages (`import yaml`, `from pydantic import Field`, etc.).
+  3. Project-local imports (`from .services import MyService`, `from microclaw.settings import Settings`, etc.).
+- Within each block, place `from ... import ...` lines first, then `import ...` lines. Sort all lines alphabetically. Example:
+  ```python
+  import json
+  import pathlib
+  from typing import Self
+
+  import yaml
+  from pydantic import Field
+  from pydantic_settings import BaseSettings
+
+  from .services import MyService
+  from microclaw.settings import Settings
+  ```
+- Functions and methods must not return tuples of multiple values. Returning a tuple is allowed only in exceptional cases (e.g. unpacking a well-known pair such as `(key, value)`). When a function needs to return more than one piece of data, define a Pydantic `BaseModel` for the result or reuse an existing model. This makes the return type self-documenting, enables IDE autocomplete, and keeps field names stable during refactoring.
+- Do not use `from __future__ import annotations`. Use explicit forward-reference strings (e.g. `"MyClass"`) when necessary.
+- Do not use `if TYPE_CHECKING:` blocks. Import the types you need at the top level. Deferred imports inside `TYPE_CHECKING` hide dependencies and break runtime introspection.
+- Do not abbreviate variable or parameter names. Write them out in full so the intent is obvious without context. Examples of forbidden abbreviations: `idx` (use `index`), `dep` (use `dependency`), `cfg` (use `config` or `configuration`), `msg` (use `message`), `err` (use `error`), `resp` (use `response`). The same rule applies to class attributes, function parameters, and local variables.