skill authoring
- Repo stars 205
- License MIT
- Author repo GitHub-Copilot-for-Azure
- Domain
- Writing
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 94 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @microsoft · MIT
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- macOS · Linux · Windows
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# 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](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](references/file.md)` load
- **Link to files, not folders** - `[Recipes](references/recipes/README.md)` not `[Recipes](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](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](references/validation/README.md) for detailed procedures.
## Reference Documentation
- [Guidelines](references/guidelines/README.md) - Detailed writing guidelines
- [Token Budgets](references/token-budgets.md) - Limits and splitting guidance
- [Reference Loading](references/REFERENCE-LOADING.md) - How references load
- [Checklist](references/CHECKLIST.md) - Pre-submission checklist
- [Validation](references/validation/README.md) - Link and reference validation
- [agentskills.io/specification](https://agentskills.io/specification) - Official spec
Sections and files
Listed in source order.
sections -> When to Use → Constraints → Structure → Progressive Disclosure → Reference Loading → Validation
terms -> only when explicitly linked · Link to files, not folders · No broken links · No orphaned references · Token budgets · No duplicates · No out-of-place guidance
files/cmd -> name · description · WHEN: · USE FOR: · DO NOT USE FOR: · references/ · scripts/ · [text](references/file.md)
body sha256 -> 32e398562805
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 directorydescription: 1-1024 chars, ≤60 words, explain WHAT and WHEN UseWHEN:with quoted trigger phrases (preferred overUSE FOR:) AvoidDO NOT USE FOR:unless the skill has trigger overlap with a broader skill (see frontmatter guidelines) Use inline double-quoted strings (not>-folded scalars)Structure
SKILL.md(required) - Instructionsreferences/(optional) - Detailed docsscripts/(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
textload Link to files, not folders -RecipesnotRecipesEach file loads in full (not sections) No caching between requests - write self-contained files