agent/agentskills
1
0
Fork 0
mirror of https://github.com/agentskills/agentskills.git synced 2026-06-18 15:54:06 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add gotchas section to best practices guide

Browse Source 
Add a new "Gotchas sections" subsection to "Patterns for effective
instructions" in the best practices guide. Covers what a gotcha is
(environment-specific facts that defy reasonable assumptions), how to
structure them (problem/correction pairs), and why they belong directly
in `SKILL.md` rather than a separate reference file.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jonathan Hefner
2026-03-15 17:30:30 -05:00
Unverified
parent 36a4d328c0
commit 4be62ebad0
1 changed files with 22 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/skill-creation/best-practices.mdx
+22
View File
@@ -162,6 +162,28 @@ This doesn't mean skills can't include specific details — output format templa
These are reusable techniques for structuring skill content. Not every skill needs all of them — use the ones that fit your task.
### Gotchas sections
The highest-value content in many skills is a list of gotchas — environment-specific facts that defy reasonable assumptions. These aren't general advice ("handle errors appropriately") but concrete corrections to mistakes the agent will make without being told otherwise:
````markdown
## Gotchas
- The `users` table uses soft deletes. Queries must include
`WHERE deleted_at IS NULL` or results will include deactivated accounts.
- The user ID is `user_id` in the database, `uid` in the auth service,
and `accountId` in the billing API. All three refer to the same value.
- The `/health` endpoint returns 200 as long as the web server is running,
even if the database connection is down. Use `/ready` to check full
service health.
````
Keep gotchas in `SKILL.md` where the agent reads them before encountering the situation. A separate reference file works if you tell the agent when to load it, but for non-obvious issues, the agent may not recognize the trigger.
<Tip>
When an agent makes a mistake you have to correct, add the correction to the gotchas section. This is one of the most direct ways to improve a skill iteratively (see [Refine with real execution](#refine-with-real-execution)).
</Tip>
### Templates for output format
When you need the agent to produce output in a specific format, provide a template. This is more reliable than describing the format in prose, because agents pattern-match well against concrete structures. Short templates can live inline in `SKILL.md`; for longer templates, or templates only needed in certain cases, store them in `assets/` and reference them from `SKILL.md` so they only load when needed.