Claude Cursor opencode Skill

litestar-styleguide

Use when authoring Litestar skill content, Python/TypeScript examples, PEP 604, async I/O, Google docstrings, ruff/mypy/pyright, pytest, or CI rules. Not for focused Litestar APIs.

LLM Mart · 0 points · 3 views 0 listing impressions 0 install-command copies
Download litestar-org-litestar-skills-skills_litestar-styleguide-669a363.zip · 24 KB

Install

skills CLI npx skills add https://github.com/litestar-org/litestar-skills/tree/main/skills/litestar-styleguide
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install litestar-org-litestar-skills@llmmart
Git git clone https://github.com/litestar-org/litestar-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole litestar-org/litestar-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

litestar-styleguide

This is the shared style baseline that every other skill in this plugin references. It exists so that cross-cutting rules (PEP 604 unions, async I/O, ruff + mypy + pyright + prek, test file naming, CI/CD conventions) live in exactly one place — and individual skills stay focused on their framework or tool-specific surface.

Code Style Rules

  • Terse, imperative, authoritative. State the preferred choice and a one-line Reason:; never hedge ("you might want to…").
  • PEP 604 unions (T | None) and PEP 585 generics (list[T], dict[K, V]). Never use typing.Optional, typing.Union, typing.List, or typing.Dict.
  • from __future__ import annotations is a library-author guardrail, not a consumer rule. Application code (handlers, services, tests) MAY use it; avoid it only in modules defining runtime-introspected types (msgspec.Struct, SQLAlchemy Mapped[...], Dishka @provide, SAQ @task).
  • Keep runtime-inspected route annotations at module top-level (# noqa: TC001, TC002). When from __future__ import annotations and Ruff flake8-type-checking (TC) are active in Litestar controller/handler modules, keep Request, NamedDependency, FromDishka, FromPath, FromQuery, JSONBody, and request/response DTO imports at module top-level with # noqa: TC001, TC002 (or "**/controllers.py" = ["TC001", "TC002", "TC003"] in per-file-ignores), never inside if TYPE_CHECKING:. Reason: Litestar and Dishka inspect handler annotations at runtime during app startup and OpenAPI generation.
  • Async all I/O, Google-style docstrings, function-based pytest tests (@pytest.mark.anyio).
  • Litestar first-party stack bias with match-your-stack flexibility. Prefer msgspec, advanced-alchemy / sqlspec, litestar-granian, litestar-saq / litestar-queues when starting fresh, and match the user's existing stack when present.

Quick Reference

Slice Reference File Key Topics
Cross-language principles references/general.md Simplicity over cleverness, boundary validation, naming, import order
Python conventions references/python.md PEP 604/585, # noqa: TC001, TC002, msgspec.Struct, async I/O, docstrings, ruff, mypy, pyright, prek
Litestar baseline references/litestar.md Typed markers (FromPath, FromQuery, JSONBody, RequestBody, NamedDependency, SkipValidation), Provide vs Dishka, MsgspecDTO, Guards, plugins
TypeScript conventions references/typescript.md Strict tsconfig, discriminated unions, named exports, oxlint / biome
Testing conventions references/testing.md pytest + anyio, AsyncTestClient lifespan fixtures, Vitest, 90%+ coverage
CI/CD conventions references/ci-cd.md GitHub Actions with setup-uv, prek / .pre-commit-config.yaml, matrix builds
Canonical reference apps references/canonical-apps.md litestar-fullstack-inertia, litestar-fullstack, litestar-sqlstack, oracledb-vertexai-demo
Google Developer Knowledge MCP references/google-developer-knowledge-mcp.md Opt-in MCP setup for fresh GCP / Firebase / Maps documentation
Documentation architecture ../litestar-docs/SKILL.md Zensical Free (zensical.toml), mkdocstrings-python (Griffe), TypedDict inline docstrings, objects.inv, llms.txt

How sibling skills consume this

Every SKILL.md in this plugin has a ## Shared Styleguide Baseline section near the bottom. That section links to a subset of these references — only the ones that apply to the skill's language / framework mix. For example:

  • skills/litestar/SKILL.md links to general.md + python.md + litestar.md
  • skills/litestar-vite/SKILL.md links to general.md + typescript.md + litestar.md
  • skills/litestar-testing/SKILL.md links to general.md + testing.md + python.md + litestar.md

The sibling skill extends the baseline with its own tool-specific Code Style Rules, Quick Reference, Guardrails, and Validation — but it does not duplicate the baseline. If a convention is generic (type hints, naming, imports), it belongs here.

When to update this skill

  • A rule becomes contentious across two or more sibling skills → pull it into the right baseline reference file here.
  • A new language lands (Rust, Mojo, etc.) → add a new references/<lang>.md and link from skills that use it.
  • A tool is swapped out (e.g., ruff replaces flake8 + black, prek replaces pre-commit CLI) → update python.md / ci-cd.md once; all sibling skills inherit it.

References Index

Official References

Shared Styleguide Baseline

Files (litestar-skills)
  • references
    • canonical-apps.md 2.4 KB
      Loading…
    • ci-cd.md 3.8 KB
      Loading…
    • general.md 2.8 KB
      Loading…
    • google-developer-knowledge-mcp.md 3.6 KB
      Loading…
    • litestar.md 12.6 KB
      Loading…
    • python.md 11.2 KB
      Loading…
    • testing.md 7.2 KB
      Loading…
    • typescript.md 5.5 KB
      Loading…
  • SKILL.md 8 KB
    ---
    name: litestar-styleguide
    description: "Use when authoring Litestar skill content, Python/TypeScript examples, PEP 604, async I/O, Google docstrings, ruff/mypy/pyright, pytest, or CI rules. Not for focused Litestar APIs."
    ---
    
    # litestar-styleguide
    
    This is the **shared style baseline** that every other skill in this plugin references. It exists so that cross-cutting rules (PEP 604 unions, async I/O, ruff + mypy + pyright + prek, test file naming, CI/CD conventions) live in exactly one place — and individual skills stay focused on their framework or tool-specific surface.
    
    ## Code Style Rules
    
    - **Terse, imperative, authoritative.** State the preferred choice and a one-line `Reason:`; never hedge ("you might want to…").
    - **PEP 604 unions (`T | None`) and PEP 585 generics (`list[T]`, `dict[K, V]`).** Never use `typing.Optional`, `typing.Union`, `typing.List`, or `typing.Dict`.
    - **`from __future__ import annotations` is a library-author guardrail, not a consumer rule.** Application code (handlers, services, tests) MAY use it; avoid it only in modules defining runtime-introspected types (`msgspec.Struct`, SQLAlchemy `Mapped[...]`, Dishka `@provide`, SAQ `@task`).
    - **Keep runtime-inspected route annotations at module top-level (`# noqa: TC001, TC002`).** When `from __future__ import annotations` and Ruff `flake8-type-checking` (`TC`) are active in Litestar controller/handler modules, keep `Request`, `NamedDependency`, `FromDishka`, `FromPath`, `FromQuery`, `JSONBody`, and request/response DTO imports at module top-level with `# noqa: TC001, TC002` (or `"**/controllers.py" = ["TC001", "TC002", "TC003"]` in `per-file-ignores`), never inside `if TYPE_CHECKING:`. Reason: Litestar and Dishka inspect handler annotations at runtime during app startup and OpenAPI generation.
    - **Async all I/O, Google-style docstrings, function-based pytest tests (`@pytest.mark.anyio`).**
    - **Litestar first-party stack bias with match-your-stack flexibility.** Prefer `msgspec`, `advanced-alchemy` / `sqlspec`, `litestar-granian`, `litestar-saq` / `litestar-queues` when starting fresh, and match the user's existing stack when present.
    
    ## Quick Reference
    
    | Slice | Reference File | Key Topics |
    | --- | --- | --- |
    | Cross-language principles | [`references/general.md`](references/general.md) | Simplicity over cleverness, boundary validation, naming, import order |
    | Python conventions | [`references/python.md`](references/python.md) | PEP 604/585, `# noqa: TC001, TC002`, `msgspec.Struct`, async I/O, docstrings, `ruff`, `mypy`, `pyright`, `prek` |
    | Litestar baseline | [`references/litestar.md`](references/litestar.md) | Typed markers (`FromPath`, `FromQuery`, `JSONBody`, `RequestBody`, `NamedDependency`, `SkipValidation`), `Provide` vs Dishka, `MsgspecDTO`, Guards, plugins |
    | TypeScript conventions | [`references/typescript.md`](references/typescript.md) | Strict `tsconfig`, discriminated unions, named exports, `oxlint` / `biome` |
    | Testing conventions | [`references/testing.md`](references/testing.md) | `pytest` + `anyio`, `AsyncTestClient` lifespan fixtures, Vitest, 90%+ coverage |
    | CI/CD conventions | [`references/ci-cd.md`](references/ci-cd.md) | GitHub Actions with `setup-uv`, `prek` / `.pre-commit-config.yaml`, matrix builds |
    | Canonical reference apps | [`references/canonical-apps.md`](references/canonical-apps.md) | `litestar-fullstack-inertia`, `litestar-fullstack`, `litestar-sqlstack`, `oracledb-vertexai-demo` |
    | Google Developer Knowledge MCP | [`references/google-developer-knowledge-mcp.md`](references/google-developer-knowledge-mcp.md) | Opt-in MCP setup for fresh GCP / Firebase / Maps documentation |
    | Documentation architecture | [`../litestar-docs/SKILL.md`](../litestar-docs/SKILL.md) | Zensical Free (`zensical.toml`), `mkdocstrings-python` (Griffe), `TypedDict` inline docstrings, `objects.inv`, `llms.txt` |
    
    ### How sibling skills consume this
    
    Every `SKILL.md` in this plugin has a `## Shared Styleguide Baseline` section near the bottom. That section links to a subset of these references — only the ones that apply to the skill's language / framework mix. For example:
    
    - `skills/litestar/SKILL.md` links to `general.md` + `python.md` + `litestar.md`
    - `skills/litestar-vite/SKILL.md` links to `general.md` + `typescript.md` + `litestar.md`
    - `skills/litestar-testing/SKILL.md` links to `general.md` + `testing.md` + `python.md` + `litestar.md`
    
    The sibling skill extends the baseline with its own tool-specific Code Style Rules, Quick Reference, Guardrails, and Validation — but it does not duplicate the baseline. If a convention is generic (type hints, naming, imports), it belongs here.
    
    ### When to update this skill
    
    - A rule becomes contentious across two or more sibling skills → pull it into the right baseline reference file here.
    - A new language lands (Rust, Mojo, etc.) → add a new `references/<lang>.md` and link from skills that use it.
    - A tool is swapped out (e.g., ruff replaces flake8 + black, `prek` replaces `pre-commit` CLI) → update `python.md` / `ci-cd.md` once; all sibling skills inherit it.
    
    <workflow>
    
    ## Workflow — consuming this baseline
    
    1. Open the sibling skill you are editing (`skills/<name>/SKILL.md`).
    2. Look at its `## Shared Styleguide Baseline` section — it already lists a subset of the references here.
    3. When adding a rule to the sibling, ask: is it generic (language/tooling) or framework-specific? Generic → land it in the right file under `references/` here. Specific → keep it in the sibling.
    4. Cross-link bidirectionally if a rule here is amplified in the sibling.
    
    </workflow>
    
    <guardrails>
    
    ## Guardrails
    
    - **No duplication across skills.** A rule lives in exactly one file; sibling skills link to it.
    - **No folklore.** Every rule has a one-line justification (perf, runtime introspection, OpenAPI alignment, etc.). Delete rules you cannot justify.
    - **Terse and imperative.** Bullets are ≤ 2 sentences. If a topic needs more, split it into its own reference file.
    - **Examples are minimal and copy-pasteable.** No pseudo-code; no multi-hundred-line fixtures.
    
    </guardrails>
    
    <validation>
    
    ## Validation Checkpoint
    
    - [ ] Every sibling skill's `## Shared Styleguide Baseline` section resolves to files that exist under `references/`
    - [ ] No rule is duplicated between two reference files (check via grep when editing)
    - [ ] Each "never do X" rule has a one-line `Reason:` explanation
    - [ ] New language support lands as a single new `references/<lang>.md` — not scattered into sibling skills
    
    </validation>
    
    <example>
    
    ## Example — adding a new rule
    
    A reviewer finds that two sibling skills independently wrote "use `ruff format` not `black`". Instead of leaving duplicates, pull the rule into `references/python.md`:
    
    ```markdown
    - **Use `ruff format`, never `black`.** Reason: ruff is the single toolchain for
      lint + format; running two formatters produces style drift.
    ```
    
    Then in each sibling's `SKILL.md`, replace the duplicate with a pointer:
    
    ```markdown
    ## Shared Styleguide Baseline
    
    - [Python](../litestar-styleguide/references/python.md)
    ```
    
    </example>
    
    ## References Index
    
    - [General Principles](references/general.md)
    - [Python](references/python.md)
    - [Litestar](references/litestar.md)
    - [TypeScript](references/typescript.md)
    - [Testing](references/testing.md)
    - [CI/CD](references/ci-cd.md)
    - [Canonical Reference Apps](references/canonical-apps.md)
    - [Google Developer Knowledge MCP](references/google-developer-knowledge-mcp.md)
    
    ## Official References
    
    - <https://peps.python.org/pep-0604/> — PEP 604 union syntax
    - <https://docs.astral.sh/ruff/> — ruff linter / formatter
    - <https://docs.astral.sh/uv/> — uv package and environment manager
    - <https://mypy.readthedocs.io/en/stable/> — mypy static type checker
    - <https://microsoft.github.io/pyright/> — pyright type checker
    - <https://docs.pytest.org/> — pytest
    
    ## Shared Styleguide Baseline
    
    - [General Principles](references/general.md)
    - [Python](references/python.md)
    - [Litestar](references/litestar.md)
    - [TypeScript](references/typescript.md)
    - [Testing](references/testing.md)
    - [CI/CD](references/ci-cd.md)
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.