Hands-On Agent Skills: From Folder to Shippable Expertise
Published by O'Reilly Media, Inc.
Learn to design and build a useful agent Skill
What you’ll learn and how you can apply it
- Articulate what an agent Skill is and why its folder format is essential
- Apply the 15/85 complementarity framing to decide whether a candidate task is worth packaging as a Skill
- Evaluate a Skill draft against a concrete rubric and identify its weakest dimension
- Diagnose the common Skill antipatterns and refactor a draft Skill to avoid them
- Design and build a working Skill with a policy file and decision log that make it shareable across a team
Course description
Agent Skills are quickly becoming the most consequential form factor for transferring expertise to AI systems. But most Skills shipped today don’t earn their place in the agent’s buffer: They balloon system prompts, route ambiguously, or don’t encode real human judgment.
In this hands-on 2-hour course with Lucas Soares, you’ll first learn what a Skill is and why the folder format ensures the constraints that drive the whole design. Then you’ll spend the bulk of the course on the patterns that distinguish Skills worth reusing from Skills that quietly degrade your agent. You’ll learn about 15/85 complementarity framing, which is a rubric for what counts as good, litmus tests for catching bad-but-compliant drafts, and the anti-patterns that show up in almost every first attempt. You’ll leave with a working Skill of your own, designed against the rubric, plus a decision framework for when not to build a Skill at all.
Schedule
The time frames are only estimates and may vary according to how the class is progressing.
What a Skill actually Is (30 minutes)
- Presentation: From folders to expertise; an email-writing Skill walkthrough; why “just paste it into the system prompt” looks like the easy answer, and what that intuition is missing; the agent’s universe is its context window; the phenomenon known as context rot; loading-on-demand as the only honest answer
- Q&A
- Break
The mental framework and the rubric (25 minutes)
- Presentation: The human does the judgment, the machine does the volume; what changes when the “machine” part is an agent that can act and remember; single, well-scoped responsibility; leanness through progressive disclosure; defined inputs and outputs; stateless across runs when possible
- Hands-on exercise: Score a Skill; identify the weakest dimension and what would have to change to fix it
- Q&A
- Break
Patterns that work (30 minutes)
- Presentation: Why parallel exploration beats iterative refinement at the discovery stage of a Skill; the virtuous context-building cycle; transcribing your own critique of a draft so it becomes the next prompt; what litmus tests catch that test cases never will
- Hands-on exercise: Build the first version of your own Skill
- Q&A
How skills fail, and how to ship them anyway (25 minutes)
- Presentation: The antipatterns you’ll ship at least once—the Frankenstein Skill, routing ambiguity, vague bodies that demand user instructions to be useful, runtime lock-in, the compatibility field as the fix, closing the loop; testing Skills by their output artifacts rather than by rerunning them end-to-end every time; when to retire a Skill instead of fixing it; making Skills shareable across a team; pairing each Skill with a decision log of alternatives considered and discarded; framing discarded variants
- Demonstration: A real shipped Skill, with policy file and decision log
- Q&A
Wrap-up and Q&A (10 minutes)
- Presentation: When to build a Skill, when to leave it in your project instructions file or a prompt, when to reach for an MCP server, and when to use a subagent or a Cowork session instead
- Q&A
Your Instructor
Lucas Soares
Lucas Soares is a machine learning engineer who has worked at K1 Digital and Biometrid, where he developed computer vision and NLP models for applications such as document verification, OCR-based applications, and recommender systems. Lucas has also developed various ML models, including neural networks, Siamese networks, convolutional neural networks, LSTMs, and genetic algorithms.