PDF Processing changedagents-and-tools/agent-skills/overview
Nearest release: v2.1.307, published an hour after 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+33added
Lines−33removed
From line
41
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits10to this page, all time
The whole hunk
from line 41, old and new numbered
/
from line 41
4141
4242Skills use Claude's VM environment to provide capabilities beyond what's possible with prompts alone. Claude operates in a virtual machine with filesystem access, allowing Skills to exist as directories containing instructions, executable code, and reference materials, organized like an onboarding guide you'd create for a new team member.
4343
44This filesystem-based architecture enables **progressive disclosure:** Claude loads information in stages as needed, rather than consuming context upfront.
44This filesystem-based architecture allows **progressive disclosure:** Claude loads information in stages as needed, rather than consuming context upfront.
4545
4646Skills can contain three types of content, each loaded at a different time:
4747
from line 60
6060
6161### Level 2: Instructions (loaded when triggered)
6262
63The main body of SKILL.md contains procedural knowledge: workflows, best practices, and guidance:
63The main body of `SKILL.md` contains procedural knowledge: workflows, best practices, and guidance:
6464
6565````markdown
6666# PDF Processing
from line 79
7979For advanced form filling, see [FORMS.md](FORMS.md).
8080````
8181
82When you request something that matches a Skill's description, Claude reads SKILL.md from the filesystem using bash. Only then does this content enter the context window.
82When you request something that matches a Skill's description, Claude reads `SKILL.md` from the filesystem using bash. Only then does this content enter the context window.
8383
8484### Level 3: Resources and code (loaded as needed)
8585
from line 93
9393 * `scripts/`
9494 * `fill_form.py` (utility script)
9595
96**Instructions:** Additional markdown files (FORMS.md, REFERENCE.md) containing specialized guidance and workflows
96**Instructions:** Additional markdown files (`FORMS.md`, `REFERENCE.md`) containing specialized guidance and workflows
9797
98**Code:** Executable scripts (fill\_form.py, validate.py) that Claude runs using bash, providing deterministic operations without loading their code into context
98**Code:** Executable scripts (`fill_form.py`, `validate.py`) that Claude runs using bash, providing deterministic operations without loading their code into context
9999
100100**Resources:** Reference materials such as database schemas, API documentation, templates, or examples
101101
102102Claude accesses these files only when referenced. The filesystem model means each content type has different strengths: instructions for flexible guidance, code for reliability, resources for factual lookup.
103103
104| Level | When loaded | Token cost | Content |
105| ------------------------- | ----------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------- |
106| **Level 1: Metadata** | Always (at startup) | \~100 tokens per Skill | `name` and `description` from YAML frontmatter |
107| **Level 2: Instructions** | When Skill is triggered | Under 5k tokens | SKILL.md body with instructions and guidance |
108| **Level 3+: Resources** | As needed | None until accessed | Bundled files. Reference files load into context when read. Scripts run through bash, and only their output enters context |
104| Level | When loaded | Token cost | Content |
105| ------------------------- | ----------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------- |
106| **Level 1: Metadata** | Always (at startup) | \~100 tokens per Skill | `name` and `description` from YAML frontmatter |
107| **Level 2: Instructions** | When Skill is triggered | Under 5k tokens | `SKILL.md` body with instructions and guidance |
108| **Level 3+: Resources** | As needed | None until accessed | Bundled files. Reference files load into context when read. Scripts run through bash, and only their output enters context. |
109109
110110Progressive disclosure ensures only relevant content occupies the context window at any given time.
111111
from line 114
114114Skills run in a code execution environment where Claude has filesystem access, bash commands, and code execution capabilities. Skills exist as directories on a virtual machine, and Claude interacts with them using the same bash commands you'd use to navigate files on your computer.
115115
116116<Frame>
117 
117 
118118</Frame>
119119
120120**How Claude accesses Skill content:**
121121
122When a Skill is triggered, Claude uses bash to read SKILL.md from the filesystem, bringing its instructions into the context window. If those instructions reference other files (such as FORMS.md or a database schema), Claude reads those files too using additional bash commands. When instructions mention executable scripts, Claude runs them through bash and receives only the output (the script code itself never enters context).
122When a Skill is triggered, Claude uses bash to read `SKILL.md` from the filesystem, bringing its instructions into the context window. If those instructions reference other files (such as `FORMS.md` or a database schema), Claude reads those files too using additional bash commands. When instructions mention executable scripts, Claude runs them through bash and receives only the output (the script code itself never enters context).
123123
124**What this architecture enables:**
124**What this architecture makes possible:**
125125
126126* **On-demand file access:** Claude reads only the files each task needs. A Skill can include dozens of reference files, but if your task only needs the sales schema, that's the one file Claude loads. The rest stay on the filesystem and cost zero tokens.
127* **Efficient script execution:** When Claude runs `validate_form.py`, the script's code never loads into the context window. Only its output (such as "Validation passed" or a specific error message) consumes tokens, which makes scripts far more efficient than having Claude generate equivalent code on the fly.
127* **Efficient script execution:** When Claude runs `validate_form.py`, the script's code never loads into the context window. Only its output (such as "Validation passed" or a specific error message) consumes tokens, which makes scripts far more efficient than having Claude generate equivalent code during the task.
128128* **No practical limit on bundled content:** Files don't consume context until accessed, so Skills can include comprehensive API documentation, large datasets, or extensive examples. There's no context penalty for bundled content that isn't used.
129129
130130### Example: Loading a PDF processing Skill
from line 133
133133
1341341. **Startup:** System prompt includes: `pdf-processing - Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.`
1351352. **User request:** "Extract the text from this PDF and summarize it"
1363. **Claude invokes:** `bash: cat pdf-processing/SKILL.md` → Instructions loaded into context
1374. **Claude determines:** Form filling is not needed, so FORMS.md is not read
1385. **Claude executes:** Uses instructions from SKILL.md to complete the task
1363. **Claude calls:** `bash: cat pdf-processing/SKILL.md` → Instructions loaded into context
1374. **Claude determines:** Form filling is not needed, so `FORMS.md` is not read
1385. **Claude executes:** Uses instructions from `SKILL.md` to complete the task
139139
140140<Frame>
141141 
from line 165
165165
166166[Claude Code](https://code.claude.com/docs/en/overview) supports custom Skills. The pre-built document Skills (PowerPoint, Excel, Word, PDF) are not available in Claude Code, though the open-source [Claude API skill](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/claude-api-skill) comes bundled with it. See the full list of [built-in commands and Skills](https://code.claude.com/docs/en/commands) that ship with Claude Code.
167167
168**Custom Skills:** Create Skills as directories with SKILL.md files. Claude discovers and uses them automatically.
168**Custom Skills:** Create Skills as directories with `SKILL.md` files. Claude discovers and uses them automatically.
169169
170170Custom Skills in Claude Code are filesystem-based and don't require API uploads: place them in `~/.claude/skills/` (personal) or `.claude/skills/` (project).
171171
from line 219
219219`description`:
220220
221221* Must be non-empty
222* Maximum 1024 characters
222* Maximum 1,024 characters
223223* Cannot contain XML tags
224224
225225The `description` must include both what the Skill does and when Claude should use it. For complete authoring guidance, see [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices).
from line 226
226226
227227## Security considerations
228228
229Use Skills only from trusted sources: those you created yourself or obtained from Anthropic. Skills give Claude new capabilities through instructions and code, which also means a malicious Skill can direct Claude to invoke tools or execute code in ways that don't match the Skill's stated purpose.
229Use Skills only from trusted sources: those you created yourself or obtained from Anthropic. Skills give Claude new capabilities through instructions and code, which also means a malicious Skill can direct Claude to call tools or run code in ways that don't match the Skill's stated purpose.
230230
231231<Warning>
232 If you must use a Skill from an untrusted or unknown source, exercise extreme caution and thoroughly audit it before use. Depending on what access Claude has when executing the Skill, malicious Skills could lead to data exfiltration, unauthorized system access, or other security risks.
232 If you must use a Skill from an untrusted or unknown source, exercise extreme caution and thoroughly audit it before use. Depending on what access Claude has when running the Skill, malicious Skills could lead to data exfiltration, unauthorized system access, or other security risks.
233233</Warning>
234234
235235**Key security considerations:**
236236
237* **Audit thoroughly:** Review all files bundled in the Skill: SKILL.md, scripts, images, and other resources. Look for unusual patterns such as unexpected network calls, file access patterns, or operations that don't match the Skill's stated purpose
238* **External sources are risky:** Skills that fetch data from external URLs pose particular risk, as fetched content may contain malicious instructions. Even trustworthy Skills can be compromised if their external dependencies change over time
239* **Tool misuse:** Malicious Skills can invoke tools (file operations, bash commands, code execution) in harmful ways
240* **Data exposure:** Skills with access to sensitive data could be designed to leak information to external systems
241* **Treat like installing software:** Be especially careful when integrating Skills into production systems with access to sensitive data or critical operations
237* **Audit thoroughly:** Review all files bundled in the Skill: `SKILL.md`, scripts, images, and other resources. Look for unusual patterns such as unexpected network calls, file access patterns, or operations that don't match the Skill's stated purpose.
238* **External sources are risky:** Skills that fetch data from external URLs pose particular risk, as fetched content might contain malicious instructions. Even trustworthy Skills can be compromised if their external dependencies change over time.
239* **Tool misuse:** Malicious Skills can call tools (file operations, bash commands, code execution) in harmful ways.
240* **Data exposure:** Skills with access to sensitive data could be designed to leak information to external systems.
241* **Treat like installing software:** Be especially careful when integrating Skills into production systems with access to sensitive data or critical operations.
242242
243243For organization-scale governance, vetting, and deployment guidance, see [Skills for enterprise](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/enterprise). Claude Enterprise organizations can also turn on [Skill content scanning](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/enterprise#skill-content-scanning) for custom Skills uploaded in claude.ai and Claude Cowork. Scanning doesn't cover Skills uploaded through the Skills API or the Claude Console.
244244
from line 263
263263
264264### Custom Skills examples
265265
266For complete examples of custom Skills, see the [Skills cookbook](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction).
266For complete examples of custom Skills, see the [Agent Skills Cookbook](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction).
267267
268268## Data retention
269269
from line 281
281281
282282**Custom Skills do not sync across surfaces**. Skills uploaded to one surface are not automatically available on others:
283283
284* Skills uploaded to claude.ai must be separately uploaded to the API
285* Skills uploaded through the API are not available on claude.ai
286* Claude Code Skills are filesystem-based and separate from both claude.ai and API
284* Skills uploaded to claude.ai must be separately uploaded to the API.
285* Skills uploaded through the API are not available on claude.ai.
286* Claude Code Skills are filesystem-based and separate from both claude.ai and the API.
287287
288288Manage and upload Skills separately for each surface where you want to use them.
289289
from line 302
302302The exact runtime environment available to your Skill depends on the product surface where you use it.
303303
304304* **claude.ai:**
305 * **Varying network access:** Depending on user/admin settings, Skills may have full, partial, or no network access. For more details, see the [Create and Edit Files](https://support.claude.com/en/articles/12111783-create-and-edit-files-with-claude#h_6b7e833898) support article.
305 * **Varying network access:** Depending on user/admin settings, Skills might have full, partial, or no network access. For more details, see the [Create and Edit Files](https://support.claude.com/en/articles/12111783-create-and-edit-files-with-claude#h_6b7e833898) support article.
306306
307307* **Claude API:**
308308
No line in this hunk matches that.