Full Walkthrough: Writing & Using Skills — Nick Nisi and Zack Proser

May 6, 20261:21:0317,643 views

Summary

Nick Nisi and Zach Proser, developer experience engineers on the applied AI team at WorkOS, lead a hands-on workshop on writing and using Skills — portable, reusable units of agent behavior that operate across Claude, Codex, Cursor, and Claude Desktop without modification.

The central problem Skills solve is repetitive re-contextualization: every new AI session starts from zero, and Claude.md / agents.md files bloat context windows because they load unconditionally. A Skill is a folder containing a skill.md file with YAML front matter (name + description), optional scripts, and reference documents. The description field is the critical routing primitive — the LLM reads it at runtime to decide whether to invoke the skill. Writing good descriptions is therefore writing routing rules for the model, not human summaries.

A key demonstrated technique is script interpolation via bang-backtick syntax, which injects deterministic command output (e.g., `git log --oneline -10`) directly into the skill's prompt. This prevents the model from speculating about repo state, saves tokens, and produces consistent results across runs.

Progressive disclosure allows larger skill systems to avoid bloating context: skill.md includes conditional file references (e.g., a scoring rubric or migration guide) that are only loaded when the current task requires them. The WorkOS public skills repo uses a skill_router pattern to map framework-specific Next.js, TanStack, and React Router migration guides to on-demand loading.

Confidence scoring is demonstrated through Nick's open-source ideation skill: the skill asks clarifying questions and scores across dimensions (problem clarity, goal definition, success criteria, scope boundaries) before proceeding. It only executes once confidence reaches 95-96 out of 100. This pattern also caught a concrete regression in evaluation: an overly prescriptive Next.js installer skill caused a ~30% drop in accuracy because Claude already has strong built-in Next.js knowledge. The WorkOS eval framework runs multiple passes with and without a skill, grades against a rubric, and requires ~80-90% correctness to pass.

Team-scale skills management was debated via audience questions from a 60-person engineering org. The speakers recommend three tiers: project-specific skills in .claude/skills/, personal global skills in ~/.claude/skills/, and marketplace skills via `npx skills add` or the Claude plugin marketplace. WorkOS ships skills as the intelligence layer behind their `npx workos install` CLI, which proxies all execution to the Claude Agent SDK — framework-specific logic lives in skills files, not CLI code.

Beyond developer tooling, the workshop demonstrates skills for non-technical workflows: a recruiting report skill that pulls from Slack, Notion, and ATS systems; a two-script animation skill using Imagen 3 (Nano Banana) and Google VEO that generates animated video from a single text prompt in ~30 seconds; a Remotion skill that produces a demo video from git history with a live localhost editor; and Slack-to-Linear ticket automation via a looping Claude Code agent using the Slack OAuth connector.

The session closes with two key practices: use Claude's built-in skill-builder skill to evaluate and iterate on existing skills, and mine past conversation JSONL logs — where Claude spun in circles, asked redundant questions, or produced wrong output — as the richest source of signal for skill improvement.

Key Takeaways

•Write the skill description as a routing rule for the LLM, not a human summary — it determines when the skill is auto-loaded at runtime.
•Use bang-backtick script interpolation to inject deterministic command output (e.g., git log) rather than asking the model to fetch it, saving tokens and improving consistency.
•Prefer constraints over prescriptions: telling the model what NOT to do typically outperforms overly detailed step-by-step instructions, as demonstrated by a ~30% accuracy drop from over-specifying Next.js behavior.
•Use progressive disclosure to load reference documents conditionally — only inject a scoring rubric or migration guide when the current task actually requires it.
•Add confidence scoring to skills that require well-specified inputs: force the model to ask clarifying questions until it reaches a threshold (e.g., 95/100) before executing.
•Evaluate skills systematically: run tasks with and without the skill, grade against a rubric, and set a pass threshold (~80-90% correctness) to detect regressions when new models ship.
•Tier your skills: project-specific in .claude/skills/, personal global in ~/.claude/skills/, and team-wide via versioned git repos or plugin marketplaces.
•Skills can power CLIs via the Claude Agent SDK — encode all intelligence in skills files and proxy execution through the agent SDK rather than hardcoding logic in the CLI.
•Non-technical users can share and load skills by renaming a .zip of a skill folder to .skill and dragging it into Claude Desktop.
•Treat past AI conversation JSONL logs as training material for skill improvement: mine what failed, what was frustrating, and where the model spun unnecessarily.

Transcript

This workshop is going to be skills at scale. We're super excited to be here with you today. There's going to be an interactive component and we also want you to feel free to interrupt us and ask questions as we go. >> Yeah, we'll show that slide again with the with the QR code and the the instructions to clone the repo. That repo has the skills the skills that we're working on plus the slides that we're presenting. So you'll have all of that as reference material. I am Nick Nisi. I am a develop...