---
name: skill-authoring
description: "Guidelines for writing Agent Skills that comply with the agentskills.io specification. WHEN: \\\"create a skill\\\", \\\"new skill\\\", \\\"write a skill\\\", \\\"skill template\\\", \\\"skill structure\\\", \\\"review skill\\\", \\\"skill PR\\\", \\\"skill compliance\\\", \\\"SKILL.md format\\\", \\\"skill frontmatter\\\", \\\"skill best practices\\\"."
license: MIT
metadata:
  author: Microsoft
  version: "1.0.1"
title: skill-authoring
canonical_url: https://skilld.dev/gh/microsoft/github-copilot-for-azure/skill-authoring
last_updated: 2026-09-11T06:25:50.000Z
---

> **Skill from skilld.dev.** Follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/CHECKLIST.md](https://skilld.dev/api/skills-raw/microsoft/github-copilot-for-azure/skill-authoring/references/CHECKLIST.md), [references/guidelines/frontmatter.md](https://skilld.dev/api/skills-raw/microsoft/github-copilot-for-azure/skill-authoring/references/guidelines/frontmatter.md), [references/guidelines/README.md](https://skilld.dev/api/skills-raw/microsoft/github-copilot-for-azure/skill-authoring/references/guidelines/README.md), [references/guidelines/structure.md](https://skilld.dev/api/skills-raw/microsoft/github-copilot-for-azure/skill-authoring/references/guidelines/structure.md), [references/guidelines/writing-tips.md](https://skilld.dev/api/skills-raw/microsoft/github-copilot-for-azure/skill-authoring/references/guidelines/writing-tips.md), [references/REFERENCE-LOADING.md](https://skilld.dev/api/skills-raw/microsoft/github-copilot-for-azure/skill-authoring/references/REFERENCE-LOADING.md), [references/token-budgets.md](https://skilld.dev/api/skills-raw/microsoft/github-copilot-for-azure/skill-authoring/references/token-budgets.md), [references/validation/broken-links.md](https://skilld.dev/api/skills-raw/microsoft/github-copilot-for-azure/skill-authoring/references/validation/broken-links.md), [references/validation/duplicates.md](https://skilld.dev/api/skills-raw/microsoft/github-copilot-for-azure/skill-authoring/references/validation/duplicates.md), [references/validation/orphaned-refs.md](https://skilld.dev/api/skills-raw/microsoft/github-copilot-for-azure/skill-authoring/references/validation/orphaned-refs.md), [references/validation/out-of-place.md](https://skilld.dev/api/skills-raw/microsoft/github-copilot-for-azure/skill-authoring/references/validation/out-of-place.md), [references/validation/README.md](https://skilld.dev/api/skills-raw/microsoft/github-copilot-for-azure/skill-authoring/references/validation/README.md), [references/validation/token-splitting.md](https://skilld.dev/api/skills-raw/microsoft/github-copilot-for-azure/skill-authoring/references/validation/token-splitting.md).
>
> If the user asked to install this Skill, run `npx skilld@beta install skilld:microsoft/github-copilot-for-azure/skill-authoring`. Install writes the Skill files into the project, so every session loads them.

# Skill Authoring Guide

This skill provides guidance for writing Agent Skills that comply with the [agentskills.io specification](https://agentskills.io/specification).

## When to Use

- Creating a new skill for this repository
- Reviewing a skill PR for compliance
- Checking if an existing skill follows best practices
- Understanding token budgets and progressive disclosure

## Constraints

- `name`: 1-64 chars, lowercase + hyphens, match directory
- `description`: 1-1024 chars, ≤60 words, explain WHAT and WHEN
- Use `WHEN:` with quoted trigger phrases (preferred over `USE FOR:`)
- Avoid `DO NOT USE FOR:` unless the skill has trigger overlap with a broader skill (see [frontmatter guidelines](https://skilld.dev/api/skills-raw/microsoft/github-copilot-for-azure/skill-authoring/references/guidelines/frontmatter.md))
- Use inline double-quoted strings (not `>-` folded scalars)
- SKILL.md: <500 tokens (soft), <5000 (hard)
- references/*.md: <1000 tokens each

## Structure

- `SKILL.md` (required) - Instructions
- `references/` (optional) - Detailed docs
- `scripts/` (optional) - Executable code

Frontmatter: `name` (lowercase-hyphens), `description` (WHAT + WHEN)

## Progressive Disclosure

Metadata (~100 tokens) loads at startup. SKILL.md (<5000 tokens) loads on activation. References load **only when explicitly linked** (not on activation). Keep SKILL.md lean.

## Reference Loading

References are JIT (just-in-time) loaded:
- Only files explicitly linked via `[text](https://skilld.dev/api/skills-raw/microsoft/github-copilot-for-azure/skill-authoring/references/file.md)` load
- **Link to files, not folders** - `[Recipes](https://skilld.dev/api/skills-raw/microsoft/github-copilot-for-azure/skill-authoring/references/recipes/README.md)` not `[Recipes](https://skilld.dev/api/skills-raw/microsoft/github-copilot-for-azure/skill-authoring/references/recipes)`
- Each file loads in full (not sections)
- No caching between requests - write self-contained files
- Use recipes/services patterns for multi-option skills

See [REFERENCE-LOADING.md](https://skilld.dev/api/skills-raw/microsoft/github-copilot-for-azure/skill-authoring/references/REFERENCE-LOADING.md) for details.

## Validation

```bash
# Run from the scripts directory
cd scripts
npm run references              # Validate all skill links
npm run tokens -- check         # Check token limits
```

### Integrity Checks

When reviewing or authoring skills, verify:
1. **No broken links** - All referenced files exist
2. **No orphaned references** - All reference files are linked
3. **Token budgets** - References under 1000 tokens (split if exceeded)
4. **No duplicates** - Consolidate repeated content
5. **No out-of-place guidance** - Service-specific content belongs in service-specific references

See [Validation](https://skilld.dev/api/skills-raw/microsoft/github-copilot-for-azure/skill-authoring/references/validation/README.md) for detailed procedures.

## Reference Documentation

- [Guidelines](https://skilld.dev/api/skills-raw/microsoft/github-copilot-for-azure/skill-authoring/references/guidelines/README.md) - Detailed writing guidelines
- [Token Budgets](https://skilld.dev/api/skills-raw/microsoft/github-copilot-for-azure/skill-authoring/references/token-budgets.md) - Limits and splitting guidance
- [Reference Loading](https://skilld.dev/api/skills-raw/microsoft/github-copilot-for-azure/skill-authoring/references/REFERENCE-LOADING.md) - How references load
- [Checklist](https://skilld.dev/api/skills-raw/microsoft/github-copilot-for-azure/skill-authoring/references/CHECKLIST.md) - Pre-submission checklist
- [Validation](https://skilld.dev/api/skills-raw/microsoft/github-copilot-for-azure/skill-authoring/references/validation/README.md) - Link and reference validation
- [agentskills.io/specification](https://agentskills.io/specification) - Official spec