lang-guidelines

Three language-specific Agent Skills that put design guidelines, idiomatic patterns and lint rules in front of an AI agent while it writes or edits code — not only during review.

• rust-guidelines/ — Microsoft's Pragmatic Rust Guidelines + Rust API Guidelines + Google Rust Style Guide (design) + rust-unofficial patterns. Mechanical checks are left to rustc + clippy.
• python-guidelines/ — Google Python Style Guide (design) + python-patterns.guide by Brandon Rhodes (patterns), with Ruff enforcing the tiered lint rules through a bundled ruff.toml.
• typescript-guidelines/ — Google TypeScript Style Guide (design) + Systemic TypeScript (Vincent Alandev), with Oxlint enforcing the tiered lint rules through a bundled oxlintrc.jsonc.

Each skill is a self-contained folder following the open Agent Skills standard. Works unchanged with Claude Code, Codex, Gemini CLI, Cursor, VS Code, GitHub Copilot, OpenCode, OpenHands, Goose, and 30+ other agents.

What a skill gives the agent

Each skill packages three conceptual layers of knowledge, from the most mechanical to the most architectural. An agent that loads the skill writes code informed by all three layers at once.

flowchart LR
    L1[<b>LINT</b><br/>mechanical correctness + security<br/><i>the things a linter or<br/>compiler can mechanically check</i>]
    L2[<b>DESIGN</b><br/>architectural decisions<br/>the compiler cannot make<br/><i>module boundaries, API shape,<br/>error philosophy, docs, crates</i>]
    L3[<b>PATTERNS</b><br/>reusable solutions to<br/>recurring design problems<br/><i>strategy, visitor, newtype,<br/>RAII guards, typestate…</i>]

    L1 --> L2 --> L3

    style L1 fill:#bf8700,stroke:#9a6700,color:#fff
    style L2 fill:#8250df,stroke:#5a1fb0,color:#fff
    style L3 fill:#1a7f37,stroke:#116329,color:#fff

The layers are cumulative: fixing every lint violation does not produce good code — it produces mechanically-correct code. Good code requires the layers above.

Install

Recommended — skills CLI (skills.sh)

The open-ecosystem CLI from Vercel Labs supports 45+ agents (Claude Code, Codex, Cursor, Gemini, OpenCode, Copilot, Goose, Windsurf, Amp, Kiro, Factory Droid, Roo, Cline, …). One command per project or global:

# Install all three skills globally (symlinked, easy updates)
npx skills add youssef-tharwat/lang-guidelines --all -g

# Or install just one
npx skills add youssef-tharwat/lang-guidelines --skill python-guidelines -g

# Or scope to a single project
cd my-project
npx skills add youssef-tharwat/lang-guidelines --all

# Target specific agents
npx skills add youssef-tharwat/lang-guidelines --all -a claude-code -a cursor

Browse the live leaderboard at https://skills.sh/ or search for the repo at skills.sh/youssef-tharwat/lang-guidelines once install telemetry accumulates.

Manual — git clone + symlinks

For agents not yet supported by the CLI, or for custom install locations:

git clone https://github.com/youssef-tharwat/lang-guidelines ~/src/lang-guidelines

# Claude Code
ln -s ~/src/lang-guidelines/rust-guidelines       ~/.claude/skills/rust-guidelines
ln -s ~/src/lang-guidelines/python-guidelines     ~/.claude/skills/python-guidelines
ln -s ~/src/lang-guidelines/typescript-guidelines ~/.claude/skills/typescript-guidelines

# Gemini CLI (~/.gemini/skills/), Codex, OpenCode, … — same pattern, different target dir.
# See per-agent docs at https://agentskills.io/home.

Direct copy (any agent)

cp -R rust-guidelines       <agent-skills-dir>/
cp -R python-guidelines     <agent-skills-dir>/
cp -R typescript-guidelines <agent-skills-dir>/

What's inside

Each SKILL.md body is a rule card: one line per design rule, grouped by the decision being made, with conflicts between upstream sources already resolved. That card is all an agent reads up front. The full upstream text, examples and lint documentation stay on disk until a task needs them.

What the agent sees at trigger time

Skill	Always loaded	On demand	Framework-gated
rust-guidelines	SKILL.md (28 KB: 92-rule card + 6-pattern index)	cards/{setup,ffi,performance}.md (19 rules, opened by trigger) · rules/<id>.md · patterns/<id>.md · lints.toml	—
python-guidelines	SKILL.md (15 KB: 39-rule card + 15-pattern index)	rules/<id>.md · patterns/<id>.md · ruff.toml · lint/<rule>/index.md · style.md (275 Tier 3 rules)	frameworks/{airflow,django,fastapi,numpy,pandas}.md
typescript-guidelines	SKILL.md (17 KB: 45-rule card + 7-pattern index)	rules/<id>.md · patterns/<id>.md · oxlintrc.jsonc · lint/<plugin>/<rule>/index.md · style.md (280 Tier 3 rules)	frameworks/{jest,jsdoc,nextjs,react,vitest,vue}.md

Python and TypeScript keep their Tier 1 (correctness, security) and Tier 2 (modernization, performance) lint rules out of the card: the bundled ruff.toml and oxlintrc.jsonc select them, so the linter enforces them mechanically, as rustc and clippy do for Rust.

Measured

Each restructure was A/B-tested against the always-load layout it replaced, on a fixed suite of coding tasks. The protocols and per-case results are in evals/<skill>/results/.

This is the beginning of the README. Read the rest at the original. Read the full README ↗