{"id":"f7a25287-a719-40c5-9bce-4e52e6faa2e7","shortId":"WF9pG9","kind":"skill","title":"litestar-styleguide","tagline":"Use when authoring or reviewing Litestar skill content, Python examples, TypeScript examples, shared style rules, PEP 604 unions, async I/O, Google docstrings, ruff/mypy/pyright tooling, pytest conventions, or CI/CD rules. Not for framework-specific implementation guidance - use ","description":"# litestar-styleguide\n\nThis 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, test file naming, CI/CD conventions) live in exactly one place — and individual skills stay focused on their framework or tool-specific surface.\n\n## What's in here\n\nEach reference covers one slice of the code-style baseline. A sibling skill links to only the files relevant to its language / framework mix.\n\n- [`references/general.md`](references/general.md) — Cross-language principles (simplicity over cleverness, error handling, naming, DRY-when-it-pays)\n- [`references/python.md`](references/python.md) — Python conventions (PEP 604 unions, docstrings, imports, ruff / mypy / pyright configuration)\n- [`references/litestar.md`](references/litestar.md) — Litestar-specific baseline (guards, DTOs, DI, plugin use)\n- [`references/typescript.md`](references/typescript.md) — TypeScript conventions (when paired with a frontend skill)\n- [`references/testing.md`](references/testing.md) — Testing conventions (pytest, vitest, fixtures, coverage)\n- [`references/ci-cd.md`](references/ci-cd.md) — CI/CD conventions (GitHub Actions, matrix builds, caching)\n\n## How sibling skills consume this\n\nEvery `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:\n\n- `skills/litestar/SKILL.md` links to `general.md` + `python.md` + `litestar.md`\n- `skills/litestar-vite/SKILL.md` links to `general.md` + `typescript.md` + `litestar.md`\n- `skills/litestar-testing/SKILL.md` links to `general.md` + `testing.md` + `python.md` + `litestar.md`\n\nThe 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.\n\n## When to update this skill\n\n- A rule becomes contentious across two or more sibling skills → pull it into the right baseline reference file here.\n- A new language lands (Rust, Mojo, etc.) → add a new `references/<lang>.md` and link from skills that use it.\n- A tool is swapped out (e.g., ruff replaces flake8 + black) → update `python.md` once; all sibling skills inherit it.\n\n## Authoring rule for this skill\n\n- Keep references **terse, imperative, authoritative**. No hedging (\"you might want to…\"). State the preferred choice and the one-line reason.\n- Every \"never do X\" rule has a one-line *why* (perf, runtime introspection, OpenAPI alignment, etc.). No folklore.\n- Examples are copy-pasteable and minimal. No pseudo-code.\n\n<workflow>\n\n## Workflow — consuming this baseline\n\n1. Open the sibling skill you are editing (`skills/<name>/SKILL.md`).\n2. Look at its `## Shared Styleguide Baseline` section — it already lists a subset of the references here.\n3. 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.\n4. Cross-link bidirectionally if a rule here is amplified in the sibling.\n\n</workflow>\n\n<guardrails>\n\n## Guardrails\n\n- **No duplication across skills.** A rule lives in exactly one file; sibling skills link to it.\n- **No folklore.** Every rule has a one-line justification (perf, runtime introspection, OpenAPI alignment, etc.). Delete rules you cannot justify.\n- **Terse and imperative.** Bullets are ≤ 2 sentences. If a topic needs more, split it into its own reference file.\n- **Examples are minimal and copy-pasteable.** No pseudo-code; no multi-hundred-line fixtures.\n\n</guardrails>\n\n<validation>\n\n## Validation Checkpoint\n\n- [ ] Every sibling skill's `## Shared Styleguide Baseline` section resolves to files that exist under `references/`\n- [ ] No rule is duplicated between two reference files (check via grep when editing)\n- [ ] Each \"never do X\" rule has a one-line `Reason:` explanation\n- [ ] New language support lands as a single new `references/<lang>.md` — not scattered into sibling skills\n\n</validation>\n\n<example>\n\n## Example — adding a new rule\n\nA reviewer finds that two sibling skills independently wrote \"use `ruff format` not `black`\". Instead of leaving duplicates, pull the rule into `references/python.md`:\n\n```markdown\n- **Use `ruff format`, never `black`.** Reason: ruff is the single toolchain for\n  lint + format; running two formatters produces style drift.\n```\n\nThen in each sibling's `SKILL.md`, replace the duplicate with a pointer:\n\n```markdown\n## Shared Styleguide Baseline\n\n- [Python](../litestar-styleguide/references/python.md)\n```\n\n</example>\n\n## Official References\n\n- <https://peps.python.org/pep-0604/> — PEP 604 union syntax\n- <https://docs.astral.sh/ruff/> — ruff linter / formatter\n- <https://microsoft.github.io/pyright/> — pyright type checker\n- <https://docs.pytest.org/> — pytest","tags":["litestar","styleguide","skills","litestar-org","advanced-alchemy","agent-skills","agentskills","ai-agents","claude-code-plugin","claude-code-skills","gemini-cli-extension","htmx"],"capabilities":["skill","source-litestar-org","skill-litestar-styleguide","topic-advanced-alchemy","topic-agent-skills","topic-agentskills","topic-ai-agents","topic-claude-code-plugin","topic-claude-code-skills","topic-gemini-cli-extension","topic-htmx","topic-inertia","topic-litestar","topic-mcp","topic-python"],"categories":["litestar-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/litestar-org/litestar-skills/litestar-styleguide","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add litestar-org/litestar-skills","source_repo":"https://github.com/litestar-org/litestar-skills","install_from":"skills.sh"}},"qualityScore":"0.453","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 7 github stars · SKILL.md body (5,024 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:13:54.841Z","embedding":null,"createdAt":"2026-05-18T13:20:58.786Z","updatedAt":"2026-05-18T19:13:54.841Z","lastSeenAt":"2026-05-18T19:13:54.841Z","tsv":"'/litestar-styleguide/references/python.md':686 '/pep-0604/':691 '/pyright/':704 '/ruff/':698 '/skill.md':424 '1':415 '2':425,532 '3':442 '4':475 '604':20,67,148,693 'across':303,492 'action':190 'ad':444,621 'add':325 'align':396,520 'alreadi':434 'amplifi':485 'appli':226 'ask':450 'async':22,69 'author':6,355 'authorit':364 'baselin':49,111,161,208,260,281,314,414,431,571,684 'becom':301 'belong':292 'bidirect':479 'black':346,638,653 'bottom':212 'build':192 'bullet':530 'cach':193 'cannot':525 'check':588 'checker':707 'checkpoint':564 'choic':374 'ci/cd':31,77,187 'clever':134 'code':109,267,410,556 'code-styl':108 'configur':155 'consum':197,412 'content':11 'contenti':302 'convent':29,78,146,170,180,188,284 'copi':403,551 'copy-past':402,550 'cover':103 'coverag':184 'cross':63,129,477 'cross-cut':62 'cross-languag':128 'cross-link':476 'cut':64 'delet':522 'di':164 'docs.astral.sh':697 'docs.astral.sh/ruff/':696 'docs.pytest.org':708 'docstr':25,150 'dri':139 'drift':668 'dry-when-it-pay':138 'dtos':163 'duplic':279,491,583,642,677 'e.g':342 'edit':422,592 'error':135 'etc':324,397,521 'everi':51,199,381,508,565 'exact':81,498 'exampl':13,15,235,400,546,620 'exist':59,577 'explan':604 'extend':258 'file':75,119,316,465,500,545,575,587 'find':627 'fixtur':183,562 'flake8':345 'focus':88 'folklor':399,507 'format':636,651,662 'formatt':665,701 'framework':36,91,124,232,457 'framework-specif':35,456 'frontend':175 'general.md':239,245,251 'generic':286,453,459 'github':189 'googl':24 'grep':590 'guard':162 'guardrail':272,489 'guidanc':39 'handl':136 'hedg':366 'hint':288 'hundr':560 'i/o':23,70 'imper':363,529 'implement':38 'import':151,290 'independ':632 'individu':85 'inherit':353 'instead':639 'introspect':394,518 'justif':515 'justifi':526 'keep':360,470 'land':321,460,608 'languag':123,130,231,320,606 'language/tooling':454 'leav':641 'line':379,390,514,561,602 'link':115,215,237,243,249,331,478,503 'lint':661 'linter':700 'list':435 'litestar':2,9,42,159 'litestar-specif':158 'litestar-styleguid':1,41 'litestar.md':241,247,254 'live':79,496 'look':426 'markdown':648,681 'matrix':191 'md':329,614 'microsoft.github.io':703 'microsoft.github.io/pyright/':702 'might':368 'minim':406,548 'mix':125,233 'mojo':323 'multi':559 'multi-hundred-lin':558 'mypi':72,153 'name':76,137,289 'near':210 'need':537 'never':382,594,652 'new':319,327,605,612,623 'offici':687 'one':82,104,224,378,389,499,513,601 'one-lin':377,388,512,600 'open':416 'openapi':395,519 'pair':172 'pasteabl':404,552 'pay':142 'pep':19,66,147,692 'peps.python.org':690 'peps.python.org/pep-0604/':689 'perf':392,516 'place':83 'plugin':56,165,203 'pointer':680 'prefer':373 'principl':131 'produc':666 'pseudo':409,555 'pseudo-cod':408,554 'pull':309,643 'pyright':73,154,705 'pytest':28,181,709 'python':12,145,685 'python.md':240,253,348 'quick':270 'reason':380,603,654 'refer':57,102,221,271,315,328,361,440,467,544,579,586,613,688 'references/ci-cd.md':185,186 'references/general.md':126,127 'references/litestar.md':156,157 'references/python.md':143,144,647 'references/testing.md':177,178 'references/typescript.md':167,168 'relev':120 'replac':344,675 'resolv':573 'review':8,626 'right':313,464 'ruff':71,152,343,635,650,655,699 'ruff/mypy/pyright':26 'rule':18,32,65,269,300,356,385,446,482,495,509,523,581,597,624,645 'run':663 'runtim':393,517 'rust':322 'scatter':616 'section':209,214,432,572 'sentenc':533 'share':16,47,206,429,569,682 'sibl':113,195,256,307,351,418,449,474,488,501,566,618,630,672 'simplic':132 'singl':611,658 'skill':10,53,86,114,176,196,229,257,298,308,333,352,359,419,423,493,502,567,619,631 'skill-litestar-styleguide' 'skill.md':200,674 'skills/litestar-testing/skill.md':248 'skills/litestar-vite/skill.md':242 'skills/litestar/skill.md':236 'slice':105 'source-litestar-org' 'specif':37,95,160,266,458,469 'split':539 'state':371 'stay':87 'style':17,48,110,268,667 'styleguid':3,43,207,430,570,683 'subset':218,437 'support':607 'surfac':96 'swap':340 'syntax':695 'ters':362,527 'test':74,179 'testing.md':252 'tool':27,94,265,338 'tool-specif':93,264 'toolchain':659 'topic':536 'topic-advanced-alchemy' 'topic-agent-skills' 'topic-agentskills' 'topic-ai-agents' 'topic-claude-code-plugin' 'topic-claude-code-skills' 'topic-gemini-cli-extension' 'topic-htmx' 'topic-inertia' 'topic-litestar' 'topic-mcp' 'topic-python' 'two':304,585,629,664 'type':287,706 'typescript':14,169 'typescript.md':246 'union':21,68,149,694 'updat':296,347 'use':4,40,166,335,634,649 'valid':274,563 'via':589 'vitest':182 'want':369 'workflow':411 'wrote':633 'x':384,596","prices":[{"id":"f331b501-49ae-43c6-be64-ad61ad46684f","listingId":"f7a25287-a719-40c5-9bce-4e52e6faa2e7","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"litestar-org","category":"litestar-skills","install_from":"skills.sh"},"createdAt":"2026-05-18T13:20:58.786Z"}],"sources":[{"listingId":"f7a25287-a719-40c5-9bce-4e52e6faa2e7","source":"github","sourceId":"litestar-org/litestar-skills/litestar-styleguide","sourceUrl":"https://github.com/litestar-org/litestar-skills/tree/main/skills/litestar-styleguide","isPrimary":false,"firstSeenAt":"2026-05-18T13:20:58.786Z","lastSeenAt":"2026-05-18T19:13:54.841Z"}],"details":{"listingId":"f7a25287-a719-40c5-9bce-4e52e6faa2e7","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"litestar-org","slug":"litestar-styleguide","github":{"repo":"litestar-org/litestar-skills","stars":7,"topics":["advanced-alchemy","agent-skills","agentskills","ai-agents","claude-code-plugin","claude-code-skills","gemini-cli-extension","htmx","inertia","litestar","mcp","python","sqlspec"],"license":"mit","html_url":"https://github.com/litestar-org/litestar-skills","pushed_at":"2026-05-13T16:04:09Z","description":"Opinionated first-party agent skills, plugins, subagents, slash commands, and MCP servers for the Litestar framework ecosystem — publishable to Claude Code, Gemini CLI, Codex CLI, Cursor, OpenCode, and VS Code/Copilot from a single repo.","skill_md_sha":"4464166086a58058695aeb6947e03af2d354d8ad","skill_md_path":"skills/litestar-styleguide/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/litestar-org/litestar-skills/tree/main/skills/litestar-styleguide"},"layout":"multi","source":"github","category":"litestar-skills","frontmatter":{"name":"litestar-styleguide","description":"Use when authoring or reviewing Litestar skill content, Python examples, TypeScript examples, shared style rules, PEP 604 unions, async I/O, Google docstrings, ruff/mypy/pyright tooling, pytest conventions, or CI/CD rules. Not for framework-specific implementation guidance - use the individual focused skill."},"skills_sh_url":"https://skills.sh/litestar-org/litestar-skills/litestar-styleguide"},"updatedAt":"2026-05-18T19:13:54.841Z"}}