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.

referencesCHECKLIST.md

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

Skill Submission Checklist

Use this checklist before submitting a new skill or updating an existing one.

Frontmatter Validation

  • name field is present and 1-64 characters
  • name uses only lowercase letters, numbers, and hyphens
  • name does not start or end with a hyphen
  • name matches the parent directory name
  • name does not start with claude- or anthropic- (reserved)
  • description field is present and 1-1024 characters
  • description explains WHAT the skill does
  • description explains WHEN to use it (use WHEN: with quoted trigger phrases)
  • description does NOT contain DO NOT USE FOR: (risky in multi-skill environments — see SCORING.md check 4)
  • description is ≤ 60 words (cross-model density)
  • description uses inline double-quoted string (not >- folded scalar)
  • No XML angle brackets (< >) in frontmatter

Token Budget

See Token Budgets for detailed limits.

  • SKILL.md is under 500 tokens (soft limit)
  • SKILL.md is under 5000 tokens (hard limit per spec)
  • Reference files are each under 1000 tokens
  • Run npm run tokens -- check from scripts/ directory

Structure

  • SKILL.md exists in the skill root directory
  • Optional references/ directory for detailed docs
  • Optional scripts/ directory for executable code
  • Optional assets/ directory for templates/data
  • File references use relative paths from skill root
  • No deeply nested reference chains

Link and Reference Integrity

  • All markdown links point to existing files (no broken links)
  • All files in references/ are linked from SKILL.md or other references (no orphans)
  • References >1000 tokens are split into folder with README.md
  • Duplicate content is consolidated into shared references
  • No out-of-place guidance (service-specific content in generic sections)

Content Quality

  • Instructions are action-oriented (step-by-step)
  • Has examples section (input → expected output)
  • Has error handling (common failures and recovery)
  • Tables used for dense information
  • No decorative emojis (only functional ones if needed)
  • No repeated content across sections
  • Complex details moved to references/ files
  • Code examples are minimal and purposeful

Azure-Specific (for this repo)

  • Prefers Azure MCP tools over direct CLI commands
  • Uses azd where applicable
  • Lists relevant MCP tools in a "Tools Used" section
  • Includes troubleshooting section for common issues
  • Scripts include both bash and PowerShell versions (if non-trivial)

Testing

  • Skill activates correctly when relevant prompts are used
  • Referenced files exist and are accessible
  • Scripts execute without errors
  • MCP tools mentioned are available and documented

Final Steps

cd scripts
npm run references        # Validate all skill links
npm run tokens -- check   # Check token limits

If any checks fail, see Guidelines for guidance.

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.