simonw-agentic-patterns

---
name: simonw-agentic-patterns
description: "Use when you want Simon Willison's framing of Claude Skills — the SKILL.md pattern, sandboxed filesystem execution, validation helpers, and the prompt-injection caveats that come with dangerous-skip-permissions."
source: https://simonwillison.net/2025/Oct/16/claude-skills/
generated: 2026-05-17T04:18:36.897Z
category: concept
audience: engineers
---

## When to use

- Deciding whether to ship a feature as an MCP server or as a Claude Skill
- Designing a SKILL.md so harnesses can scan it cheaply and trigger it precisely
- Adding validation helper functions so Claude can iterate against hard constraints
- Thinking through what 'safe coding environment' actually means before enabling skip-permissions
- Loading skill-specific Python modules from a known mount path inside the sandbox
- Comparing Claude Skills against the broader MCP protocol surface

## Key concepts

### Skill = Markdown + optional assets

Willison defines a skill as 'a Markdown file telling the model how to do something, optionally accompanied by extra documents and pre-written scripts.' The simplicity is the point — the harness handles the rest.

### Token-efficient discovery

Skills use YAML frontmatter metadata that the harness scans at session start, consuming only dozens of tokens per skill until one is actually needed. This makes large skill libraries cheap to keep loaded.

### Sandbox dependency

Skills fundamentally require 'access to a filesystem, tools to navigate it and the ability to execute commands.' This is what differentiates skills from MCP, which has no execution-environment requirement.

### Validation helper functions

Skills can ship helper functions for constraint checking. The slack-gif-creator example includes check_slack_size() to enforce the 2MB limit, letting Claude iterate on outputs until the constraint passes.

### Python path integration

Skills load their own modules via standard imports against a known mount point, e.g. sys.path.insert(0, '/mnt/skills/examples/slack-gif-creator'), so generated code can call into pre-written scripts.

### Skills vs MCP trade-off

Unlike MCP's complex protocol (hosts, clients, servers, resources, prompts, tools, sampling, roots, elicitation, three transports), skills deliberately outsource complexity to the harness — betting on model capability over protocol specification.

## API reference

```
sys.path.insert(0, '/mnt/skills/examples/<skill-name>')
```

Add a skill's directory to the Python path inside the sandbox so its helper scripts are importable.

```
import sys
sys.path.insert(0, '/mnt/skills/examples/slack-gif-creator')
from helpers import check_slack_size
```

```
check_slack_size(path) -> bool
```

Example validation helper from the slack-gif-creator skill that enforces Slack's 2MB upload limit so Claude can iterate when an output exceeds it.

```
if not check_slack_size('out.gif'):
    # re-render with lower fps / fewer colors
    ...
```

## Gotchas

- The word 'safe' in 'safe coding environments' is doing significant work — prompt injection risk is real
- Skills require filesystem and command execution; without a sandbox they are unsafe to run
- Frontmatter metadata governs triggering — a weak description means Claude never loads the skill
- dangerous-skip-permissions removes guardrails; combine it with a sandbox or you're handing the model your machine
- Skills and MCP solve overlapping problems differently — picking one over the other is a real architectural choice
- Validation helpers only help if Claude actually calls them; document them in SKILL.md so the model knows they exist

---
Generated by SkillMake from https://simonwillison.net/2025/Oct/16/claude-skills/ on 2026-05-17T04:18:36.897Z.
Verify against source before relying on details.

File: ~/.claude/skills/simonw-agentic-patterns/SKILL.md