skilld
All skills
microsoft avatar

/skill-authoring

@70c03ac official
by microsoftmicrosoft/github-copilot-for-azure253 stars
206

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".

Ask your Agent

Use this Skill: https://skilld.dev/gh/microsoft/github-copilot-for-azure/skill-authoring

This session only. Nothing lands on disk.

referencesvalidationREADME.md

≈331 tokens on demand. Your agent reads this file only when SKILL.md points to it.

Skill Validation Procedures

Run these validations when reviewing or authoring skills.

Automated Validation

cd scripts
npm run references              # Check broken links and cross-skill escapes
npm run tokens -- check         # Check token limits

Validations

# Check Description
1 Broken Links Verify all markdown links point to existing files (not folders)
2 Orphaned References Find unreferenced files in references/
3 Token Splitting Split references exceeding 1000 tokens
4 Duplicate Content Consolidate repeated content
5 Out-of-Place Guidance Find misplaced service-specific content

Quick Checklist

Check Action if Failed
Broken links Fix path, add /README.md for folder links, or delete
Folder links Change to file links (e.g., recipes/ → recipes/README.md)
Orphaned references Delete, add link, or user decision
References >1000 tokens Split into folder with README.md
Duplicate content Consolidate into shared reference
Out-of-place guidance Extract, create skill, add section, or user decision

Source: SKILL.md on GitHub

Third-party checks

No alerts15d5 checks · Risk SAFE
  • Gen Agent Trust Hub15d

    This skill is a comprehensive documentation and validation guide for authoring agent skills. It follows security best practices and contains no identified threats.

  • Socket15d

    No alerts

  • Snyk15d

    Risk: LOW · No issues

  • Runlayer7mo

    14 files scanned · No issues

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at 70c03ac. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 6 months ago

Capability

metadata
{
  "author": "Microsoft",
  "version": "1.0.1"
}

Topics

  • Documentation
  • skill-authoring
  • specification
  • agentskills
  • guidelines
  • frontmatter
  • validation

README badge

README badge for microsoft/github-copilot-for-azure/skill-authoring

What it does

Provides guidelines for authoring Agent Skills that comply with the agentskills.io specification, including frontmatter structure, token budgets, progressive disclosure patterns, and validation procedures. Use this when creating a new skill, reviewing a skill PR for compliance, or checking if a skill follows best practices.

Generated from the current SKILL.md.

Frequently asked

What are the token limits for a skill?
SKILL.md must stay under 5000 tokens (soft limit ~500), and each reference file under 1000 tokens. References load only when explicitly linked, not on activation.
What should the description field contain?
The description must explain WHAT the skill does and WHEN to use it, be ≤60 words, and include a WHEN: clause with quoted trigger phrases.
How do references get loaded?
References are just-in-time loaded only when explicitly linked via [text](references/file.md) in the SKILL.md. Link to files, not folders, and each file loads in full.
What structure should a skill have?
A skill requires SKILL.md with frontmatter (name, description) and instructions. References and scripts directories are optional for detailed docs and executable code.
How do I validate my skill before submission?
Run npm run references to check for broken links and npm run tokens -- check to verify token limits. Use the checklist in references/CHECKLIST.md before submitting.

Generated from the current SKILL.md. These answers refresh after source changes.