| layout | default |
|---|---|
| title | Chapter 3: Advanced Skill Design |
| nav_order | 3 |
| parent | Anthropic Skills Tutorial |
Welcome to Chapter 3: Advanced Skill Design. 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.
Advanced skills are small systems. Treat them like mini-products with explicit interfaces.
customer-support-skill/
SKILL.md
scripts/
classify_ticket.py
enrich_account_context.ts
references/
escalation-policy.md
sla-tiers.md
assets/
issue-taxonomy.csv
templates/
escalation-email.md
Good skills avoid dumping all context at once. Instead:
- Start with task intent and output contract.
- Pull references only when relevant.
- Call scripts only when deterministic transformation is required.
This pattern reduces token waste and improves instruction adherence.
At minimum, keep name and description precise.
For larger catalogs, add optional metadata fields (when your runtime supports them) to improve discoverability and policy checks, such as:
- compatibility constraints
- license information
- ownership metadata
- tool allowlists
Scripts should be boring and reliable.
- Use strict argument parsing.
- Return stable JSON structures.
- Fail loudly with actionable error messages.
- Avoid hidden network side effects unless clearly documented.
Example output contract:
{
"status": "ok",
"severity": "high",
"routing_queue": "support-l2",
"confidence": 0.91
}- Put durable, high-signal guidance in
references/. - Keep
assets/for files that are required but not convenient to inline. - Version both in Git so skill behavior is auditable over time.
- Single responsibility per script
- Explicit file paths in instructions
- Backward-compatible schema evolution
- Changelog entries for instruction changes
You can now design skills that remain understandable as they grow beyond a single markdown file.
Next: Chapter 4: Integration Platforms
Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for support, escalation, customer 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 3: Advanced Skill Design 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 skill, SKILL, scripts as your checklist when adapting these patterns to your own repository.
Under the hood, Chapter 3: Advanced Skill Design usually follows a repeatable control path:
- Context bootstrap: initialize runtime config and prerequisites for
support. - Input normalization: shape incoming data so
escalationreceives stable contracts. - Core execution: run the main logic branch and propagate intermediate state through
customer. - 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
supportandescalationto map concrete implementation paths - compare docs claims against actual runtime/config code before reusing patterns in production
- Tutorial Index
- Previous Chapter: Chapter 2: Skill Categories
- Next Chapter: Chapter 4: Integration Platforms
- Main Catalog
- A-Z Tutorial Directory
The get_field_info function in skills/pdf/scripts/extract_form_field_info.py handles a key part of this chapter's functionality:
def get_field_info(reader: PdfReader):
fields = reader.get_fields()
field_info_by_id = {}
possible_radio_names = set()
for field_id, field in fields.items():
if field.get("/Kids"):
if field.get("/FT") == "/Btn":
possible_radio_names.add(field_id)
continue
field_info_by_id[field_id] = make_field_dict(field, field_id)
radio_fields_by_id = {}
for page_index, page in enumerate(reader.pages):
annotations = page.get('/Annots', [])
for ann in annotations:
field_id = get_full_annotation_field_id(ann)
if field_id in field_info_by_id:
field_info_by_id[field_id]["page"] = page_index + 1
field_info_by_id[field_id]["rect"] = ann.get('/Rect')
elif field_id in possible_radio_names:
try:
on_values = [v for v in ann["/AP"]["/N"] if v != "/Off"]
except KeyError:
continue
if len(on_values) == 1:
rect = ann.get("/Rect")This function is important because it defines how Anthropic Skills Tutorial: Reusable AI Agent Capabilities implements the patterns covered in this chapter.
The write_field_info function in skills/pdf/scripts/extract_form_field_info.py handles a key part of this chapter's functionality:
def write_field_info(pdf_path: str, json_output_path: str):
reader = PdfReader(pdf_path)
field_info = get_field_info(reader)
with open(json_output_path, "w") as f:
json.dump(field_info, f, indent=2)
print(f"Wrote {len(field_info)} fields to {json_output_path}")
if __name__ == "__main__":
if len(sys.argv) != 3:
print("Usage: extract_form_field_info.py [input pdf] [output json]")
sys.exit(1)
write_field_info(sys.argv[1], sys.argv[2])This function is important because it defines how Anthropic Skills Tutorial: Reusable AI Agent Capabilities implements the patterns covered in this chapter.
The create_blank_frame function in skills/slack-gif-creator/core/frame_composer.py handles a key part of this chapter's functionality:
def create_blank_frame(
width: int, height: int, color: tuple[int, int, int] = (255, 255, 255)
) -> Image.Image:
"""
Create a blank frame with solid color background.
Args:
width: Frame width
height: Frame height
color: RGB color tuple (default: white)
Returns:
PIL Image
"""
return Image.new("RGB", (width, height), color)
def draw_circle(
frame: Image.Image,
center: tuple[int, int],
radius: int,
fill_color: Optional[tuple[int, int, int]] = None,
outline_color: Optional[tuple[int, int, int]] = None,
outline_width: int = 1,
) -> Image.Image:
"""
Draw a circle on a frame.
Args:
frame: PIL Image to draw onThis function is important because it defines how Anthropic Skills Tutorial: Reusable AI Agent Capabilities implements the patterns covered in this chapter.
The draw_circle function in skills/slack-gif-creator/core/frame_composer.py handles a key part of this chapter's functionality:
def draw_circle(
frame: Image.Image,
center: tuple[int, int],
radius: int,
fill_color: Optional[tuple[int, int, int]] = None,
outline_color: Optional[tuple[int, int, int]] = None,
outline_width: int = 1,
) -> Image.Image:
"""
Draw a circle on a frame.
Args:
frame: PIL Image to draw on
center: (x, y) center position
radius: Circle radius
fill_color: RGB fill color (None for no fill)
outline_color: RGB outline color (None for no outline)
outline_width: Outline width in pixels
Returns:
Modified frame
"""
draw = ImageDraw.Draw(frame)
x, y = center
bbox = [x - radius, y - radius, x + radius, y + radius]
draw.ellipse(bbox, fill=fill_color, outline=outline_color, width=outline_width)
return frame
def draw_text(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[get_field_info]
B[write_field_info]
C[create_blank_frame]
D[draw_circle]
E[draw_text]
A --> B
B --> C
C --> D
D --> E