How Claude Skills Replaced Our Documentation

A developer explains how replacing traditional documentation with Claude 'skills' — structured markdown instruction files in `.claude/skills/` — solves the problem of AI coding assistants producing code that doesn't match codebase-specific patterns. Skills encode exact patterns, anti-patterns, and reasoning for stack-specific conventions (Elysia routes, Drizzle ORM, Inngest jobs), ensuring Claude follows the actual architecture rather than guessing. The post covers why this outperforms human-facing docs (AI always reads them), how MCP servers complement skills for external service setup, and practical advice on writing effective skills including concrete examples, anti-pattern lists, and iterative refinement. Limitations are acknowledged: skills need maintenance, don't replace architectural thinking, and code review remains essential.