One skill is a package of instructions and tools that changes Claude Code's behavior for a specific task. Instead of explaining the same process every day ("before coding, write a test"), you package that logic into a skill, and the agent loads it when needed.

Technically, a skill is a directory with a file SKILL.md (YAML frontmatter + Markdown body) that describes when to activate e how to act. It can include slash commands, sub-agents, hooks, and references to other skills.

# Minimum SKILL.md structure
---
name: grill-me
description: Stress-tests a plan before coding.
  Use when the user says "I'm going to start implementing",
  "I have an idea", "does it make sense to do it this way?".
---

# Grill Me

You're a skeptical senior. Before accepting any plan:

1. List 5 assumptions implicit in the user's request.
2. For each one, ask "what if this is wrong?".
3. Suggest the cheapest experiment to validate each one.
4. Only then return the refined plan.

The most costly problem isn’t incorrect code—it’s code right about the wrong thing. The user asks for X but wants Y, the agent implements X perfectly, and two weeks later the feature gets thrown away.

When agent and human don't share vocabulary, every conversation has to be explained from scratch. Eric Evans (author of Domain-Driven Design) calls this the absence of ubiquitous language: terms the whole team—humans and agents—uses consistently.

A concrete example. Imagine a course where “lesson” can be a placeholder OR a real instance materialized with a student and progress. Without ubiquitous language, you write it like this:

LLMs are trained to produce code that seems right. Types match, imports exist, syntax is valid — and yet the logic is wrong. Without an external signal (tests), the agent believes its own output.

The classic solution is TDD (Test-Driven Development): write the test first, watch it fail (red), implement the minimum to make it pass (green), then refactor. Skills like /tdd imposes this cycle on the agent.

Code rots. Foote and Yoder documented this in 1997 with the term "Big Ball of Mud": systems that grow without coherent architecture because each feature was rushed in, without refactoring. With agents, the pace increases—and so does the decay.

The wrong intuition: "I’ll ask the agent to refactor everything now." The right intuition: refactor as an opportunity, not an event. You don’t rewrite the system; you identify a duplication and unify it when you already need to work in that area.

Individual skills already help. But the real gains appear when they compose into workflows — each one solves a problem, and one’s output feeds the next.

Typical workflow for a feature, from scratch to production code:

   /grill-with-docs        Stress-testa a ideia contra docs e ADRs
          │              (elimina desalinhamento, problema #1)
          ▼
   /to-prd                 Vira documento de produto curto e cravado
          │              (fixa linguagem ubiqua, problema #2)
          ▼
   /to-issues              Quebra o PRD em issues pequenas e testaveis
          │              (escopo pequeno = menos ball of mud)
          ▼
   /tdd                    Para cada issue: teste vermelho -> verde -> refactor
          │              (resolve problema #3)
          ▼
   /triage                 Revisa diff, sugere refator pontual antes do merge
                         (combate problema #4, deepening opportunity)

Each arrow is a deliberate transition. You don’t have to hold the entire context in your head—the skills handle the handoff. The PRD becomes input for the /to-issues; the issue becomes input for the /tdd; the diff becomes input for the /triage.