PDF Processing changedagents-and-tools/agent-skills/best-practices
Nearest release: v2.1.312, published under an hour before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+69added
Lines−69removed
From line
16
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits8to this page, all time
### Solve, don’t defer ### Solve, don't defer
The whole hunk
from line 16, old and new numbered
/
from line 16
1616
1717* The system prompt
1818* Conversation history
19* Other Skills' metadata
19* Other Skills’ metadata
2020* Your actual request
2121
2222Not every token in your Skill has an immediate cost. At startup, only the metadata (name and description) from all Skills is pre-loaded. Claude reads `SKILL.md` only when the Skill becomes relevant, and reads additional files only as needed. However, being concise in `SKILL.md` still matters: once Claude loads it, every token competes with conversation history and other context.
from line 23
2323
2424**Default assumption:** Claude is already very smart
2525
26Only add context Claude doesn't already have. Challenge each piece of information:
26Only add context Claude doesn’t already have. Challenge each piece of information:
2727
28* "Does Claude really need this explanation?"
29* "Can I assume Claude has this information?"
30* "Does this paragraph justify its token cost?"
28* “Does Claude really need this explanation?”
29* “Can I assume Claude has this information?”
30* “Does this paragraph justify its token cost?”
3131
3232**Good example: Concise** (approximately 50 tokens):
3333
from line 60
6060
6161### Set appropriate degrees of freedom
6262
63Match the level of specificity to the task's fragility and variability.
63Match the level of specificity to the task’s fragility and variability.
6464
6565**High freedom** (text-based instructions):
6666
from line 128
128128
129129**Analogy:** Think of Claude as a robot exploring a path:
130130
131* **Narrow bridge with cliffs on both sides:** There's only one safe way forward. Provide specific guardrails and exact instructions (low freedom). Example: database migrations that must run in exact sequence.
131* **Narrow bridge with cliffs on both sides:** There’s only one safe way forward. Provide specific guardrails and exact instructions (low freedom). Example: database migrations that must run in exact sequence.
132132* **Open field with no hazards:** Many paths lead to success. Give general direction and trust Claude to find the best route (high freedom). Example: code reviews where context determines the best approach.
133133
134134### Test with all models you plan to use
from line 153
153153 * Maximum 64 characters
154154 * Must contain only lowercase letters, numbers, and hyphens
155155 * Cannot contain XML tags
156 * Cannot contain reserved words: "anthropic", "claude"
156 * Cannot contain reserved words: `anthropic`, `claude`
157157
158158 `description`:
159159
from line 205
205205<Warning>
206206 **Always write in third person**. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems.
207207
208 * **Good:** "Processes Excel files and generates reports"
209 * **Avoid:** "I can help you process Excel files"
210 * **Avoid:** "You can use this to process Excel files"
208 * **Good:** “Processes Excel files and generates reports”
209 * **Avoid:** “I can help you process Excel files”
210 * **Avoid:** “You can use this to process Excel files”
211211</Warning>
212212
213213**Be specific and include key terms**. Include both what the Skill does and specific triggers/contexts for when to use it.
from line 377
377377
378378### Avoid deeply nested references
379379
380Claude might partially read files when they're referenced from other referenced files. When encountering nested references, Claude might use commands such as `head -100` to preview content rather than reading entire files, resulting in incomplete information.
380Claude might partially read files when they’re referenced from other referenced files. When encountering nested references, Claude might use commands such as `head -100` to preview content rather than reading entire files, resulting in incomplete information.
381381
382382**Keep references one level deep from `SKILL.md`**. All reference files should link directly from `SKILL.md` to ensure Claude reads complete files when needed.
383383
from line 478
478478Check that every claim references the correct source document. If citations are incomplete, return to Step 3.
479479````
480480
481This example shows how workflows apply to analysis tasks that don't require code. The checklist pattern works for any complex, multistep process.
481This example shows how workflows apply to analysis tasks that don’t require code. The checklist pattern works for any complex, multistep process.
482482
483483**Example 2: PDF form filling workflow** (for Skills with code):
484484
from line 549
5495495. Finalize and save the document
550550```
551551
552This shows the validation loop pattern using reference documents instead of scripts. The "validator" is `STYLE_GUIDE.md`, and Claude performs the check by reading and comparing.
552This shows the validation loop pattern using reference documents instead of scripts. The “validator” is `STYLE_GUIDE.md`, and Claude performs the check by reading and comparing.
553553
554554**Example 2: Document editing process** (for Skills with code):
555555
from line 573
573573
574574### Avoid time-sensitive information
575575
576Don't include information that will become outdated:
576Don’t include information that will become outdated:
577577
578578**Bad example: Time-sensitive** (will become wrong):
579579
from line 582
582582After August 2025, use the new API.
583583```
584584
585**Good example** (use "old patterns" section):
585**Good example** (use “old patterns” section):
586586
587587```markdown
588588## Current method
from line 608
608608
609609**Good - Consistent:**
610610
611* Always "API endpoint"
612* Always "field"
613* Always "extract"
611* Always “API endpoint”
612* Always “field”
613* Always “extract”
614614
615615**Bad - Inconsistent:**
616616
617* Mix "API endpoint," "URL," "API route," "path"
618* Mix "field," "box," "element," "control"
619* Mix "extract," "pull," "get," "retrieve"
617* Mix “API endpoint,” “URL,” “API route,” “path”
618* Mix “field,” “box,” “element,” “control”
619* Mix “extract,” “pull,” “get,” “retrieve”
620620
621621Consistency helps Claude parse and follow instructions.
622622
from line 753
753753
7547541. **Identify gaps:** Run Claude on representative tasks without a Skill. Document specific failures or missing context.
7557552. **Create evaluations:** Build three scenarios that test these gaps.
7563. **Establish baseline:** Measure Claude's performance without the Skill.
7563. **Establish baseline:** Measure Claude’s performance without the Skill.
7577574. **Write minimal instructions:** Create just enough content to address the gaps and pass evaluations.
7587585. **Iterate:** Run evaluations, compare against baseline, and refine.
759759
760This approach ensures you're solving actual problems rather than anticipating requirements that might never materialize.
760This approach ensures you’re solving actual problems rather than anticipating requirements that might never materialize.
761761
762762**Evaluation structure:**
763763
from line 780
780780
781781### Develop Skills iteratively with Claude
782782
783The most effective Skill development process involves Claude itself. Work with one instance of Claude ("Claude A") to create a Skill that is used by other instances ("Claude B"). Claude A helps you design and refine instructions, whereas Claude B tests them in real tasks. This works because Claude models can both write effective agent instructions and identify what information agents need.
783The most effective Skill development process involves Claude itself. Work with one instance of Claude (“Claude A”) to create a Skill that is used by other instances (“Claude B”). Claude A helps you design and refine instructions, whereas Claude B tests them in real tasks. This works because Claude models can both write effective agent instructions and identify what information agents need.
784784
785785**Creating a new Skill:**
786786
7871. **Complete a task without a Skill:** Work through a problem with Claude A using normal prompting. As you work, you'll naturally provide context, explain preferences, and share procedural knowledge. Notice what information you repeatedly provide.
7871. **Complete a task without a Skill:** Work through a problem with Claude A using normal prompting. As you work, you’ll naturally provide context, explain preferences, and share procedural knowledge. Notice what information you repeatedly provide.
788788
7897892. **Identify the reusable pattern:** After completing the task, identify what context you provided that would be useful for similar future tasks.
790790
791 **Example:** If you worked through a BigQuery analysis, you might have provided table names, field definitions, filtering rules (such as "always exclude test accounts"), and common query patterns.
791 **Example:** If you worked through a BigQuery analysis, you might have provided table names, field definitions, filtering rules (such as “always exclude test accounts”), and common query patterns.
792792
7933. **Ask Claude A to create a Skill:** "Create a Skill that captures this BigQuery analysis pattern we just used. Include the table schemas, naming conventions, and the rule about filtering test accounts."
7933. **Ask Claude A to create a Skill:** “Create a Skill that captures this BigQuery analysis pattern we just used. Include the table schemas, naming conventions, and the rule about filtering test accounts.”
794794
795795 <Tip>
796 Claude models handle the Skill format and structure natively. You don't need special system prompts or a "writing skills" skill to get Claude to help create Skills. Ask Claude to create a Skill and it generates properly structured `SKILL.md` content with appropriate frontmatter and body content.
796 Claude models handle the Skill format and structure natively. You don’t need special system prompts or a “writing skills” skill to get Claude to help create Skills. Ask Claude to create a Skill and it generates properly structured `SKILL.md` content with appropriate frontmatter and body content.
797797 </Tip>
798798
7994. **Review for conciseness:** Check that Claude A hasn't added unnecessary explanations. Ask: "Remove the explanation about what win rate means - Claude already knows that."
7994. **Review for conciseness:** Check that Claude A hasn’t added unnecessary explanations. Ask: “Remove the explanation about what win rate means - Claude already knows that.”
800800
8015. **Improve information architecture:** Ask Claude A to organize the content more effectively. For example: "Organize this so the table schema is in a separate reference file. We might add more tables later."
8015. **Improve information architecture:** Ask Claude A to organize the content more effectively. For example: “Organize this so the table schema is in a separate reference file. We might add more tables later.”
802802
8038036. **Test on similar tasks:** Use the Skill with Claude B (a fresh instance with the Skill loaded) on related use cases. Observe whether Claude B finds the right information, applies rules correctly, and handles the task successfully.
804804
8057. **Iterate based on observation:** If Claude B struggles or misses something, return to Claude A with specifics: "When Claude used this Skill, it forgot to filter by date for Q4. Should we add a section about date filtering patterns?"
8057. **Iterate based on observation:** If Claude B struggles or misses something, return to Claude A with specifics: “When Claude used this Skill, it forgot to filter by date for Q4. Should we add a section about date filtering patterns?”
806806
807807**Iterating on existing Skills:**
808808
from line 810
810810
811811* **Working with Claude A** (the expert who helps refine the Skill)
812812* **Testing with Claude B** (the agent using the Skill to perform real work)
813* **Observing Claude B's behavior** and bringing insights back to Claude A
813* **Observing Claude B’s behavior** and bringing insights back to Claude A
814814
8158151. **Use the Skill in real workflows:** Give Claude B (with the Skill loaded) actual tasks, not test scenarios.
816816
8172. **Observe Claude B's behavior:** Note where it struggles, succeeds, or makes unexpected choices.
8172. **Observe Claude B’s behavior:** Note where it struggles, succeeds, or makes unexpected choices.
818818
819 **Example observation:** "When I asked Claude B for a regional sales report, it wrote the query but forgot to filter out test accounts, even though the Skill mentions this rule."
819 **Example observation:** “When I asked Claude B for a regional sales report, it wrote the query but forgot to filter out test accounts, even though the Skill mentions this rule.”
820820
8213. **Return to Claude A for improvements:** Share the current `SKILL.md` and describe what you observed. Ask: "I noticed Claude B forgot to filter test accounts when I asked for a regional report. The Skill mentions filtering, but maybe it's not prominent enough?"
8213. **Return to Claude A for improvements:** Share the current `SKILL.md` and describe what you observed. Ask: “I noticed Claude B forgot to filter test accounts when I asked for a regional report. The Skill mentions filtering, but maybe it’s not prominent enough?”
822822
8234. **Review Claude A's recommendations:** Claude A might recommend reorganizing to make rules more prominent, using stronger language such as "MUST filter" instead of "always filter," or restructuring the workflow section.
8234. **Review Claude A’s recommendations:** Claude A might recommend reorganizing to make rules more prominent, using stronger language such as “MUST filter” instead of “always filter,” or restructuring the workflow section.
824824
8255. **Apply and test changes:** Update the Skill with Claude A's refinements, then test again with Claude B on similar requests.
8255. **Apply and test changes:** Update the Skill with Claude A’s refinements, then test again with Claude B on similar requests.
826826
8278276. **Repeat based on usage:** Continue this observe-refine-test cycle as you encounter new scenarios. Each iteration improves the Skill based on real agent behavior, not assumptions.
828828
from line 829
829829**Gathering team feedback:**
830830
8318311. Share Skills with teammates and observe their usage.
8322. Ask: Does the Skill activate when expected? Are instructions clear? What's missing?
8322. Ask: Does the Skill activate when expected? Are instructions clear? What’s missing?
8338333. Incorporate feedback to address gaps in your own usage patterns.
834834
835835**Why this approach works:** Claude A identifies agent needs, you provide domain expertise, Claude B reveals gaps through real usage, and iterative refinement improves Skills based on observed behavior rather than assumptions.
from line 838
838838
839839As you iterate on Skills, pay attention to how Claude actually uses them in practice. Watch for:
840840
841* **Unexpected exploration paths:** Does Claude read files in an order you didn't anticipate? This might indicate your structure isn't as intuitive as you thought.
841* **Unexpected exploration paths:** Does Claude read files in an order you didn’t anticipate? This might indicate your structure isn’t as intuitive as you thought.
842842* **Missed connections:** Does Claude fail to follow references to important files? Your links might need to be more explicit or prominent.
843843* **Overreliance on certain sections:** If Claude repeatedly reads the same file, consider whether that content should be in the main `SKILL.md` instead.
844844* **Ignored content:** If Claude never accesses a bundled file, it might be unnecessary or poorly signaled in the main instructions.
845845
846Iterate based on these observations rather than assumptions. The `name` and `description` in your Skill's metadata are particularly critical. Claude uses these when determining whether to trigger the Skill in response to the current task. Make sure they clearly describe what the Skill does and when it should be used.
846Iterate based on these observations rather than assumptions. The `name` and `description` in your Skill’s metadata are particularly critical. Claude uses these when determining whether to trigger the Skill in response to the current task. Make sure they clearly describe what the Skill does and when it should be used.
847847
848848## Anti-patterns to avoid
849849
from line 858
858858
859859### Avoid offering too many options
860860
861Don't present multiple approaches unless necessary:
861Don’t present multiple approaches unless necessary:
862862
863863````markdown
864864**Bad example: Too many choices** (confusing):
from line 877
877877
878878The following sections focus on Skills that include executable scripts. If your Skill uses only markdown instructions, skip to [Checklist for effective Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#checklist-for-effective-skills).
879879
880### Solve, don't defer
880### Solve, don’t defer
881881
882882When writing scripts for Skills, handle error conditions rather than deferring to Claude.
883883
from line 909
909909 return open(path).read()
910910```
911911
912Also justify and document configuration parameters to avoid "voodoo constants" (Ousterhout's law). If you don't know the right value, how will Claude determine it?
912Also justify and document configuration parameters to avoid “voodoo constants” (Ousterhout’s law). If you don’t know the right value, how will Claude determine it?
913913
914914**Good example: Self-documenting:**
915915
from line 949
949949
950950**Important distinction:** Make clear in your instructions whether Claude should:
951951
952* **Run the script** (most common): "Run `analyze_form.py` to extract fields"
953* **Read it as reference** (for complex logic): "See `analyze_form.py` for the field extraction algorithm"
952* **Run the script** (most common): “Run `analyze_form.py` to extract fields”
953* **Read it as reference** (for complex logic): “See `analyze_form.py` for the field extraction algorithm”
954954
955For most utility scripts, execution is preferred because it's more reliable and efficient. See the following [Runtime environment](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#runtime-environment) section for details on how script execution works.
955For most utility scripts, execution is preferred because it’s more reliable and efficient. See the following [Runtime environment](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#runtime-environment) section for details on how script execution works.
956956
957957**Example:**
958958
from line 1004
10041004````
10051005
10061006<Note>
1007 In this example, you'd need to write the `pdf_to_images.py` script.
1007 In this example, you’d need to write the `pdf_to_images.py` script.
10081008</Note>
10091009
1010Claude's vision capabilities help analyze layouts and structures.
1010Claude’s vision capabilities help analyze layouts and structures.
10111011
10121012### Create verifiable intermediate outputs
10131013
1014When Claude performs complex, open-ended tasks, it can make mistakes. The "plan-validate-execute" pattern catches errors early by having Claude first create a plan in a structured format, then validate that plan with a script before executing it.
1014When Claude performs complex, open-ended tasks, it can make mistakes. The “plan-validate-execute” pattern catches errors early by having Claude first create a plan in a structured format, then validate that plan with a script before executing it.
10151015
10161016**Example:** Imagine asking Claude to update 50 form fields in a PDF based on a spreadsheet. Without validation, Claude might reference non-existent fields, create conflicting values, miss required fields, or apply updates incorrectly.
10171017
from line 1026
10261026
10271027**When to use:** Batch operations, destructive changes, complex validation rules, high-stakes operations.
10281028
1029**Implementation tip:** Make validation scripts verbose with specific error messages such as "Field 'signature\_date' not found. Available fields: customer\_name, order\_total, signature\_date\_signed" to help Claude fix issues.
1029**Implementation tip:** Make validation scripts verbose with specific error messages such as “Field ‘signature\_date’ not found. Available fields: customer\_name, order\_total, signature\_date\_signed” to help Claude fix issues.
10301030
10311031### Package dependencies
10321032
from line 1035
10351035* **claude.ai:** Can install packages from npm and PyPI and pull from GitHub repositories
10361036* **Claude API:** Has no network access and no runtime package installation
10371037
1038List required packages in your `SKILL.md` and verify they're available in the [Code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool) documentation.
1038List required packages in your `SKILL.md` and verify they’re available in the [Code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool) documentation.
10391039
10401040### Runtime environment
10411041
from line 1045
10451045
10461046**How Claude accesses Skills:**
10471047
10481. **Metadata pre-loaded:** At startup, the name and description from all Skills' YAML frontmatter are loaded into the system prompt.
10481. **Metadata pre-loaded:** At startup, the name and description from all Skills’ YAML frontmatter are loaded into the system prompt.
104910492. **Files read on-demand:** Claude uses bash Read tools to access `SKILL.md` and other files from the filesystem when needed.
10503. **Scripts run efficiently:** Utility scripts can be run through bash without loading their full contents into context. Only the script's output consumes tokens.
10514. **No context penalty for large files:** Reference files, data, or documentation don't consume context tokens until actually read.
10503. **Scripts run efficiently:** Utility scripts can be run through bash without loading their full contents into context. Only the script’s output consumes tokens.
10514. **No context penalty for large files:** Reference files, data, or documentation don’t consume context tokens until actually read.
10521052
10531053* **File paths matter:** Claude navigates your skill directory like a filesystem. Use forward slashes (`reference/guide.md`), not backslashes.
10541054
from line 1065
10651065
10661066* **Make execution intent clear:**
10671067
1068 * "Run `analyze_form.py` to extract fields" (execute)
1069 * "See `analyze_form.py` for the extraction algorithm" (read as reference)
1068 * “Run `analyze_form.py` to extract fields” (execute)
1069 * “See `analyze_form.py` for the extraction algorithm” (read as reference)
10701070
10711071* **Test file access patterns:** Verify Claude can navigate your directory structure by testing with real requests.
10721072
from line 1088
10881088
10891089### MCP tool references
10901090
1091If your Skill uses MCP (Model Context Protocol) tools, always use fully qualified tool names to avoid "tool not found" errors.
1091If your Skill uses MCP (Model Context Protocol) tools, always use fully qualified tool names to avoid “tool not found” errors.
10921092
10931093**Format:** `ServerName:tool_name`
10941094
from line 1108
11081108
11091109### Avoid assuming tools are installed
11101110
1111Don't assume packages are available:
1111Don’t assume packages are available:
11121112
11131113````markdown
11141114**Bad example: Assumes installation**:
from line 1149
11491149* [ ] Description includes both what the Skill does and when to use it
11501150* [ ] `SKILL.md` body is under 500 lines
11511151* [ ] Additional details are in separate files (if needed)
1152* [ ] No time-sensitive information (or in "old patterns" section)
1152* [ ] No time-sensitive information (or in “old patterns” section)
11531153* [ ] Consistent terminology throughout
11541154* [ ] Examples are concrete, not abstract
11551155* [ ] File references are one level deep
from line 1160
11601160
11611161* [ ] Scripts solve problems rather than defer to Claude
11621162* [ ] Error handling is explicit and helpful
1163* [ ] No "voodoo constants" (all values justified)
1163* [ ] No “voodoo constants” (all values justified)
11641164* [ ] Required packages listed in instructions and verified as available
11651165* [ ] Scripts have clear documentation
11661166* [ ] No Windows-style paths (all forward slashes)
No line in this hunk matches that.