Anthropic engineer Thariq called it the “highest-signal content” in any skill. After reviewing hundreds of SKILL.md files submitted to AgentSkillExchange, we agree—but we’d go further. The gotchas section is the single thing that separates skills that work from skills that frustrate everyone who installs them.
This post breaks down what makes a gotchas section effective, shows real examples from production skills, and gives you a repeatable process for building one from scratch. If you’re writing skills for Claude Code or any agent platform, this is the section worth getting right.
What a Gotchas Section Actually Does
Every agent skill starts from the same baseline: whatever the LLM learned during training. Claude knows Python. It knows how REST APIs work. It can read documentation. So what does a skill add?
The answer should be: information the model can’t figure out on its own. And the gotchas section is where that information concentrates most densely.
A gotchas section captures the failure modes that an LLM hits repeatedly when working in a specific domain. These are the gaps between “how things should work according to documentation” and “how things actually work in practice.” Every experienced developer carries this knowledge around in their head. A gotchas section externalizes it into something an agent can use.
Consider what happens without one. Claude reads your SKILL.md, follows the instructions, and runs into a silent API behavior that returns null where the TypeScript types promise a string. It generates code that passes type checking but crashes at runtime. The user debugs, fixes it, and moves on. Next week, a different user hits the same bug. And the week after that. The failure is predictable and preventable—but only if someone wrote it down.
The Anatomy of a Bad Gotchas Section
Most gotchas sections we reject on ASE look something like this:
## Gotchas
- Be careful with API rate limits
- Make sure to handle errors properly
- Don't forget to validate input
- Remember to check authentication before making requests
- Always test in staging firstEvery line here is true. Every line is also useless. Claude already knows all of this. Writing “be careful with API rate limits” is like telling a driver to “be careful on the road”—it’s technically correct advice that changes no one’s behavior.
The problems with this kind of section:
- It’s generic. These gotchas apply to every API in existence. They’re not specific to your skill’s domain.
- It’s vague. “Handle errors properly” doesn’t tell the model how to handle them or which errors to expect.
- It wastes tokens. Every line in your SKILL.md costs context window space. Generic advice consumes tokens without adding decision-making value.
- It builds false confidence. A skill with a gotchas section that says nothing useful is worse than one with no gotchas section at all—at least the absence signals a gap.
What Good Gotchas Look Like
A good gotchas entry has three properties: it’s specific, it’s corrective, and it’s born from an actual failure.
Here’s an example from a Stripe integration skill:
## Gotchas
- The Stripe API returns `null` for `invoice.subscription` on one-time
payments, but the TypeScript types say it's always a string. Always
null-check it regardless of what the types say.
- When creating customers, the `metadata` field silently truncates
values longer than 500 characters. Validate length before sending
or you'll get partial data with no error.
- Webhook signatures use the RAW request body. If you parse JSON first
and re-stringify, the signature verification fails every time.
Use `express.raw()` middleware on the webhook route, not
`express.json()`.Each entry follows the same pattern:
- State the specific behavior — what actually happens, not what should happen
- Explain why it’s a trap — why the “obvious” approach fails
- Give the correct action — what to do instead
This structure maps directly to how LLMs make decisions. When Claude encounters a situation matching the gotcha, it has enough context to deviate from its default behavior. No ambiguity, no interpretation required.
Five Patterns for Finding Gotchas
The hardest part of building a gotchas section isn’t writing it—it’s knowing what to include. These five patterns cover the most common sources of high-value gotchas.
Pattern 1: Silent Failures
APIs and tools that fail without throwing errors are gotcha goldmines. The model does everything “right,” gets a 200 response, and the data is wrong or incomplete.
- The `/users` endpoint returns a 200 with an empty array when the
API key has insufficient permissions, instead of returning a 403.
Check the response headers for `X-Permission-Level` to verify
access before trusting an empty result.Silent failures are especially dangerous for agents because they don’t trigger error-handling paths. The model continues confidently with bad data.
Pattern 2: Documentation Lies
Official docs that are outdated, incomplete, or misleading about actual behavior. Claude was trained on these docs, so it “knows” the wrong thing with high confidence.
- The docs say `pagination.total_count` returns the total number of
records. In practice, it caps at 10,000 regardless of actual count.
For accurate totals, use the `/stats` endpoint instead.Pattern 3: Platform-Specific Behavior
Code that works on macOS but breaks on Linux, or runs fine with Node 18 but fails on Node 20. The model picks a “correct” approach that’s only correct in certain environments.
- `fs.watch()` fires duplicate events on macOS (one for content
change, one for metadata). On Linux it fires once. Use a 100ms
debounce wrapper or switch to `chokidar` for consistent behavior
across platforms.Pattern 4: Ordering and Timing Dependencies
Operations where sequence matters but isn’t obvious. Race conditions, required initialization steps, or API calls that must happen in a specific order.
- You must call `client.connect()` before `client.subscribe()`, even
though `subscribe()` doesn't throw if called first — it silently
drops messages until the connection is established. The fix: await
the 'connected' event before subscribing.Pattern 5: Configuration Traps
Default settings that cause problems, environment variables with unexpected behavior, or config values that interact in non-obvious ways.
- Setting `MAX_RETRIES` above 5 with `RETRY_BACKOFF=exponential`
causes the final retry to wait 32+ seconds, which exceeds the
default Lambda timeout of 30 seconds. Either cap retries at 4
or use `RETRY_BACKOFF=linear`.Building Your Gotchas Section: A Repeatable Process
You don’t need to write a perfect gotchas section on day one. The best ones evolve through a cycle of use, failure, and correction. Here’s a practical process:
Step 1: Seed from Your Own Experience
Think about the last five times you debugged something in this skill’s domain. What was the root cause? If you can remember the problem, it’s probably a gotcha worth documenting.
Start with 3-5 entries. Don’t aim for completeness—aim for the failures that burned the most time.
Step 2: Run the Skill and Watch It Fail
Give Claude a task using your skill. Watch what happens. When it makes a mistake, don’t just fix it—ask yourself: what would it need to know to avoid this mistake next time?
Write that answer as a gotcha entry.
Step 3: Check Issue Trackers and Stack Overflow
For library or API skills, search for common issues in the project’s GitHub issues and Stack Overflow tags. The questions people ask repeatedly are the gotchas your skill should preempt.
A 30-minute search through the top 20 Stack Overflow questions for your tool will surface gotchas that save hours of debugging downstream.
Step 4: Iterate After Real Usage
After your skill has been used for a week, review the results. Which tasks succeeded on the first try? Which required manual correction? Every correction is a potential gotcha.
On AgentSkillExchange, we see skills with actively maintained gotchas sections outperform static ones significantly in user ratings. The skills that improve over time earn user trust.
Step 5: Prune Ruthlessly
Not every failure deserves a gotcha entry. If a bug was caused by a typo or a one-time environment issue, it doesn’t belong. Gotchas should capture systematic failure modes—things that will happen to anyone using the skill, not just the person who discovered them.
Remove entries that haven’t triggered in months. Remove entries about bugs that got fixed upstream. Keep the section lean and relevant.
Structuring Gotchas for LLM Comprehension
How you format your gotchas matters as much as what you include. LLMs process text differently than humans skim it. A few structural principles help:
Lead with the Trigger Condition
Start each gotcha with the situation that triggers it. This helps the model pattern-match against its current task:
## ✅ Good: trigger first
- When deploying to AWS Lambda, the `tmp` directory has a 512MB limit.
Store temporary files in `/tmp` and clean up after each invocation.
## ❌ Bad: buried trigger
- Make sure you clean up temporary files because the directory might
have size limits on some platforms like Lambda.The first version lets Claude match “deploying to AWS Lambda” against the current task. The second version buries the trigger condition in the middle of generic advice.
Use Negative-Positive Pairs
Show what’s wrong and what’s right. The contrast helps the model avoid the bad pattern even in novel situations:
- ❌ `JSON.parse(response.body)` — body is already an object when
using the SDK's built-in parser, so this throws "unexpected token o"
✅ Use `response.body` directly without parsingGroup by Operation
If you have more than 8-10 gotchas, organize them by the operation they relate to. This reduces cognitive load and makes individual entries easier to find:
## Gotchas
### Authentication
- [auth gotcha 1]
- [auth gotcha 2]
### Data Fetching
- [fetch gotcha 1]
- [fetch gotcha 2]
### Deployment
- [deploy gotcha 1]Real-World Examples from the ASE Marketplace
Here are gotchas sections from three popular skills on AgentSkillExchange, showing how different domains produce different kinds of gotchas.
From a WordPress REST API Skill
## Gotchas
- The REST API returns dates in the site's timezone, not UTC, unless
you explicitly pass `?context=edit`. Always use edit context when
comparing timestamps across systems.
- `wp/v2/posts` returns max 100 items per page regardless of the
`per_page` value you send. For bulk operations, implement pagination
with `X-WP-TotalPages` header.
- Featured image uploads via REST require a two-step process: first
upload to `/wp/v2/media`, then update the post's
`featured_media` field. Sending image data directly to the posts
endpoint is silently ignored.From a GitHub Actions Skill
## Gotchas
- `actions/checkout@v4` does a shallow clone by default (depth 1).
Git operations that need history (blame, log, diff against older
commits) will fail. Set `fetch-depth: 0` for full history or a
specific number for partial.
- Environment variables set in one step are NOT available in
subsequent steps. Use `$GITHUB_ENV` to persist:
`echo "VAR=value" >> $GITHUB_ENV`
- Matrix strategy runs are independent — they don't share workspace
files. If one matrix job builds an artifact another needs, use
`actions/upload-artifact` and `actions/download-artifact`.From a Database Migration Skill
## Gotchas
- PostgreSQL advisory locks acquired with `pg_advisory_lock()` are
session-level, not transaction-level. If your migration runner
crashes mid-migration, the lock persists until the connection
drops. Use `pg_advisory_xact_lock()` for transaction-scoped locks.
- Running `ALTER TABLE` on tables with >1M rows in PostgreSQL
acquires an `ACCESS EXCLUSIVE` lock that blocks all reads.
Use `CREATE INDEX CONCURRENTLY` for index additions and
`pg_repack` for column type changes on large tables.
- Sequelize migrations don't run in a transaction by default.
A failing migration leaves your database in a partial state.
Wrap each migration in `queryInterface.sequelize.transaction()`.Notice the pattern across all three: every entry is something you’d only learn by hitting the problem. None of it is in the “getting started” docs. All of it prevents real debugging sessions.
Common Mistakes in Gotchas Sections
Beyond the “too generic” problem covered earlier, these mistakes show up frequently in ASE submissions:
- Gotchas about the skill itself. “Remember to install dependencies before running” is a setup instruction, not a gotcha. Put it in a Setup section.
- Gotchas that are actually feature requests. “This doesn’t handle pagination yet” belongs in a TODO, not in gotchas.
- Stale gotchas. A bug fixed in v2.3 of the library doesn’t need to live in your gotchas forever. Pin gotchas to specific versions if relevant, and clean up when they no longer apply.
- Too many gotchas. If your section has 40 entries, the model will spend significant context window space loading all of them. Prioritize the top 10-15 by frequency and severity. Move edge cases to
references/gotchas-extended.mdand let the model load them on demand. - Duplicating official docs. If the official documentation already warns about a behavior clearly, you don’t need to repeat it. Focus on the things the docs miss or get wrong.
How Gotchas Fit Into the Larger Skill Structure
The gotchas section doesn’t exist in isolation. It works best when paired with the other structural elements Thariq outlined in his original breakdown.
Your description field gets the right skill activated. Your core instructions explain the workflow. Your references/ directory provides detailed documentation on demand. And your gotchas section prevents the model from making the mistakes that no amount of documentation can prevent—because they’re the things documentation usually gets wrong.
The ideal information flow looks like this:
- Description triggers activation → the model loads the skill
- SKILL.md core section → the model understands the workflow and goals
- Gotchas section → the model adjusts its default behavior at known failure points
- references/ files → the model loads detailed info only when needed
Gotchas sit at step 3—after the model knows what to do, but before it starts doing it. That positioning is critical. The gotchas reshape the model’s plan before it starts executing, preventing failures rather than recovering from them.
Frequently Asked Questions
How many gotchas should a skill have?
Start with 3-5 high-impact entries and grow from there. Most mature skills settle around 8-15 entries. If you have more than 15, split them into the main SKILL.md (top 10 by frequency) and a references/gotchas-extended.md file for edge cases the model can load when relevant.
Should I include gotchas about tools the skill doesn’t directly use?
Only if the interaction is non-obvious. If your deployment skill shells out to docker, a gotcha about Docker’s build cache behavior is fair game. A gotcha about Docker Compose networking when your skill never touches Compose is noise.
How do I know if a gotcha is too specific or too generic?
Apply the “would Claude already know this?” test. If Claude would handle it correctly without your gotcha, it’s too generic (or already covered in training data). If it requires insider knowledge of your specific tool, API, or codebase, it belongs.
Can gotchas reference code examples?
Yes, and they should when the fix involves specific code. Short inline code snippets (1-3 lines) work well directly in the gotcha entry. For longer examples, point to a file in examples/ to keep the gotchas section scannable.
Start With Your Most Painful Bug
If you’re building a skill and haven’t written a gotchas section yet, start now. Think of the bug that cost you the most time in this skill’s domain—the one where the fix was obvious after you found it, but invisible before. Write that as your first gotcha entry.
Then think of two more. That’s enough to ship.
The gotchas section isn’t something you write once and forget. It’s a living document that improves every time someone uses the skill and hits a new edge case. The best skills on AgentSkillExchange are the ones where the author kept feeding real-world failures back into the gotchas section—and every user after them benefited.
For more on writing effective skills, read our guides on lessons from Anthropic’s Thariq, description field optimization, and building your first skill in 15 minutes. Or browse the full skill marketplace to see gotchas sections in action.