Immutable. This exact content is served forever at /api/v1/blob/03282acbf4cebd59.
# `litestar-skills` Agent Context This file is loaded by every AI agent CLI that consumes this repo: Claude Code, Gemini CLI, Codex CLI, Cursor, OpenCode, VS Code/Copilot, and others supporting the [agentskills.io](https://agentskills.io) standard. ## Mission `litestar-skills` is a curated, opinionated collection of agent skills, plugins, subagents, slash commands, and MCP servers for the **Litestar** framework and its first-party ecosystem. Agents working in this repo are authoring or maintaining content that will be consumed by other agents to guide Litestar application development. Style baseline for every skill here: [`skills/litestar-styleguide/`](skills/litestar-styleguide/SKILL.md). ## Agent Conduct - **Terse, imperative, authoritative tone.** No hedging. State the preferred choice. - **Litestar-first-party bias.** Prefer `litestar-granian`, `litestar-saq`, `sqlspec`, `advanced-alchemy`, `msgspec` over generic alternatives in examples and recommendations. - **Minimal targeted changes.** Do not make opportunistic cleanup edits without approval. - **Canonical commands via Make.** Always prefer `make <target>` over raw tool invocations. See [Development Commands](#development-commands). - **Never silently descope.** If a task is larger than expected, refine the plan or ask how to prioritize. - **No blame language.** Describe problems factually; offer the smallest useful next step. ## Skill Authoring Rules Every `SKILL.md` MUST follow these conventions: 1. **YAML frontmatter** with `name` (kebab-case, matches directory) and `description` (starts with auto-activation signal, ends with `Not for X — why`). 2. **XML-tagged sections** in this order: Code Style Rules → Quick Reference → `<workflow>` → `<guardrails>` → `<validation>` → `<example>` → References Index → Official References → Shared Styleguide Baseline. 3. **Match-your-stack**: when multiple valid libraries / backends / patterns exist for a concern (data access, DI, background tasks, Channels backend, settings, serialization, deployment target), present all options and help the user pick based on what's already in their project. Never force one path. 4. **Litestar code-sample conventions** (full detail in [`skills/litestar-styleguide/`](skills/litestar-styleguide/SKILL.md)): - PEP 604 unions (`T | None`), never `Optional[T]` - `from __future__ import annotations` is a library-author guardrail, not a consumer rule — application code MAY use it; library code that defines runtime-introspected types avoids it - Google-style docstrings, async all I/O - `msgspec` over Pydantic in Litestar contexts (unless the project already uses Pydantic) - `advanced-alchemy` / `sqlspec` over raw SQLAlchemy (match the project's chosen stack) ## Supported Hosts Every host falls into one of three tiers: - **First-class** — the repo ships maintained host-specific manifests, agents, and install guidance; changes to the shared skills tree are verified against the host. - **Compatible bundle** — the host consumes the repo through standard manifests or generic skill-discovery paths; no native wrapper is promised. - **Free ride** — the host discovers generic Agent Skills / `AGENTS.md` content; the repo ships no dedicated integration. | Host | Tier | Entry Point | Notes | | --- | --- | --- | --- | | **Claude Code** | first-class | `.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json` + `.claude-plugin/agents/*.md` | Full plugin with skills, commands, agents, hooks. | | **Gemini CLI** | first-class | `gemini-extension.json` + `agents/*.md`, context via `GEMINI.md` | Auto-indexed gallery (topic `gemini-cli-extension`). | | **Codex CLI** | first-class | `.codex-plugin/plugin.json` + `.codex/agents/*.toml` + `.codex/config.toml` | Custom agents ship as pure TOML (tools inherited from session). | | **OpenCode** | first-class | `.opencode/plugins/litestar-skills.js` + `.opencode/agents/*.md` + native `.claude/skills/` / `.agents/skills/` reads | JS plugin wrapper + dict-schema agents. | | **Cursor** | compatible bundle | `.cursor-plugin/plugin.json` | Hooks via `hooks/hooks-cursor.json`. | | **VS Code / Copilot** | compatible bundle | User adds path to `chat.skillsLocations` | Raw SKILL.md tree (no wrapper extension in v0.1). | | **Google Antigravity** | free ride | `.agent/skills/` (workspace, note **singular**) or `~/.gemini/antigravity/skills/` (global) | Symlink `.agent → .agents` in your workspace; see README install. | | **OpenClaw** | compatible bundle | `.agents/skills/` + `AGENTS.md` | Consumes generic Agent Skills tree without extra config. | ## File Resolution | Resource | Location | | --- | --- | | Skills | `skills/<skill-name>/SKILL.md` | | Slash commands | `commands/<prefix>/<command>.toml` | | Subagents (Claude Code) | `.claude-plugin/agents/<agent-name>.md` (`tools` as comma-separated string of Claude tool names) | | Subagents (Codex CLI) | `.codex/agents/<agent-name>.toml` (pure TOML; `developer_instructions` holds the prompt; no top-level `tools` — inherited from session `config.toml`) | | Subagents (Gemini CLI) | `agents/<agent-name>.md` (`tools` as YAML list of Gemini tool names) | | Subagents (OpenCode) | `.opencode/agents/<agent-name>.md` (`tools` as dict mapping + `mode: subagent`) | | MCP servers | `mcp-servers/<server-name>/` | | Hooks | `hooks/*.json` + `hooks/session-start` | | Templates | `templates/skill-template/` | ## Development Commands Always run via `make` — never invoke underlying tools directly in documentation. ```bash make install # uv sync + bun install + prek install make lint # ruff + oxlint + markdownlint make typecheck # mypy + pyright make test # pytest + bun test make validate-skills # frontmatter + link + skills-ref validation make check # lint + typecheck + test + validate-skills (CI parity) make release bump=patch # atomic bump of all 8 manifests via bump-my-version ``` ## External Integrations Optional, opt-in only. No manifests shipped — users add them per host. - **Google Developer Knowledge MCP** — fresh Firebase / Google Cloud / Android / Maps docs. See [`skills/litestar-styleguide/references/google-developer-knowledge-mcp.md`](skills/litestar-styleguide/references/google-developer-knowledge-mcp.md) for auth, install one-liners, and the Codex/OpenCode gap note. ## Version Sync Rule Any file with a `version` string is listed under `[[tool.bumpversion.files]]` in `pyproject.toml`. Adding a new manifest requires adding it to bumpversion in the **same commit**.