Writing & Using Skills — Nick Nisi and Zack Proser
Writing & Using Skills
How to package repeatable agent tasks, load the right context, and test whether a skill helps
WorkOS developer experience engineers Nick Nisi and Zack Proser show how to package instructions, references, and scripts for a repeatable task in an agent skill. The description helps the agent decide when to load the skill, while optional files keep unrelated context out. Running the same task with and without the skill shows whether it improves the result. Team ownership and versioning remain unsettled, and the evaluation figures are approximate.
WorkOS developer experience engineers Nick Nisi and Zack Proser lead a hands-on workshop on agent skills. A skill is a small folder—sometimes only a SKILL.md file—that packages instructions for a specific kind of task and may also include references or scripts. Its description helps the agent decide when to load those instructions, keeping task-specific context out of unrelated runs.
Key Points Covered
- Describe when the skill applies: Write the description for the agent, naming the task and conditions that should trigger the skill. In the body, prefer a few clear constraints over an exhaustive procedure 07:46–09:24(opens in a new tab), 14:12–16:04(opens in a new tab).
- Reserve always-loaded files for universal rules: Put instructions needed in every session in
AGENTS.mdorCLAUDE.md; keep task-specific procedures, such as testing guidance, in skills that load only for relevant work 20:28–22:13(opens in a new tab). - Use scripts to supply repeatable evidence: Where the runtime supports it, run a fixed command to provide Git history, stale TODOs, or other inputs in a known format instead of making the agent rediscover them 16:04–17:49(opens in a new tab).
- Load supporting files only when needed: Point to a testing rubric, framework-specific guide, or migration reference only for the branch of work that requires it 43:56–45:46(opens in a new tab).
- Refine skills from real runs: Start small, use the skill on actual tasks, then add guidance where runs reveal repeated questions, failures, or unnecessary tool calls 48:35–51:33(opens in a new tab), 1:17:32–1:18:23(opens in a new tab).
- Test against the same task without the skill: Repeat both versions as models change. The Next.js example shows that an over-prescriptive skill can make a capable agent worse, but its reported percentage is only directional 29:24–30:27(opens in a new tab), 1:09:30–1:10:28(opens in a new tab).
- Treat distribution and governance separately: Project, internal, public, and personal locations provide ways to share skills, but they do not settle review ownership, forks, duplicate or conflicting skills, or ongoing maintenance 23:01–29:24(opens in a new tab), 31:14–32:06(opens in a new tab).
Full workshop: https://www.youtube.com/watch?v=pFsfax19yOM(opens in a new tab)