Anthropic's Internal Claude Skills Framework

Skill Architecture and Components

Anthropic treats Claude Skills as functional folders containing scripts, assets, and configuration files rather than simple markdown files. To build robust systems, developers should partition workflows into deterministic tasks handled by code scripts and non-deterministic tasks handled by the LLM.

• Scripts: Use code to handle deterministic logic, which reduces token usage and ensures repeatable outputs.
• Assets/Templates: Store standard output formats (e.g., PowerPoint templates) in the skill folder to prevent the model from improvising structure.
• Setup/Config: Include a config.json to store persistent user preferences and use ask_user_question tools for structured, multi-choice inputs instead of free-form text.

Verification and Quality Control

Verification is the most critical component for increasing output quality, with internal data suggesting that effective verification can improve performance by 2x to 3x.

• Correctness vs. Quality: Distinguish between verifying factual accuracy (e.g., code execution) and stylistic quality (e.g., brand voice).
• Skill-Driven Verification: Modify existing skills to include a pass/fail output or a numerical grade, allowing the agent to self-critique before presenting work to the user.
• Gotchas: Maintain a gotchas section in the skill.md file to log specific edge cases and failure points. This serves as a living document that grows as the agent encounters new errors, effectively building a personal moat around the skill's reliability.

Categorization and Orchestration

Skills should be categorized into four distinct types to avoid agent confusion: Utility (reusable tasks), Verification (quality checks), Data Enrichment (external data integration), and Orchestration (chaining other skills).

• Orchestration: Build complex workflows by chaining smaller utility skills rather than writing monolithic scripts. This ensures that updates to a single utility skill propagate across all dependent orchestrations.
• Trigger Tuning: The description field in a skill is a functional trigger condition, not a summary. Explicitly state the user intent or keywords that should invoke the skill (e.g., "Use this skill when the user asks to build...") to ensure the agent calls the correct tool automatically.