← ContentsClaude Code · intermediate

SKILL.md system & skill authoring

The SKILL.md system is a structured way to package specialized knowledge, workflows, and executable code into reusable units that Claude can discover and invoke automatically. Each skill lives in its own directory containing at minimum a SKILL.md file, which opens with YAML frontmatter declaring a name and description, followed by markdown instructions, reference material, and optionally executable scripts or supporting files. Skills are loaded lazily: Claude evaluates each skill's frontmatter description against the current task and only injects the full skill content into its context window when a semantic match occurs. This means a project can include dozens of skills without bloating the active context — only the relevant skill is loaded for any given request. Skills can also include dynamic context injection, where lines like `!\`git diff HEAD\`` are executed before Claude sees the skill content, so real-time data (a current diff, an open GitHub issue) arrives already inlined. In Claude Code, skills are discovered automatically from `~/.claude/skills/` (global) or `.claude/skills/` (project-local). In Claude.ai web and Team/Enterprise plans, skills are uploaded as ZIP archives through the UI or Organization settings. On the API, skills are uploaded programmatically and integrated through the code execution tool. Across all surfaces, skills share the same SKILL.md file format and the same YAML frontmatter schema.

When you’d use it

  • Brand guidelines enforcementA marketing team stores Acme Corp's official colors, fonts, logo placement rules, and tone-of-voice guidelines in a skill. Whenever anyone asks Claude to create a presentation or document, the skill loads automatically and the output is consistently on-brand without manual reminders.
  • Automated API documentationA backend team builds a skill that reads endpoint handler files, parses request/response payloads, and formats the output as OpenAPI schemas or Markdown reference docs. Developers run it on demand instead of writing documentation by hand.
  • GitHub issue investigation and patchingA developer types /fix-issue 1234. The skill uses shell injection to run `gh issue view 1234`, prepend the live issue text into the prompt, and then instructs Claude to trace the root cause and implement a passing patch — all in one turn, with no secondary tool-call round trip.
  • Sprint planning and project managementAn engineering team encodes their sprint workflow — story templates, definition-of-done checklists, estimation rubrics — into a skill. Claude uses the skill to create properly formatted tickets, flag missing acceptance criteria, and generate sprint summaries.
  • PDF form extraction and batch fillingA HR team uploads a skill with Python scripts that use PyPDF2 to extract fillable form fields and populate them from a CSV. Claude runs the scripts without loading either the scripts or the PDFs into conversational context, then returns completed PDFs as a ZIP archive.

What changed recently

  • 2025-10Agent Skills beta launched (API version: skills-2025-10-02). Initial release included Anthropic-managed skills for PowerPoint (.pptx), Excel (.xlsx), Word (.docx), and PDF files, plus custom skill upload via the Skills API. Skills integrate with the Messages API through the code execution tool.
  • 2025-12-18Organization-wide skill deployment added for Team and Enterprise plans. Admins can now provision skills workspace-wide with automatic updates and centralized management. A directory of partner-built skills was introduced. Agent Skills was published as an open standard to enable cross-platform portability.
  • 2026-01-06Anthropic officially announced Agent Skills publicly (news post dated January 6, 2026), describing the system as a new way to extend Claude's capabilities with organized folders of instructions, scripts, and resources.
  • 2026-03Claude Code skills gained dynamic context injection support: lines beginning with !` in SKILL.md are executed as shell commands before Claude reads the skill, so real-time output (e.g., git diffs, live issue data) is inlined into the instructions. The legacy .claude/commands/ directory was deprecated and merged into the .claude/skills/ system, giving former slash commands access to directory-level bundling, shell injection, and effort-level overrides via ${CLAUDE_EFFORT}.
This is the short version

The full chapter has three worked examples, the common pitfalls, and the workflow that makes it pay — plus the other 84 features, kept current.

Get Claude Master — $97
CLAUDEMASTER
An independent publication.
Independent product. Not affiliated with or endorsed by Anthropic. “Claude” is a trademark of Anthropic, used here only to describe the subject of this manual.
© 2026 Claude Master — All rights reserved.