Skills at Scale — Nick Nisi and Zack Proser, WorkOS

Nick Nisi and Zach Proser from WorkOS explain how to build, manage, and scale AI 'skills'—reusable, portable instructions that make AI agents like Claude more powerful and consistent. They cover the core anatomy of a skill, best practices for writing them, advanced techniques like progressive disclosure, and their application beyond coding, from video generation to automating business workflows.

May 6, 2026 5 min read

Skills at Scale — Nick Nisi and Zack Proser, WorkOS — source: https://www.youtube.com/watch?v=pFsfax19yOM

The Challenge with Stateless AI Conversations

AI models like Claude operate on a conversational basis, meaning each session starts without any memory of past interactions. To achieve consistent results, users must repeatedly provide context, such as coding conventions, project-specific tooling (e.g., pnpm over npm), and architectural patterns.

While memory files like .claude.md or agents.md can store this information, they have significant downsides:

Context Bloat: These files are loaded into the context window for every conversation, consuming valuable tokens even when the information is not relevant to the current task.
Lack of Portability: They are often tied to a specific repository or a global user setting, making them difficult to share and reuse across different projects.
Limited Functionality: They are static and cannot easily incorporate dynamic data or execute scripts to provide deterministic results.

Introducing Skills: Composable, Context-Aware Instructions

Skills are presented as the solution to these challenges, acting as discrete, portable, and composable units of work. They encapsulate specific knowledge and workflows, bringing the “Don’t Repeat Yourself” (DRY) principle to the agentic era.

A key advantage is that skills are loaded on-demand. The AI agent determines which skill is relevant to a given task based on its description, injecting the context only when needed. This keeps the primary context window lean and efficient.

The Anatomy of a Skill

A skill is fundamentally a directory containing a skill.md file and any other necessary assets like scripts or reference documents.

The skill.md file consists of two main parts:

Frontmatter: YAML metadata at the top of the file. The most critical fields are name and description. The description is not for human readers but acts as a routing rule for the LLM, telling it when the skill should be activated.
Body: The main content of the file, written in Markdown, which contains the instructions for the AI.

Skills can be stored in a .claude/skills/ directory within a project repository for project-specific instructions, or in the user’s home directory for global availability.

Best Practices for Authoring Effective Skills

Write Descriptions for the AI: Craft descriptions that clearly and accurately define the skill’s purpose so the LLM can reliably route to it. For example, a skill for generating pixel art could have a description like, “When the user asks for an image for their personal blog, use this skill to generate it in a pixel art style.”
Provide Constraints, Not Overly-Detailed Prescriptions: It is often more effective to set boundaries and rules rather than writing a novel-length procedure. Providing a few clear constraints (e.g., “Never be vague,” “Always cite code with a specific line number and git commit hash”) allows the LLM more creative freedom while ensuring the output meets your standards.
Use Scripts for Determinism: To avoid non-deterministic behavior where the AI might speculate or fail to retrieve information, you can embed executable scripts. In Claude, this is done with the ! syntax. The command inside the backticks is executed, and its output is directly interpolated into the context. This is highly effective for tasks like fetching the latest git commits or finding stale TODOs, as it provides the AI with precise, factual data to work from, saving tokens and improving reliability.

Advanced Techniques for Smarter Skills

Progressive Disclosure: To avoid overwhelming the context with information that may not be needed, you can structure skills to load additional context dynamically. The main skill file can act as a “router,” pointing to other reference files. For instance, it might instruct the AI: “If you are performing a code review that involves scoring, load and follow the scoring_rubric.md file.” This keeps the initial skill lightweight and pulls in detailed information only when necessary.
Confidence Scoring: You can instruct the skill to force the LLM into a self-evaluation loop. Before executing a complex task, the AI assesses its confidence in understanding the requirements based on a predefined rubric (e.g., problem clarity, scope boundaries). If the confidence score is below a certain threshold, it is instructed to ask clarifying questions until it has enough information to proceed. This iterative process leads to significantly better and more aligned outcomes.

The Skill Development Lifecycle

The recommended workflow for creating and refining skills is iterative:

Build: Create an initial version of the skill, either manually or by using a tool like Claude’s built-in “skill creator” skill.
Execute: Use the skill in your daily workflow for a period of time (e.g., a week).
Evaluate: Analyze the results. Identify where the skill falls short, produces annoying or incorrect output, or misses edge cases. The JSONL log files of your conversations are a rich source for this analysis.
Refine: Improve the skill based on your evaluation. You can even ask the LLM to review your conversation history and suggest improvements or entirely new skills to automate repetitive patterns.

Beyond the Editor: A Broad and Growing Ecosystem

Skills are not limited to a single model or development environment. They represent an emerging standard for packaging and distributing agentic workflows.

Cross-Platform: They work across various hosts, including Claude, Cursor, and Copilot, as well as in desktop and web applications.
Sharing with Non-Technical Users: A skill directory can be zipped and renamed with a .skill extension. This file can then be dragged and dropped into an application like Claude Desktop, making it easy to share powerful, automated workflows with non-technical team members, as demonstrated with a recruiting team use case.
Creative Applications: The talk showcased skills for non-coding tasks, such as generating a marketing video with Remotion, creating animated videos from a single text prompt using image generation APIs, and automating the creation of Linear tickets from Slack messages to reduce context switching.
Programmatic Use: Skills can be integrated into applications via tools like the Claude Agent SDK, allowing developers to ship products with sophisticated, AI-driven features powered by a shared skill library.