| layout | default |
|---|---|
| title | Chapter 1: Getting Started |
| nav_order | 1 |
| parent | Anthropic Skills Tutorial |
Welcome to Chapter 1: Getting Started. In this part of Anthropic Skills Tutorial: Reusable AI Agent Capabilities, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
This chapter gets you from zero to a functioning skill you can iterate on.
A minimal skill is one folder plus one file:
my-first-skill/
SKILL.md
SKILL.md has two important parts:
- Frontmatter for identity and routing metadata
- Instruction body that defines behavior, constraints, and output expectations
---
name: incident-summary
description: Summarize incident notes into a concise operations report
---
When given incident notes:
1. Produce a timeline of events.
2. List likely contributing factors.
3. Propose prioritized action items with owners.Most teams should move immediately from free-form instructions to explicit output contracts.
## Output Contract
- Return markdown only.
- Include sections: `Timeline`, `Contributing Factors`, `Actions`.
- Each action must include `owner`, `due_date`, and `risk_if_missed`.This single addition usually reduces variance more than model-level tuning.
As tasks become operational, move from one-file skills to structured packages:
incident-skill/
SKILL.md
templates/
postmortem.md
scripts/
normalize_incident_json.py
references/
severity-matrix.md
Use this rule:
- Put policy and behavior in
SKILL.md - Put deterministic transforms in
scripts/ - Put stable source context in
references/
- Run the skill against 5 to 10 representative prompts.
- Save outputs as golden snapshots.
- Tighten instructions where variance or ambiguity appears.
- Re-run snapshots after every instruction change.
This gives you fast regression detection without heavyweight tooling.
| Mistake | Symptom | Fix |
|---|---|---|
| Broad description | Skill triggers for unrelated requests | Narrow the description to explicit use cases |
| No output schema | Inconsistent format between runs | Add required sections and field-level constraints |
| Hidden dependencies | Skill fails on missing files/scripts | Document all dependencies in SKILL.md |
| Conflicting instructions | Internal contradiction in outputs | Remove overlap and define precedence |
You now have a valid, testable skill package and a repeatable iteration loop.
Next: Chapter 2: Skill Categories
Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for incident, skill, SKILL so behavior stays predictable as complexity grows.
In practical terms, this chapter helps you avoid three common failures:
- coupling core logic too tightly to one implementation path
- missing the handoff boundaries between setup, execution, and validation
- shipping changes without clear rollback or observability strategy
After working through this chapter, you should be able to reason about Chapter 1: Getting Started as an operating subsystem inside Anthropic Skills Tutorial: Reusable AI Agent Capabilities, with explicit contracts for inputs, state transitions, and outputs.
Use the implementation notes around notes, action, first as your checklist when adapting these patterns to your own repository.
Under the hood, Chapter 1: Getting Started usually follows a repeatable control path:
- Context bootstrap: initialize runtime config and prerequisites for
incident. - Input normalization: shape incoming data so
skillreceives stable contracts. - Core execution: run the main logic branch and propagate intermediate state through
SKILL. - Policy and safety checks: enforce limits, auth scopes, and failure boundaries.
- Output composition: return canonical result payloads for downstream consumers.
- Operational telemetry: emit logs/metrics needed for debugging and performance tuning.
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
Use the following upstream sources to verify implementation details while reading this chapter:
- anthropics/skills repository
Why it matters: authoritative reference on
anthropics/skills repository(github.com).
Suggested trace strategy:
- search upstream code for
incidentandskillto map concrete implementation paths - compare docs claims against actual runtime/config code before reusing patterns in production
The ReviewHandler class in skills/skill-creator/eval-viewer/generate_review.py handles a key part of this chapter's functionality:
print("Note: lsof not found, cannot check if port is in use", file=sys.stderr)
class ReviewHandler(BaseHTTPRequestHandler):
"""Serves the review HTML and handles feedback saves.
Regenerates the HTML on each page load so that refreshing the browser
picks up new eval outputs without restarting the server.
"""
def __init__(
self,
workspace: Path,
skill_name: str,
feedback_path: Path,
previous: dict[str, dict],
benchmark_path: Path | None,
*args,
**kwargs,
):
self.workspace = workspace
self.skill_name = skill_name
self.feedback_path = feedback_path
self.previous = previous
self.benchmark_path = benchmark_path
super().__init__(*args, **kwargs)
def do_GET(self) -> None:
if self.path == "/" or self.path == "/index.html":
# Regenerate HTML on each request (re-scans workspace for new outputs)
runs = find_runs(self.workspace)
benchmark = None
if self.benchmark_path and self.benchmark_path.exists():This class is important because it defines how Anthropic Skills Tutorial: Reusable AI Agent Capabilities implements the patterns covered in this chapter.
The get_mime_type function in skills/skill-creator/eval-viewer/generate_review.py handles a key part of this chapter's functionality:
def get_mime_type(path: Path) -> str:
ext = path.suffix.lower()
if ext in MIME_OVERRIDES:
return MIME_OVERRIDES[ext]
mime, _ = mimetypes.guess_type(str(path))
return mime or "application/octet-stream"
def find_runs(workspace: Path) -> list[dict]:
"""Recursively find directories that contain an outputs/ subdirectory."""
runs: list[dict] = []
_find_runs_recursive(workspace, workspace, runs)
runs.sort(key=lambda r: (r.get("eval_id", float("inf")), r["id"]))
return runs
def _find_runs_recursive(root: Path, current: Path, runs: list[dict]) -> None:
if not current.is_dir():
return
outputs_dir = current / "outputs"
if outputs_dir.is_dir():
run = build_run(root, current)
if run:
runs.append(run)
return
skip = {"node_modules", ".git", "__pycache__", "skill", "inputs"}
for child in sorted(current.iterdir()):
if child.is_dir() and child.name not in skip:This function is important because it defines how Anthropic Skills Tutorial: Reusable AI Agent Capabilities implements the patterns covered in this chapter.
The find_runs function in skills/skill-creator/eval-viewer/generate_review.py handles a key part of this chapter's functionality:
def find_runs(workspace: Path) -> list[dict]:
"""Recursively find directories that contain an outputs/ subdirectory."""
runs: list[dict] = []
_find_runs_recursive(workspace, workspace, runs)
runs.sort(key=lambda r: (r.get("eval_id", float("inf")), r["id"]))
return runs
def _find_runs_recursive(root: Path, current: Path, runs: list[dict]) -> None:
if not current.is_dir():
return
outputs_dir = current / "outputs"
if outputs_dir.is_dir():
run = build_run(root, current)
if run:
runs.append(run)
return
skip = {"node_modules", ".git", "__pycache__", "skill", "inputs"}
for child in sorted(current.iterdir()):
if child.is_dir() and child.name not in skip:
_find_runs_recursive(root, child, runs)
def build_run(root: Path, run_dir: Path) -> dict | None:
"""Build a run dict with prompt, outputs, and grading data."""
prompt = ""
eval_id = NoneThis function is important because it defines how Anthropic Skills Tutorial: Reusable AI Agent Capabilities implements the patterns covered in this chapter.
The build_run function in skills/skill-creator/eval-viewer/generate_review.py handles a key part of this chapter's functionality:
outputs_dir = current / "outputs"
if outputs_dir.is_dir():
run = build_run(root, current)
if run:
runs.append(run)
return
skip = {"node_modules", ".git", "__pycache__", "skill", "inputs"}
for child in sorted(current.iterdir()):
if child.is_dir() and child.name not in skip:
_find_runs_recursive(root, child, runs)
def build_run(root: Path, run_dir: Path) -> dict | None:
"""Build a run dict with prompt, outputs, and grading data."""
prompt = ""
eval_id = None
# Try eval_metadata.json
for candidate in [run_dir / "eval_metadata.json", run_dir.parent / "eval_metadata.json"]:
if candidate.exists():
try:
metadata = json.loads(candidate.read_text())
prompt = metadata.get("prompt", "")
eval_id = metadata.get("eval_id")
except (json.JSONDecodeError, OSError):
pass
if prompt:
break
# Fall back to transcript.md
if not prompt:This function is important because it defines how Anthropic Skills Tutorial: Reusable AI Agent Capabilities implements the patterns covered in this chapter.
flowchart TD
A[ReviewHandler]
B[get_mime_type]
C[find_runs]
D[build_run]
E[embed_file]
A --> B
B --> C
C --> D
D --> E