🧩 Understand What a Skill Is
A skill is a reusable capability that guides the agent through a specific task: analyzing a repository, generating a specification, creating a plan, reproducing a bug, generating tests, reviewing architecture, reviewing security, updating documentation, preparing a pull request, modernizing a legacy module, analyzing an incident, validating a deploy.
How to read: the cyan boxes are skills—each one expands what the agent can do well. The dashed line around them represents the rules: they don’t teach anything; they just define where no one can go. Adding a skill without guardrails is like increasing power without brakes.
Capacity
A skill expands
Limit
Rule fences in
Reuse
Less variation
One task
By skill
🧱 Structure a Skill
Ten fields are enough. The two that most distinguish a useful skill from a saved prompt are "when to use" (helps the agent choose correctly) and "prohibited actions" (prevents harm).
🧪 Copyable exercise — your first skill
Objective: turn a prompt you already repeat into a version-controlled skill. Create skills/<nome>/SKILL.md with this skeleton.
# Skill: <nome curto e verbal, ex.: revisar-api> ## Objetivo <o que esta skill entrega, em uma frase> ## Quando usar <gatilhos concretos: "quando o diff altera arquivos em src/api/"> ## Quando NÃO usar <casos em que outra skill é melhor> ## Entradas - <spec, diff, caminho, log... o que precisa existir antes> ## Ferramentas permitidas - <leitura de arquivos, execução de testes, busca... e nada além> ## Etapas 1. <passo> 2. <passo> 3. <passo> ## Ações proibidas - <não alterar testes, não instalar dependências, não commitar...> ## Tratamento de falhas - <se X falhar, pare e relate; não tente contornar> ## Formato da saída <estrutura exata: tabela, lista com severidade, arquivo:linha...> ## Verificações obrigatórias - <o que rodar antes de declarar pronto, com a saída real anexada>
How to verify: ask someone on the team to use the skill on a real task without you explaining anything. If that person needs to ask a question, turn what was missing into a new field. A good skill works without its author nearby.
When to use
The most important field
Prohibitions
Within the skill itself
Format
Makes composable
Verification
Close the loop
🗂️ Choose Which Skills to Create First
Prioritize by frequency × variation in quality: tasks you repeat often and that produce different results depending on who does them today. A skill for a rare task is maintenance with no return.
✓ Good first skills
- ✓Generate a specification from a task
- ✓Review the PR through a security lens
- ✓Reproduce the bug and write a failing test
- ✓Prepare PR with attached evidence
✗ Skills that don’t pay off
- ✗"Do anything in the repository" (too generic)
- ✗Task that happens once every six months
- ✗A process that still changes every week
- ✗Thirty skills created before using the first one
💡 Practical tip
Start with three to five skills. If you haven’t used one of them in a month, it wasn’t a priority — delete it. A large collection of unused skills has the same problem as dead documentation: it enters the context and gets in the way.
Frequency
First criterion
Variation
Where the biggest gains are
3 a 5
Not thirty
Not used
Delete
📏 Understand what rules are
Rules are permanent or conditional rules that limit agents’ behavior. They apply to every task, regardless of which skill is used. Rules reduce arbitrary decisions.
Starter set — copy and adapt
- never change tests to hide a failure - never add secrets to the repository - don't add dependencies without justification - preserve public APIs - don't deploy without approval - don't modify the production database directly - don't remove security logs - produce test evidence - limit the number of attempts - stop when the cost exceeds the limit - ask for approval before destructive actions - don't refactor outside the scope
Permanent
Applies to every task
Arbitrariness
It’s what the rule cuts off
Clear
One line, no ambiguity
Few
Long lists are ignored
🔐 Write Security and Compatibility Rules
These are the hard rules: the ones that are costly to violate and difficult to reverse. They deserve to be written down—and, whenever possible, turned into automatic gates.
Never change tests to hide a failure
This is the rule that protects the very concept of “done.” Without it, the rest of the course loses its meaning—the verifier stops being reliable.
Never put secrets in the repository
Combine it with the module 3.3 secret detection gate. Rule and check together: one guides, the other prevents.
Preserve public APIs and produce evidence
The public contract doesn't change without versioning. And every delivery comes with the actual test output—evidence is a requirement, not a courtesy.
⚠️ Attention
A rule without verification depends on obedience — and obedience from a probabilistic system is no guarantee. Whenever the rule is critical e automatable, turn it into a gate. The rule still applies as guidance; the gate is what prevents it.
Untouchable test
Protects the “done” state
Secret
Rule + gate
Public API
Contract preserved
Evidence
Obligation
🎚️ Use rules to limit autonomy
Attempt limit, cost cap, approval before destructive actions, no refactoring outside the scope: this is the written, permanent version of the limits you configured in track 2.
🔗 Where each piece lives
- •Rule (text, always valid): "request approval before destructive actions".
- •Harness (configuration): the permission that simply does not exist for the agent.
- •Gate (verification): the pipeline that blocks the change if the rule was violated.
- •The three layers reinforce one another. Relying on just one is a gamble.
Quick check: you wrote the rule "never commit secrets." Is that enough?
Rule
Guides
Harness
Don’t grant permission
Gate
Blocks at output
Three layers
If they strengthen
📌 Module Summary
Next Module:
5.3 - Governance and autonomy levels: who the agent is and how far it goes.