Skip to main content
If you use AI agents in real work, you probably repeat the same setup steps over and over: explain the task, list rules, ask for formatting fixes, then iterate until the output is right. Skills let you package those repeated workflows so agents can reuse them without you retyping the same instructions every time. In this lesson we’ll cover agent skills — a folder-based way to package a reusable SKILL.md and optional supporting files. When a harness detects a request that matches a skill’s description, it loads that skill for the specific run and follows the instructions inside. Important: loading a skill does not change or retrain the underlying model — the harness simply places the skill content into the model’s context for that run.
A slide titled "What is a Skill?" defining it as a reusable set of instructions. It shows two side-by-side boxes comparing "A Prompt" (manual, one-off) with "A Skill" (packaged, versionable) with a red "vs" arrow between them.
What a skill captures
  • A prompt that already works.
  • The decisions and rules your team needs followed.
  • References, templates, and scripts the workflow requires.
By packaging these into a skill, the workflow becomes repeatable, versionable, and shareable across teammates or systems. How the harness chooses a skill
  • The harness keeps a small catalog consisting of each skill’s name and description (YAML front matter). These fields stay in the routing context to decide matches.
  • The full SKILL.md body is not loaded into context until the harness determines a match.
  • When a match occurs, the harness loads the skill body and then opens referenced files or executes allowed scripts on demand.
This progressive loading prevents dozens of skills from consuming the model’s context at startup. On-disk layout and naming conventions
  • Name the folder using lowercase, numbers, and hyphens to match discovery rules.
  • The required file is SKILL.md (uppercase).
  • Optional top-level directories: references/, scripts/, and assets/.
Example structure:
Quick reference table for common top-level contents: References can provide one-shot or few-shot examples. Scripts run checks or transformations. Assets supply templates or visual resources. None of these are loaded until the skill requests them. When to build a skill Build a skill when you find yourself repeating the same steps or when outputs must follow strict rules:
  • Repeating tasks (weekly reports, meeting summaries).
  • Tasks with strict formatting or compliance rules.
  • Outputs that must match a team voice or brand.
  • Processes multiple people should follow consistently.
A dark-themed slide titled "When to Build a Skill" with the subtitle "Build one if you keep explaining the same work." Four boxed points list reasons: Repeating Tasks, Specific Rules or Formatting, Tone and Clarity, and Sharing Within Your Team.
For one-off or exploratory questions, a normal prompt remains appropriate. Skills show their value when the workflow repeats and consistency matters. Authoring a skill (don’t start from scratch unless you want to) You can draft the first version yourself or use an agent to bootstrap it. Provide the workflow, an example result, then review and test the generated SKILL.md. If you have an existing chat with many instructions, ask the agent to convert that conversation into a skill — it often produces a good starting point. Security and trust Treat downloaded skills like any third-party package. Inspect the SKILL.md, review scripts, and confirm any requested network or file access before running.
Always review the source and any executable scripts before running a downloaded skill. Verify that requested permissions and external network access are safe for your environment.
Installing skills Install by downloading, cloning, or using an installer. Example CLI:
Always review the skill contents before enabling or running it. Concrete example: a helpdesk support skill This example skill drafts support ticket replies according to your team’s rules and tone. Typical flow:
  • User: “Reply to this ticket.”
  • Harness: matches the request to helpdesk-replies.
  • Skill: reads the ticket, checks policy rules, drafts a reply.
  • Human: reviews and approves the draft before sending.
Local folder:
If the initial input is vague, the skill’s output will likely be vague — define inputs clearly in your SKILL.md. SKILL.md structure and best practices SKILL.md should include YAML front matter followed by the Markdown body with the instructions the harness will execute. Required front matter keys:
  • name — use the folder name and stick to lowercase, numbers, and hyphens.
  • description — the main routing field; include likely trigger phrases users will use.
Optional metadata:
  • license, author, version, compatibility
  • allowed_tools or pre-approvals (client support varies)
Example front matter:
Recommended sections in the body (not required, but helpful)
  • When to Use — trigger conditions.
  • Inputs — what data is required (ticket text, customer name, priority).
  • Workflow — ordered, imperative steps the agent should follow.
  • Rules — mandatory formatting and policy constraints.
  • Output — what the finished deliverable should look like; include explicit examples.
  • Edge Cases — handling missing data, escalation rules, sensitivity checks.
A dark-themed presentation slide titled "Write the Body for Execution" showing six labeled boxes — When to Use, Inputs, Workflow, Rules, Output, and Edge Cases — each with a short instruction. The footer reads "AI Foundations for Technical Professionals" with the author's name.
Progressive disclosure: what loads and when
  • Level 1 — name and description: kept available for routing.
  • Level 2 — SKILL.md body: loaded when the skill is activated.
  • Level 3 — supporting materials (references/, scripts/, assets/): loaded or executed on demand.
Keep SKILL.md focused and compact (recommendation: under ~500 lines) and move heavy content into supporting files to minimize context load.
A dark-themed slide titled "Split Detail by When It's Needed" explaining progressive disclosure for SKILL.md (name + description, SKILL.md body, supporting files). The right side lists example helpdesk files and notes about workflow, tone, reply templates, and guidelines.
Example referenced files (place these at top-level and call them directly from SKILL.md):
Best practice: instruct the agent exactly when to open referenced files (for example: “Read references/tone-guide.md before drafting the reply.”). Avoid chained references (A -> B -> C); prefer top-level direct references to reduce context consumption and simplify debugging. Build process in four steps
  1. Name the job (folder + SKILL.md).
  2. Write the description (what it does and when it triggers).
  3. Define the task: inputs, ordered workflow steps, rules, outputs.
  4. Split heavy or complex parts into references/, scripts/, and assets/.
A dark presentation slide titled "Build It in Four Easy Steps" with four numbered boxes connected by red arrows. Each box lists a step: 01 Name the job; 02 Write the description; 03 Define the task; 04 Split up the complex parts.
Testing and iteration
  • Test with real tickets and edge cases (missing fields, unusual requests, policy conflicts).
  • If the skill never triggers: broaden the description with realistic phrases users might use.
  • If the skill triggers too often: narrow the description and add disambiguating phrases.
  • Iterate on SKILL.md and supporting files based on observed behavior.
Summary When the same instructions keep repeating, build a skill. Put the workflow in SKILL.md, keep the main file focused, move larger materials into references/, scripts/, and assets/, and iterate after testing. A demo follows that builds a working example. Links and references

Watch Video