railtracks: Skill for Claude Code

railtracks Code Style

Code changes in this repo should be reviewed against these rules. Each one comes from a recurring, repeated PR review comment on railtracks, not a hypothetical style preference.

• Lint/format: run ruff check --fix and ruff format, required for every PR (CI-enforced).
• Imports: prefer top-level imports. Local/inline imports are fine when there's a real reason (e.g. deferring an expensive or optional dependency like litellm); don't add them out of habit, and don't let a lint failure be the excuse either way.
• Tests: new functionality gets tests in the matching package's tests/ directory; don't leave a behavior change uncovered.
• Docstrings: must match the actual signature (param names, types, | None / Iterable[...] etc.). Update the docstring any time a signature changes.
• Tool docstrings/type hints: for any @rt.function_node-wrapped tool, the docstring is the literal tool description the LLM sees and the type hints define its JSON schema parameters; don't write vague docstrings or omit type hints on a tool function.
• Module-level comment strings: a docstring at the top of a file is welcome. Avoid long inline paragraph-style comments in the body of the code; keep inline comments short and targeted.
• Typing: no bare Any when a concrete type is available or already imported nearby. Don't reach for Any as a quick fix to silence something that's actually broken, either; fix the real type mismatch.
• TODOs: no inline # TODO comments. Either fix it now or file a tracked GitHub issue and reference it.
• Cruft: no dead/commented-out code, no stray debug/scratch files left in a change.
• Documentation paragraphs: keep prose paragraphs on one line, matching the existing docs; do not hard-wrap sentences. Preserve code-block formatting.
• Mutable defaults: don't store a mutable default (x or []) by reference and mutate it later; copy defensively.
• Errors: use repr(e) rather than str(e) in error/log messages.
• __init__.py: don't add docstrings to __init__.py files; not this repo's convention.
• Consistency with siblings: when adding a new variant of something that already has 2+ siblings (chunkers, loaders, LLM providers, etc.), match their existing shape/behavior rather than introducing an ad hoc one-off.
• Model references in examples: use current, provider-documented model IDs in user-facing examples and bundled CLI skills. Verify IDs against the provider's model catalog and deprecation page when adding or refreshing examples. Keep a model-specific reference only when the example demonstrates behavior unique to that model, and explain that choice nearby when it would otherwise look stale. Historical upgrade guides and tests that intentionally exercise model-name passthrough may retain older IDs.