Anthropic Skills — Administrator & Developer Guide

1. Architecture Overview

Anthropic Skills is a curated skill pack for Claude Code — a collection of 16 self-contained skill directories that extend Claude's capabilities in specific domains. The repository is not a traditional software application with a runtime, server, or database. Instead, it is a content-and-script package: each skill is a bundle of markdown instructions (SKILL.md), optional Python or shell helper scripts, reference documentation, and static assets. Claude Code loads these skills on demand, reading the SKILL.md to understand the skill's purpose and available tools, then executing scripts as needed.

The architecture follows a flat, modular pattern:

anthropics/skills/
├── skills/                    # All 16 skills
│   ├── {skill-name}/
│   │   ├── SKILL.md           # Skill definition (loaded by Claude Code)
│   │   ├── LICENSE.txt        # Per-skill license
│   │   ├── scripts/           # Helper scripts (Python/Shell)
│   │   ├── reference/         # Reference documentation
│   │   └── examples/          # Usage examples
│   └── ...
├── template/
│   └── SKILL.md               # Template for creating new skills
├── spec/
│   └── agent-skills-spec.md   # Skill format specification
├── THIRD_PARTY_NOTICES.md     # Third-party license attributions
└── README.md                  # Repository overview

Component Inventory

Technology Stack

Note

This repository contains no server, no database, no API endpoints, and no CLI commands. It is a content package consumed by Claude Code's skill loading mechanism. The "architecture" is the directory convention and the SKILL.md contract.

Data Flow

The primary data flow is straightforward:

1. User invokes a skill by name (e.g., /pdf) in Claude Code
2. Claude Code reads skills/pdf/SKILL.md for instructions and available tools
3. Claude follows the SKILL.md instructions, optionally executing scripts from scripts/
4. Scripts read input files and write output to the user's workspace
5. Claude reports results to the user

2. System Requirements

Per-Skill Dependencies

Important

The Office document skills (docx, pptx, xlsx) share a common scripts/office/ infrastructure including XML schema validation, pack/unpack utilities, and LibreOffice integration via soffice.py. LibreOffice must be installed and accessible as soffice on the system path for document preview and conversion operations.

3. Configuration Reference

Skill Definition Format (SKILL.md)

Each skill is defined by a SKILL.md file in its directory root. This file is the skill's contract with Claude Code — it defines what the skill does, when it activates, and what tools are available.

The template at template/SKILL.md provides the canonical structure:

Environment Variables

Important

There are no configuration files, YAML settings, or environment-specific overrides in this repository. All configuration is implicit through environment variables and the SKILL.md contract.

Shared Reference Documents (claude-api)

The Claude API skill uses a shared/ directory for cross-language documentation:

4. Deployment & Scaling

Distribution Model

Skills are distributed as a Git repository. There is no build step, no compilation, and no container:

# Install (clone into Claude Code's skill directory)
claude skills install anthropics/skills

# Update (pull latest from repository)
claude skills update anthropics/skills

Repository Structure for Distribution

The repository follows a deliberate structure that separates per-skill content from shared infrastructure:

skills/          # Individual skill directories (the product)
template/        # Skill creation boilerplate (for developers)
spec/            # Formal specification (for developers)

Each skill is self-contained — removing a skill directory has no impact on other skills. The only cross-cutting dependency is the shared scripts/office/ infrastructure used by the three Office document skills (docx, pptx, xlsx), which each carry their own copy of the validation framework.

Note

The Office document skills (docx, pptx, xlsx) each contain their own copy of scripts/office/ with identical pack/unpack, validation, and helper code. This deliberate duplication ensures each skill is independently deployable, though it means bug fixes must be applied to all three copies.

Versioning

The repository is versioned through Git commits. Skills do not have independent version numbers — the repository commit hash serves as the version identifier. The current source commit is d211d43 (2026-05-06).

5. Operations

Monitoring Skill Health

Skills have no runtime state, processes, or services to monitor. Operational health means:

1. The skill directory exists and contains a valid SKILL.md
2. Required Python packages are installed
3. Helper scripts are executable
4. External dependencies (LibreOffice, Playwright, etc.) are available

Tip

Run claude skills list to verify all skills are recognized. If a skill is missing, check that its directory contains a SKILL.md file.

Updating Skills

claude skills update anthropics/skills

This performs a git pull on the skill repository. There is no migration step — new versions of SKILL.md files, scripts, and reference documents take effect immediately on the next invocation.

Tip

After updating, verify that per-skill Python dependencies still match by checking requirements.txt files in each skill's scripts/ directory.

Backup and Recovery

The skill repository is the single source of truth. Recovery is a fresh clone:

claude skills install anthropics/skills

User-generated output (PDFs, documents, GIFs, test results) lives in the user's workspace, not in the skill repository.

6. Performance

GIF Builder Optimization

The GIFBuilder class in skills/slack-gif-creator/core/gif_builder.py provides several optimization controls:

The color optimization uses Pillow's quantize() with a global palette built from sampled frames. For large animations (50+ frames), this involves stacking frame pixels into a combined image for palette generation — expect proportional memory usage.

OOXML Validation Performance

The XML validation pipeline in scripts/office/validators/base.py performs:

1. XML well-formedness check (lxml parse)
2. Namespace declaration validation
3. Unique ID verification (iterates all elements)
4. File reference validation (resolves all .rels entries)
5. Relationship ID cross-referencing
6. Content type verification

For large documents (100+ XML files), steps 3-5 can take several seconds. The validator loads all files into memory via rglob().

7. Security

Script Execution Model

Skills can include executable Python scripts that Claude runs during skill invocation. These scripts:

• Execute with the permissions of the Claude Code process
• Have full filesystem access to the user's workspace
• Can make network requests (e.g., mcp-builder, claude-api examples)
• Are not sandboxed beyond Claude Code's own permission model

Warning

Review script contents before installing third-party skills. The scripts/ directory in each skill contains code that will be executed with your user permissions. The official anthropics/skills repository is maintained by Anthropic, but forked or community skills should be audited.

Dependency Security

Caution

The Office document skills use defusedxml.minidom for safe XML parsing, preventing XML External Entity (XXE) attacks. However, the validation pipeline also uses lxml.etree.parse() directly for schema validation. Files from untrusted sources should be treated with caution.

Credential Management

The Claude API skill's managed agents documentation demonstrates vault-based credential management:

• API keys are passed via environment variables, not hardcoded
• OAuth credentials are stored in vaults (client.beta.vaults.create()) with server-side encryption
• GitHub tokens are passed as authorization_token on session resources
• The skill documentation explicitly warns against calling agents.create in the request path (which would leak system prompts)

License Compliance

All skills are MIT-licensed. Font assets carry OFL (SIL Open Font License) or Apache 2.0 licenses with attribution in THIRD_PARTY_NOTICES.md. The XML schemas are from ISO/IEC 29500-4:2016 and ECMA-376 4th edition.

8. Developer Internals

Repository Structure

skills/
├── algorithmic-art/           # JS-based generative art
│   ├── SKILL.md, LICENSE.txt
│   └── templates/             # JS generator template + HTML viewer
├── brand-guidelines/          # Brand evaluation
│   └── SKILL.md, LICENSE.txt
├── canvas-design/             # Canvas-based design
│   ├── SKILL.md, LICENSE.txt
│   └── canvas-fonts/          # 30+ open-source TTF fonts
├── claude-api/                # API reference (largest skill)
│   ├── SKILL.md, LICENSE.txt
│   ├── csharp/                # C# examples
│   ├── curl/                  # cURL examples + managed agents
│   ├── go/                    # Go SDK + managed agents
│   ├── java/                  # Java SDK + managed agents
│   ├── php/                   # PHP SDK + managed agents
│   ├── python/
│   │   ├── claude-api/        # Core API (messages, vision, caching, thinking)
│   │   └── managed-agents/    # Agents, sessions, events, files, vaults
│   ├── ruby/                  # Ruby SDK + managed agents
│   ├── shared/                # 15 cross-language reference docs
│   └── typescript/
│       ├── claude-api/        # Core API
│       └── managed-agents/    # Managed agents
├── doc-coauthoring/           # Collaborative editing
│   └── SKILL.md
├── docx/                      # Word document creation
│   ├── SKILL.md, LICENSE.txt
│   └── scripts/
│       ├── accept_changes.py  # Accept tracked changes
│       ├── comment.py         # Add/manage comments
│       └── office/            # Shared OOXML infrastructure
├── frontend-design/           # Frontend UI design
│   └── SKILL.md, LICENSE.txt
├── internal-comms/            # Internal communications
│   ├── SKILL.md, LICENSE.txt
│   └── examples/              # 4 communication templates
├── mcp-builder/               # MCP server scaffolding
│   ├── SKILL.md, LICENSE.txt
│   ├── reference/             # Best practices + language guides
│   └── scripts/               # Connection testing + evaluation
├── pdf/                       # PDF creation/manipulation
│   ├── SKILL.md, LICENSE.txt
│   ├── forms.md, reference.md
│   └── scripts/               # 8 helper scripts
├── pptx/                      # PowerPoint creation
│   ├── SKILL.md, LICENSE.txt
│   ├── editing.md, pptxgenjs.md
│   └── scripts/               # add_slide, clean, thumbnail + office/
├── skill-creator/             # Meta-skill for skill creation
│   ├── SKILL.md, LICENSE.txt
│   ├── agents/                # Analyzer, comparator, grader agents
│   ├── assets/                # HTML eval review template
│   ├── eval-viewer/           # Evaluation results viewer
│   ├── references/            # Schema documentation
│   └── scripts/               # 8 evaluation/packaging scripts
├── slack-gif-creator/         # Animated GIF creation
│   ├── SKILL.md, LICENSE.txt
│   ├── requirements.txt
│   └── core/                  # Easing, frame composition, GIF builder
├── theme-factory/             # Design theme generation
│   ├── SKILL.md, LICENSE.txt
│   ├── theme-showcase.pdf
│   └── themes/                # 10 pre-built themes
├── web-artifacts-builder/     # Web artifact bundling
│   ├── SKILL.md, LICENSE.txt
│   └── scripts/               # init-artifact.sh, bundle-artifact.sh, shadcn
├── webapp-testing/            # Playwright-based testing
│   ├── SKILL.md, LICENSE.txt
│   ├── examples/              # 3 Python automation examples
│   └── scripts/               # with_server.py
└── xlsx/                      # Excel spreadsheet creation
    ├── SKILL.md, LICENSE.txt
    └── scripts/               # recalc.py + office/

Module Reference

GIFBuilder (skills/slack-gif-creator/core/gif_builder.py)

The central class for GIF creation. Manages frame collection, color optimization, deduplication, and output.

class GIFBuilder:
    def __init__(self, width: int = 480, height: int = 480, fps: int = 15)
    def add_frame(self, frame: np.ndarray | Image.Image)
    def add_frames(self, frames: list[np.ndarray | Image.Image])
    def optimize_colors(self, num_colors: int = 128, use_global_palette: bool = True) -> list[np.ndarray]
    def deduplicate_frames(self, threshold: float = 0.9995) -> int
    def save(self, output_path: str | Path, num_colors: int = 128,
             optimize_for_emoji: bool = False, remove_duplicates: bool = False) -> dict
    def clear(self)

Key behaviors:

• Frames are stored as NumPy arrays internally; PIL Images are converted on add_frame()
• optimize_colors() builds a global palette from 5 sampled frames when use_global_palette=True
• deduplicate_frames() uses mean pixel difference with a high default threshold (0.9995) to preserve subtle animations
• save() raises ValueError("No frames to save. Add frames with add_frame() first.") if no frames are present
• Emoji optimization resizes to 128x128, caps colors at 48, and reduces to ~12 frames

Easing Functions (skills/slack-gif-creator/core/easing.py)

Provides 19 easing functions for animation timing, plus utility functions:

Convenience mapping via EASING_FUNCTIONS dict. Access by name with get_easing(name).

Utility functions:

• interpolate(start, end, t, easing) — interpolate between two values with named easing
• apply_squash_stretch(base_scale, intensity, direction) — volume-preserving squash/stretch
• calculate_arc_motion(start, end, height, t) — parabolic arc path calculation

Frame Composer (skills/slack-gif-creator/core/frame_composer.py)

Drawing primitives for frame construction:

All functions accept and return PIL.Image.Image objects. Drawing uses PIL.ImageDraw.

Validators (skills/slack-gif-creator/core/validators.py)

Emoji validation: 128x128 optimal, 64-128 square acceptable. Message GIF validation: aspect ratio ≤ 2.0, shortest dimension 320-640px.

OOXML Validator (skills/{docx,pptx,xlsx}/scripts/office/validators/base.py)

The BaseSchemaValidator class provides the validation infrastructure shared across Office document types:

class BaseSchemaValidator:
    def validate(self)                      # Abstract — implemented by subclasses
    def repair(self) -> int                 # Run auto-repairs (whitespace preservation)
    def validate_xml(self)                  # Check XML well-formedness
    def validate_namespaces(self)           # Verify namespace declarations
    def validate_unique_ids(self)           # Check ID uniqueness per scope
    def validate_file_references(self)      # Verify .rels targets exist
    def validate_all_relationship_ids(self) # Cross-reference rIDs against .rels
    def validate_content_types(self)        # Verify [Content_Types].xml

Key design decisions:

• Uses lxml.etree for schema validation and defusedxml.minidom for safe repair operations
• UNIQUE_ID_REQUIREMENTS maps element names to (attribute, scope) tuples where scope is "file" or "global"
• SCHEMA_MAPPINGS maps file patterns to ISO/IEC 29500-4 and ECMA-376 XSD files
• IGNORED_VALIDATION_ERRORS suppresses known false positives (hyphenationZone, purl.org/dc/terms)
• AlternateContent (MCE) elements are removed before ID validation to avoid false duplicates
• repair_whitespace_preservation() automatically adds xml:space="preserve" to text runs with leading/trailing whitespace

Subclasses DocxValidator, PptxValidator, and RedliningValidator extend this base with format-specific rules.

Office Pack/Unpack (scripts/office/pack.py, unpack.py)

Utility scripts for working with OOXML files as unpacked directory trees:

• unpack.py — extracts .docx/.pptx/.xlsx to a directory of XML files
• pack.py — reassembles an unpacked directory into a valid Office file
• soffice.py — LibreOffice integration for preview and conversion

Webapp Testing Examples

Three Playwright automation examples in skills/webapp-testing/examples/:

All examples use playwright.sync_api.sync_playwright with headless Chromium, viewport 1920x1080 (or default), and networkidle wait strategy.

Skill Creator Scripts

Eight scripts in skills/skill-creator/scripts/ for the skill development lifecycle:

Supporting agents in skills/skill-creator/agents/:

• analyzer.md — Analyzes skill structure and quality
• comparator.md — Compares skill versions
• grader.md — Grades skill quality against criteria

Code Patterns and Conventions

Skill naming: lowercase, hyphenated directory names under skills/ (e.g., slack-gif-creator, web-artifacts-builder).

Script organization: Python scripts live in scripts/ subdirectories. The __init__.py files in docx, pptx, xlsx, and skill-creator scripts directories indicate these are importable packages.

Office infrastructure duplication: The scripts/office/ directory (pack, unpack, validate, soffice, helpers, schemas) is fully duplicated across docx, pptx, and xlsx skills. This is intentional — each skill must be independently functional. The validators share the same base.py with format-specific subclasses.

Font bundling: Canvas design includes 30+ TTF fonts directly in the repository (canvas-fonts/), each with its own OFL license file. This avoids runtime font downloads.

Reference-only skills: Several skills (brand-guidelines, doc-coauthoring, frontend-design) contain only a SKILL.md with no scripts. They rely entirely on Claude's built-in capabilities, guided by the skill's instructions.

Claude API skill structure: The largest skill by file count, organized by language with a shared/ directory for cross-cutting concepts. Each language directory has a claude-api/ README for core API usage and a managed-agents/ README for the managed agents API.

Testing Strategy

The repository includes no automated test suite. Quality assurance is handled through:

1. Skill evaluation framework (skill-creator/scripts/run_eval.py) — benchmarks skill trigger rates and output quality
2. OOXML validation (scripts/office/validators/) — validates generated documents against ISO/IEC standards
3. GIF validation (core/validators.py) — checks output dimensions, file size, and frame count for Slack compliance
4. Manual testing — skills are tested by invoking them in Claude Code sessions

Note

Issue #556 reports that run_eval.py achieves a 0% trigger rate when claude -p does not properly activate skills/commands. This suggests the evaluation framework may need updates to match current Claude Code skill loading behavior.

Potential Improvements

Areas for improvement, based on the current source and community issues:

1. Deduplicate Office infrastructure — The scripts/office/ directory is fully copied across docx, pptx, and xlsx. A shared package or symlink approach would reduce maintenance burden.

2. Add automated CI tests — No test suite exists. Evaluation scripts exist in skill-creator but are not integrated into CI.

3. Fix run_eval.py trigger rate (issue #556) — The evaluation framework's 0% trigger rate suggests a mismatch between how it invokes Claude and how skills are registered.

4. Enable org-wide skill sharing (issue #228) — Currently skills must be installed per-user. Organization-level sharing would reduce friction for teams.

5. Improve Windows compatibility (issue #954) — The spaces-in-path bug on Windows affects skill updates.

6. Add explicit versioning — Individual skills have no version numbers; the entire repository is versioned by commit hash. Per-skill versioning would enable selective updates.

7. Expand MCP builder templates — The current reference material covers Python and Node.js; other languages could be added.

8. Add skill dependency declarations — Skills that require Python packages don't have a standard way to declare dependencies that Claude Code could auto-install.

Contributing

The repository follows a standard open-source contribution model:

1. Fork the repository
2. Create a skill directory under skills/ following the template/SKILL.md structure
3. Include a LICENSE.txt (MIT for consistency with existing skills)
4. Add helper scripts in scripts/ if needed
5. Test the skill by installing it locally in Claude Code
6. Evaluate with the skill-creator's run_eval.py if applicable
7. Submit a pull request

9. Integration Points

Claude Code Integration

Skills integrate with Claude Code through the SKILL.md loading mechanism:

• Trigger: User invokes a skill by name (e.g., /pdf)
• Loading: Claude Code reads the SKILL.md file and presents it as context
• Execution: Claude follows instructions in SKILL.md, executing scripts via tool use
• Output: Results are written to the user's workspace

Claude API (via claude-api skill)

The Claude API skill provides integration patterns for seven languages:

Warning

The managed agents API is in beta. Agent objects are immutable per version — updates create new versions. Always store the agent ID and reuse it across sessions; do not recreate agents per request.

MCP Server Integration (via mcp-builder skill)

The MCP builder skill scaffolds servers that implement the Model Context Protocol, enabling Claude to use external tools:

• Python servers using the mcp library
• Node.js servers using the MCP SDK
• Connection testing via scripts/connections.py
• Evaluation framework via scripts/evaluation.py

Office Document Pipeline (docx, pptx, xlsx)

The Office document skills share a common pipeline:

Create/Edit → Unpack (ZIP → XML tree) → Modify XML → Validate → Pack (XML → ZIP) → Verify

The pipeline uses:

• unpack.py to extract OOXML packages to XML files
• Direct XML manipulation via lxml
• validate.py to check against ISO/IEC 29500-4 schemas
• pack.py to reassemble valid packages
• soffice.py for LibreOffice-based preview and conversion