Claude Code Skills: teaching the AI assistant the house rules
AI coding assistants are powerful and opinionless: out of the box they'll produce monolithic files, skipped error paths, and whatever style the prompt implies. Claude Code Skills is my library of skills for Claude Code — markdown rule sets with reference docs, worked examples, and executable scripts — that load automatically when relevant work begins, so a session on a FastAPI route or a Kubernetes manifest starts from production standards instead of averages. This portfolio is built under them.
- Type
- Developer tooling · AI workflow
- Stack
- Claude Code · Markdown skills · Python & shell scripts
- Form
- Skills library · skills guide · skill-creator
- Goal
- Production standards enforced in AI-assisted work
The problem: an assistant without context regresses to the mean
An AI assistant with no context produces average code — average file structure, average error handling, average naming — because average is what it learned from. Teams that adopt these tools without encoding their standards spend the saved time in review, catching the same avoidable mistakes on every pull request: a 400-line component with the types, constants, API calls and JSX in one file; a route handler with no failure path; `any` wherever the shape was unclear.
Prompting harder in the moment doesn't fix it, because the fix evaporates when the session ends. The standards have to be packaged once, in a form the assistant reads at the right moment without being asked. Claude Code's skills system is that form, and this project is what happens when you take it seriously.
What a skill is, and why the description is the whole game
A skill is a directory with a SKILL.md at its root: frontmatter that names it and describes when it applies, then the instructions. Around it sit supporting files the assistant loads on demand — references for detail, examples for shape — and scripts it executes rather than reads. The assistant decides whether to load a skill by matching the task against the description, which makes the description the most important sentence in the repository: too narrow and the skill never fires, too broad and it fires on everything.
So the descriptions here are written as triggers, not summaries. The code-quality skill says it must be loaded whenever a .ts, .tsx, .py, .jsx or .js file is being written, edited, reviewed or created, and lists the phrasings that should wake it — “create a component”, “add an endpoint”, “refactor”, “clean up”. The Docker skill fires on any Dockerfile, compose file or .dockerignore being touched. Reading one is not optional for the assistant; that is the point.
The library
The skills cover the stack I actually ship: code-quality (file organisation, arrow functions with explicit return types, no `any`, pre-write and post-write checklists, with TypeScript, Python and security references); Next.js App Router; FastAPI; Python; Docker; Kubernetes; Spring Boot; PostgreSQL on Neon; the OpenAI Agents SDK; FastMCP; frontend design and UI/UX engineering; a design-to-code skill with Shadcn mappings; GitHub repository SEO; an interview-ready README rewriter; and an open-source contribution workflow. A set of n8n skills is third-party, vendored with their licences, because good work already existed and rewriting it would have been ego.
The one I find most interesting is a meta-skill: a knowledge router that decides, for a technical question, whether to use a curated skill, query live documentation through a Context7 MCP server, or layer both — pattern requests (“how do I add auth to FastAPI?”) go to the skill, lookup requests (“what parameters does HTTPException accept?”) go to the docs, and version-specific or error-message queries go to whichever is authoritative. Curated opinions and current facts are different things, and the router keeps them from being confused.
Scripts that run instead of being read
Not every rule should be prose. The Next.js App Router skill ships a shell validator that checks a project's structure — that an app directory exists, that the root layout renders html and body, that every page has a default export, that “use client” sits where it belongs — and reports errors and warnings in colour. The assistant runs it; it doesn't reason about it. A deterministic check is cheaper and more reliable than asking a language model to eyeball the same thing.
The same principle puts working examples next to the instructions: a multi-stage Dockerfile for a Node app and another for FastAPI, a full-stack compose file, Kubernetes manifests for a web deployment, an API deployment, a stateful database and a stateful cache, a Spring Boot concurrency proof test, a multi-agent triage example for the Agents SDK. An example is a rule with all its ambiguity removed.
The guide, and a skill that writes skills
Alongside the library sits a complete guide to the skills system itself — directory structure, where skills live and which scope wins, the full frontmatter reference, dynamic substitutions like arguments and inline shell execution, invocation control (user-only, agent-only, both), allowed-tool patterns, forked subagent context, hooks scoped to a skill's lifecycle, and plugin packaging. It collects in one file the answers that were scattered across documentation and release notes.
And there's a skill for making skills: draft it, write test prompts, run the assistant with and without it, evaluate the outputs qualitatively and against quantitative checks, then iterate. Treating a skill as something you evaluate rather than something you write once is what separates a rule set that shapes behaviour from a wiki nobody reads.
What it changed, honestly
This portfolio — its data-driven case studies, schema, sitemap and llms.txt — is developed under these skills, and the difference is visible in the shape of the code rather than in any metric I can quote: files split by responsibility, arrow functions with explicit return types, explanatory comments that state why, no `any`. I don't have a controlled measurement of review time saved, and I'm not going to invent one.
The limits are real. Skills are only as current as their last edit, and a framework release can make a rule wrong overnight — which is exactly why the knowledge router exists. A skill that fires too eagerly costs context on every session, so tuning descriptions is ongoing work, not finished work. The repository is public and written in Markdown, Python and shell, because tooling that shapes an assistant should be readable by the humans it's shaping for.