AI-Native Engineering 01: Package Procedural Knowledge as Agent Skills

This is part 2 of 9 in the AI-Native Engineering series. Start with the course index or continue to the next part below.

Audience. You should know one programming language, Git, a shell, HTTP, and how to run tests. The examples use plain files, JSON, HTTP, Git, and shell so the ideas transfer across agent SDKs.

Shared capstone. Every part extends the same shop-agent: a support agent that searches products, inspects orders, and prepares—but never executes—a refund recommendation. The companion repository lives alongside the site source.

Package Procedural Knowledge as Agent Skills

Capability. Turn “how our team does this” into a discoverable, versioned skill.

Anthropic describes a skill as a directory with a SKILL.md, optional scripts, and references. Metadata is loaded first; detailed files are loaded only when needed. This progressive disclosure prevents a giant instruction dump.

Minimal skill.

skills/refund-review/
├── SKILL.md
├── checklist.md
└── scripts/check_refund.py

---
name: refund-review
description: Review a proposed refund; use for policy, evidence, and safe handoff.
---

1. Read `checklist.md` only when a refund is proposed.
2. Verify order identity, payment state, and policy window.
3. Never call a money-moving tool. Return a recommendation and evidence.
4. Run `scripts/check_refund.py` before handoff.

Mental model. name + description → SKILL.md → linked reference → script. Each layer answers “is this relevant?”, “what do I do?”, “what detail do I need?”, and “what can be checked mechanically?”

flowchart LR
    M[Metadata] -->|triggers| K[SKILL.md]
    K -->|links when needed| R[Reference]
    K -->|runs| S[Deterministic script]
    S -->|fails check| F[Repair + handoff]
    F -->|updates| K

Text equivalent: Metadata lets the agent decide whether a skill is relevant. The agent then reads the skill, opens a linked reference only when needed, and runs a deterministic script for a check.

Module contract. Starting state: course/shop-agent/skills/refund-review/. Edit checklist.md; run scripts/check_refund.py; prove the handoff record passes.

Break it. Put every policy rule in SKILL.md. Measure whether unrelated tasks now receive the rules. Then split the file and add a test that every referenced path exists.

Acceptance test. From a clean checkout, an agent can discover the skill, run the script, and explain why the money-moving tool is out of scope. The skill has no secret, stale link, or instruction that conflicts with the repository policy.

Use when / don’t use when. Use skills for reusable procedures and domain context. Do not use them as a hidden permission system; permissions belong in the harness and tool server.

Continue the series

← Previous: Choose the Smallest Agentic Shape · Next: Engineer Context, Not Just Prompts →

Return to the course index.