skills

This repository is a collection of reusable skills — small instruction scripts — designed to be installed into AI coding agents like Claude Code or Codex. The problem it addresses is that AI coding agents frequently fail in predictable ways: they misunderstand what you want to build, they produce code that works but has poor architecture, they lack test-driven feedback loops, and they generate verbose output because they lack shared vocabulary with the project. These skills are packaged solutions to each of those failure modes.

Each skill is a short, focused prompt file that teaches the agent a specific disciplined practice. For example, the grill-me skill makes the agent interview you with detailed questions before starting any work, to ensure alignment. The grill-with-docs skill adds shared vocabulary documentation so the agent uses consistent project-specific terminology. The tdd skill enforces red-green-refactor test-driven development where the agent writes a failing test first then makes it pass. The diagnose skill provides a structured debugging loop. The improve-codebase-architecture skill helps identify and refactor overly complex code. You install the skills with a one-liner command using npx and then choose which agents to install them on. The skills work with any model and any coding agent that supports custom instructions or skill plugins. The README explicitly frames these as tools for real engineering rather than vibe coding, referencing software engineering books and principles. You would use this repository when you find your AI coding agent repeatedly making the same kinds of mistakes. The tech stack is Shell scripts plus Markdown for the skill definitions.