TL;DR: Add a PITFALLS.md next to every SKILL.md so your AI never repeats the same mistake twice.
Common Mistake ❌
You write a great SKILL.md.
The AI follows it well most of the time.
Then it does something wrong.
You correct it in the conversation.
Next session, the AI does the same wrong thing again.
You never wrote it down.
Problems Addressed 😔
Hard-won corrections disappear when the session ends
Your SKILL.md grows noisy when you add every edge case to it
The AI repeats the same mistakes across sessions
Silent errors look correct until they cause real damage
You spend time re-teaching lessons you already taught
How to Do It 🛠️
Create a PITFALLS.md file in the same folder as your SKILL.md.
After each session, add one entry for each thing the AI got wrong.
Write each entry with three parts: the trigger, the wrong behavior, and the correct behavior.
Reference PITFALLS.md from your SKILL.md so the AI reads it at the start of every session.
Treat it as append-only: never delete entries, only add new ones.
Keep the happy path and the pitfalls apart.
Benefits 🎯
Clean separation: Your SKILL.md stays focused on the happy path while PITFALLS.md handles the exceptions.
Accumulated memory: The AI starts every session knowing what failed before, without you repeating it.
Faster iteration: You stop re-explaining corrections you've already made.
Explicit dark knowledge: You write down lessons that lived only in your head.
Compounding improvement: Your skills get better with every mistake the AI makes, not worse.
Skill brevity: You keep the skill short and focused, with progressive disclosure loading pitfalls only as a final checklist.
Context 🧠
SKILL.md tells the AI what to do.
PITFALLS.md tells the AI what not to do.
They're complementary, not competing.
Anthropic's own skill authors describe the pitfalls section as "the highest-signal content in any skill."
When that section grows too large to stay inside SKILL.md, it earns its own file.
Think of PITFALLS.md as the scar tissue that lives next to the blueprint.
The same way you initialize an AGENTS.md for a project, you pair every skill with its failure log.
When you use modular skills, each skill gets its own folder.
That folder is the right place for PITFALLS.md.
Remember a Skill is a folder with documentation and scripts, not a single file.
The same instinct drives feeding pull request lessons back into the AI brain: you capture what went wrong so the AI doesn't repeat it.
PITFALLS.md applies that exact pattern to individual skills.
Each skill builds its own second brain of failure memory.
This principle has a long history in good programming practices.
The same separation principle applies to code: keep your normal flow in one place and your exceptional cases in another.
Mixing them creates noise, hides intent, and makes maintenance harder.
SKILL.md and PITFALLS.md apply that discipline to AI instructions.
Many AI Coding Tips find their roots in established programming principles.
When you separate concerns in your code, you separate them in your prompts too.
Prompt Reference 📝
Bad Prompt 🚫
Write a SKILL.md for validating markdown articles.
Check for required sections and formatting rules.
If something's wrong, we'll fix it in the chat.
Good Prompt 👉
Write a SKILL.md for validating markdown articles.
Check for required sections and formatting rules.
Also create a PITFALLS.md in the same folder.
Add this first entry:
## Don't use regex to count H2 sections
Trigger: counting sections by heading level
Wrong: regex-based heading detection (/^##/m)
Correct: match section names explicitly by string
Reason: code blocks with # fool regex heading counters
Reference PITFALLS.md at the top of your SKILL.md.
The AI loads it at the start of every session.
Considerations ⚠️
Keep each entry short: trigger, wrong behavior, correct behavior.
Don't delete entries.
Even solved pitfalls can come back after a skill update.
Review PITFALLS.md when you update SKILL.md to check if any entries became obsolete.
Type 📝
[X] Semi-Automatic
Limitations ⚠️
PITFALLS.md only helps if the AI reads it.
Always reference it explicitly inside your SKILL.md so the AI loads it automatically.
Level 🔋
[X] Intermediate
https://maximilianocontieri.com/ai-coding-tip-004-use-modular-skills
https://maximilianocontieri.com/ai-coding-tip-005-keep-context-fresh
https://maximilianocontieri.com/ai-coding-tip-011-initialize-agents-md
https://maximilianocontieri.com/ai-coding-tip-013-use-progressive-disclosure
https://maximilianocontieri.com/ai-coding-tip-016-feed-your-pr-lessons-into-the-ai-brain
https://maximilianocontieri.com/ai-coding-tip-020-create-a-second-brain
https://maximilianocontieri.com/ai-coding-tip-024-force-a-criteria-check-before-the-task-ends
Conclusion 🏁
Your SKILL.md is the blueprint.
Your PITFALLS.md is the scar tissue.
You need both.
Lessons from building Claude Code: How we use skills
Designing, Refining, and Maintaining Agent Skills at Perplexity
Code Smell 73 - Exceptions for Expected Cases
Also Known As 🎭
- Negative-Knowledge-File
- Skill-Shadow-File
- Failure-Memory-Companion
- Anti-Pattern-Log
Disclaimer 📢
The views expressed here are my own.
I am a human who writes as best as possible for other humans.
I use AI proofreading tools to improve some texts.
I welcome constructive criticism and dialogue.
I shape these insights through 30 years in the software industry, 25 years of teaching, and writing over 500 articles and a book.
This article is part of the AI Coding Tip series.
https://maximilianocontieri.com/ai-coding-tips
