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.

referencestoken-budgets.md

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

Token Budget Guidelines

Central reference for token limits across all skill files.

Limits

File Type Soft Limit Hard Limit Action if Exceeded
SKILL.md 500 tokens 5000 tokens Split into references
references/*.md 1000 tokens 2000 tokens Split into folder with README.md
docs/*.md 1500 tokens 3000 tokens Restructure

Splitting Large References

When a reference exceeds 1000 tokens, convert to a folder structure:

# Before
references/large-guide.md    # 1500 tokens

# After
references/large-guide/
├── README.md                # Overview + links (~200 tokens)
├── section-1.md             # First section (~400 tokens)
└── section-2.md             # Second section (~400 tokens)

Update links: [guide](references/large-guide.md) → [guide](references/large-guide/README.md)

Validation

cd scripts
npm run tokens -- check plugins/{plugin}/skills/my-skill/SKILL.md

Why Token Limits Matter

Units note: Limits are measured in tokens (cl100k_base tokenizer), not words. Anthropic's Complete Guide says "under 5,000 words" while the Agent Skills spec says "< 5000 tokens." As a rough conversion: 5000 tokens ≈ 3,750 words. Token-based limits are stricter.

  • Metadata (~100 tokens): Loads at startup for ALL skills
  • SKILL.md (<5000 tokens): Loads entirely on activation
  • References: Load only when explicitly linked

Smaller files = faster activation, less context consumed.

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.