I'm learning to author and use Agent Skills in Claude and Codex. I gained some insights and I would like to share them here today.
Skill content comes in three types: instructions, scripts, and resources. Skills are organized as files/folders that Claude can draw from via a filesystem-style interface. Claude does progressive disclosure: it does not need to load the entire Skill into the context window upfront, and can fetch only the relevant files as needed. 1
Skill content types have different strengths:
- Instructions: flexible guidance and procedures (how to do the task, standards, checklists).
- Scripts: reliable and deterministic execution (Claude runs the code; the script contents typically do not need to be included in the context).
- Resources: factual/reference material for lookup (templates, policy text, examples). 1
You might also use custom instructions. These are preferences about how Claude works with you in general. You might already use Projects for certain work. Projects make sense when context accumulates over time.
Custom instructions apply broadly to all your conversations. Skills are task-specific and only load when relevant, making them better for specialized workflows that you want Claude to apply automatically. 1
Projects provide a persistent workspace where relevant background context can accumulate over time. Skills provide specialized procedures and capabilities that activate dynamically when needed and can work across Claude experiences (claude.ai / API / agent workflows) rather than being tied to a single project context. 1
You ask Claude to create a quarterly business review. Claude can already build presentations, but making them match your standards means explaining your preferences each time. You could document guidelines in a Project, but they don't automatically apply when you need them outside that workflow.
- Efficient script execution: When Claude runs a script, the script’s code typically does not need to be loaded into the context window. Only the script’s output or specific error messages consume tokens. This makes scripts far more efficient than having Claude generate equivalent code on the fly. 1
- This dynamic loading ensures only relevant Skill content occupies the context window (“progressive disclosure”), so Skills can bundle large amounts of procedural knowledge without forcing it all into the prompt. 1
Skill authoring best practices 2
- Good Skills are concise, well-structured, and tested with real usage.
- Avoid vague descriptions like these: "Helps with documents", "Processes data".
- Naming conventions matter for discoverability and reuse (recommended: gerund form, e.g.
processing-pdfs). - Anti-patterns to avoid: Avoid Windows-style paths. Avoid offering too many options at once.
- Even if Claude could write a script, pre-made scripts offer advantages: more reliable than generated code on the fly, save tokens, save time, consistent across uses.
- Create verifiable intermediate outputs