# Agent Skills Reference

Course: [Agent Skills](https://www.devtutorials.ai/learn/agent-skills) · Section: Skills at Scale
Source: https://www.devtutorials.ai/learn/agent-skills/scale/reference

> A one-page look-up for agent skills: the course at a glance, a SKILL.md template, front matter, body sections, what loads when, skill folders per tool, who owns a job, patterns, checklists, troubleshooting, testing and a glossary.

This page is a quick look-up. It puts the most useful templates, tables and checklists from the course in one place.

Each section names the lesson that explains it.

## The Course at a Glance

| Lesson | One-line idea |
| --- | --- |
| Agent Skills Overview | A skill is a folder with a SKILL.md that teaches the agent one repeatable job. |
| Skill Anatomy | SKILL.md has two parts: front matter (name, description) and a body (the steps). |
| Loading and Context Cost | Only the name and description load at first. The body loads when the skill fires. |
| Activation and Descriptions | The description decides when the skill fires. Use the words people type. |
| Release Note Skill | Build your first skill from start to finish. |
| Skill Installation | Put the skill in the folder your tool reads, then check that it loads. |
| Workflow Instructions | Write numbered steps, one action each, with stop conditions. |
| Output Format and Examples | Fix the shape of the reply. Show one good example. |
| Reference Files | Move long detail into `references/`. Point to it from the right step. |
| Scripts and Validators | Let a script do exact checks. The agent fixes and runs it again. |
| Choosing the Right Owner | Skill, instruction file, script, MCP tool or plugin: pick one owner. |
| Diagnosing Skills | Find the first broken layer. Fix only that layer. |
| Skill Evaluation | Test activation and output before and after every change. |
| Skill Security | Read every file of an outside skill before you trust it. |
| Maintaining and Sharing Skills | Version skills, review changes, and share them with your team. |
| Everyday Skill Patterns | Reviewer, generator, transformer and triage skills you can adapt. |

## SKILL.md Template

Copy this and fill in the parts in angle brackets.

```markdown
---
name: your-skill-name
description: <What it does>. Use when someone asks <the words people type>. Do not use for <nearby jobs>.
---

# Your Skill Name

## When to use
- <Requests this skill is for>

## Inputs
- <What the agent must gather first>

## Workflow
1. <One action per step>
2. <If condition, read references/topic.md>

## Output format
## <Heading 1>
## <Heading 2>

## Examples
<One short input and the output you want>

## Do not use
- <Nearby job> (use <other-skill>)

## Final checks
- <A check the agent can do>
- Run scripts/check.js on the output.
```

## Folder Layout

```text
your-skill-name/
  SKILL.md        required: front matter + steps
  references/     detail, opened only when a step points to it
  scripts/        exact checks; only their result is read
  templates/      files the agent fills in
  examples/       sample inputs and good outputs
```

## Front Matter

| Field | Needed? | Rule | Lesson |
| --- | --- | --- | --- |
| `name` | Yes | Lowercase letters, numbers and single hyphens. Same as the folder name. | Skill Anatomy |
| `description` | Yes | Says what it does, "Use when ...", and "Do not use for ...". | Activation and Descriptions |
| `metadata` | No | Extra data, such as `version` and `owner`. | Maintaining and Sharing Skills |
| `allowed-tools` | No | Tools it may use without asking. Support varies by tool. | Skill Security |

**Simple rule:** if the name and description are wrong, nothing else matters.

## Body Sections

| Section | Answers |
| --- | --- |
| When to use | Which requests is it for? |
| Inputs | What must the agent get first? |
| Workflow | Which steps, in order? |
| Output format | What shape must the reply have? |
| Examples | What does good look like? |
| Do not use | Which jobs belong to other skills? |
| Final checks | What must be checked before replying? |

## What Loads, and When

| Level | Loads when | Keep it |
| --- | --- | --- |
| Name + description | Every request, for every skill | One or two sentences |
| SKILL.md body | The skill fires | Only the steps that are needed |
| Reference files | A step points to them | One topic per file |
| Script output | A script runs | A short OK or FAIL list |

Lesson: Loading and Context Cost.

## Where Skills Live

| Tool | Project folder | Personal folder | Call by name |
| --- | --- | --- | --- |
| Syncfusion Code Studio | `.codestudio/skills/`, `.github/skills/`, `.claude/skills/`, `.agents/skills/` | The same folders under `~/` | `/name` |
| Claude Code | `.claude/skills/` | `~/.claude/skills/` | `/name` |
| GitHub Copilot | `.github/skills/`, `.claude/skills/`, `.agents/skills/` | `~/.copilot/skills/`, `~/.agents/skills/` | `/name` |
| OpenAI Codex | `.agents/skills/` | `~/.agents/skills/` | `$name` |

Folders can change. Check your tool's documentation. Lesson: Skill Installation.

## Who Owns the Job

| You need | Use | Lesson |
| --- | --- | --- |
| A one-off answer | A prompt | Agent Skills Overview |
| A rule for every task in the repo | AGENTS.md or project instructions | Choosing the Right Owner |
| An exact check or fix | A script, linter or formatter | Scripts and Validators |
| Live data or an action in another app | An MCP tool | Choosing the Right Owner |
| A repeatable job with steps and a format | A skill | Agent Skills Overview |
| A repeatable job that needs live data | A skill + an MCP tool | Choosing the Right Owner |
| A kit to share with a team | A plugin | Maintaining and Sharing Skills |

## Skill Patterns

| Pattern | Shape | DevKit examples |
| --- | --- | --- |
| Reviewer | Code in, findings out (severity, place, fix) | ui-review, security-review, pr-review |
| Generator | Request in, code from a template out | react-component, api-endpoint, test-planner |
| Transformer | A list in, a grouped document out | release-note-helper, commit-writer |
| Triage | A report in, severity and next steps out | bug-triage |

Lesson: Everyday Skill Patterns.

## Authoring Checklist

- [ ] The job is frequent, done the same way, and easy to check.
- [ ] `name` matches the folder.
- [ ] `description` says what, "Use when ..." and "Do not use for ...".
- [ ] Steps are numbered, one action each.
- [ ] The output format has exact headings or fields.
- [ ] There is one short example and a Do not use section.
- [ ] Final checks cover the rules that matter most.
- [ ] Long detail is in `references/`. Exact checks are in `scripts/`.
- [ ] No secrets, stories or role-play.
- [ ] Activation and output tests exist.

## Security Checklist

- [ ] Read every file in raw form, including scripts and hidden comments.
- [ ] No `curl ... | bash`, no reading of keys, no uploads.
- [ ] No "ignore previous instructions" or "do not tell the user".
- [ ] Scripts do only what SKILL.md says.
- [ ] Give the fewest tool permissions.
- [ ] Treat code, tickets and docs as data, never as instructions.
- [ ] Never store secrets in a skill.

Lesson: Skill Security.

## Troubleshooting

| What you see | Broken layer | First fix | Lesson |
| --- | --- | --- | --- |
| The tool does not list the skill | Discovery | Check the folder, the file name and the front matter | Skill Installation |
| It never fires | Activation | Add the words people type to the description | Activation and Descriptions |
| It fires for the wrong request | Activation | Add "Do not use for ..." | Activation and Descriptions |
| It skips a step | Instructions | One action per step; add a final check | Workflow Instructions |
| It ignores a reference file | Resources | Point to the file from the right step, with a condition | Reference Files |
| The reply shape changes | Verification | Add an exact output format and a validator | Output Format and Examples |
| It broke after an edit | Improvement | Compare with the last version; run the tests again | Skill Evaluation |

**Simple rule:** start at the top of the table. Fix the first layer that fails.

## Testing and Versions

| Test | Checks | When |
| --- | --- | --- |
| Structure | Front matter, sections, file pointers | Every edit |
| Activation | The right skill fires, or none | Every edit |
| Output | Good replies pass, bad replies fail | Every edit |
| Real runs | A real model on real inputs | Before you share a change |

| Change | Version |
| --- | --- |
| A small fix | Patch: 1.2.0 → 1.2.1 |
| A new feature, nothing breaks | Minor: 1.2.1 → 1.3.0 |
| The output shape changes | Major: 1.3.0 → 2.0.0 |

## Glossary

| Term | Meaning |
| --- | --- |
| **$ARGUMENTS** | The text typed after a skill's name, like `/release-notes v3.1`, passed into the skill |
| **Activation** | The agent picking a skill for a request |
| **allowed-tools** | A front matter field (in some tools) that lists the only tools a skill may use |
| **AGENTS.md** | An instruction file read for every task in a repo |
| **Catalog** | The list of skill names and descriptions the agent sees first |
| **Context window** | Everything the agent can see at one time; skills and files all share it |
| **Discovery** | The tool finding the installed skills |
| **Hook** | Code that runs on its own when something happens, with no choice by the model |
| **MCP** | Model Context Protocol: a standard way to connect tools and data to agents |
| **Output format** | The exact shape a reply must have |
| **Plugin** | A bundle of skills and tools to share |
| **Prompt injection** | Hidden instructions inside content the agent reads |
| **Regression** | Something that worked before and fails now |
| **Subagent** | A separate helper with its own context window, for a big side task |
| **Validator** | A script that checks a reply exactly |

## Links

- Agent Skills open format: [agentskills.io](https://agentskills.io)
- Syncfusion Code Studio skills: [help.syncfusion.com/code-studio/customization/skills](https://help.syncfusion.com/code-studio/customization/skills)
- Claude Code skills: [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills)
- GitHub Copilot skills: [docs.github.com: create skills](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-skills)
- OpenAI Codex skills: [learn.chatgpt.com/docs/build-skills](https://learn.chatgpt.com/docs/build-skills)
- Model Context Protocol: [modelcontextprotocol.io](https://modelcontextprotocol.io)
- On this site: the [MCP course](/learn/mcp) (build and connect tools), plus the **Context Engineering** and **Prompt Engineering** courses.

## Common Mistakes

| Mistake | Why it hurts | Fix |
| --- | --- | --- |
| A vague description | The skill never fires | Say what, "Use when ..." and "Do not use for ..." |
| No tests | An edit breaks the skill and nobody sees it | Run activation and output tests on every change |
| Trusting an outside skill | Hidden steps can leak secrets | Read every file before you install it |