Get the FREE Ultimate OpenClaw Setup Guide →

skill-authoring

Scanned
npx machina-cli add skill microsoft/GitHub-Copilot-for-Azure/skill-authoring --openclaw
Files (1)
SKILL.md
3.2 KB

Skill Authoring Guide

This skill provides guidance for writing Agent Skills that comply with the 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:)
  • Do NOT use DO NOT USE FOR: (keyword contamination on Sonnet)
  • 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 for details.

Validation

# 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 for detailed procedures.

Reference Documentation

Source

git clone https://github.com/microsoft/GitHub-Copilot-for-Azure/blob/main/.github/skills/skill-authoring/SKILL.mdView on GitHub

Overview

The Skill Authoring Guide provides practical directions for writing Agent Skills that meet the agentskills.io specification. It covers when to create or review skills, naming and description constraints, frontmatter structure, and how content loads progressively. It helps teams validate skills with defined pipelines and ensures references stay linked and within token budgets.

How This Skill Works

Metadata loads at startup (~100 tokens) and SKILL.md loads on activation (<5000 tokens). References load only when explicitly linked. Validation is performed via npm scripts (npm run references and npm run tokens -- check) to enforce link integrity and token budgets.

When to Use It

  • Creating a new skill for the repository
  • Reviewing a skill PR for compliance
  • Checking if an existing skill follows best practices
  • Understanding token budgets and progressive disclosure
  • Preparing for SKILL.md validation and integrity checks

Quick Start

  1. Step 1: Ensure frontmatter name and description align with the directory and spec
  2. Step 2: Write SKILL.md with clear WHEN triggers and keep token budgets lean, moving long docs to references
  3. Step 3: From scripts/, run npm run references and npm run tokens -- check to validate links and budgets

Best Practices

  • Align name with directory: 1-64 characters, lowercase with hyphens
  • Keep description concise (1-1024 chars, ≤60 words) and clearly explain WHAT and WHEN
  • Use WHEN with quoted trigger phrases; avoid DO NOT USE FOR
  • Keep SKILL.md lean; store long content in references with explicit links
  • Run validation: check references, token budgets, and integrity before submission

Example Use Cases

  • Creating a skill-authoring SKILL.md for a new skill in the repository
  • Reviewing a PR to verify compliance with naming, description and frontmatter constraints
  • Auditing a skill for proper frontmatter and token budgets
  • Organizing references to stay under token budgets and ensuring JIT loading
  • Linking references explicitly via references/file.md to avoid folder links

Frequently Asked Questions

Add this skill to your agents
Sponsor this space

Reach thousands of developers ↗