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.

referencesvalidationout-of-place.md

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

Out-of-Place Guidance Detection

Identify guidance that seems misplaced - typically when generic content contains very specific technology or service references.

Indicators

  • Generic workflow steps with service-specific workarounds embedded
  • Platform-agnostic instructions mentioning a particular Azure service
  • General azd commands followed by special handling for one service
  • Troubleshooting for a specific resource type in a general skill
  • Service-specific environment variables in generic setup docs

Examples

Context Misplaced Content Why It's Misplaced
Generic azd up workflow "Note: For Cosmos DB, add --no-prompt flag" Service-specific workaround in generic flow
General authentication docs "If using Azure SQL, also grant db_owner role" SQL-specific step in auth overview
Container Apps deployment "Redis requires minimum 1GB memory allocation" Redis-specific detail in general deploy
Generic error handling "PostgreSQL connections may timeout after 30s" DB-specific behavior in general errors

Procedure

  1. Review skill content for technology/service keywords
  2. Check if the surrounding context is generic or service-specific
  3. Flag content where specificity level mismatches context
  4. Determine if the content should be moved or the skill scope narrowed

When out-of-place guidance found, ask user:

  • a) Extract to service-specific reference - Move to references/services/<service>.md
  • b) Create new skill - If content warrants its own skill
  • c) Add conditional section - Create "Service-Specific Notes" section
  • d) Keep as-is - If the specificity is justified in context
  • e) Something else - User provides alternative action

Extraction pattern

# Before (in generic workflow)
## Deploy Application
1. Run `azd up`
2. Wait for provisioning
3. Note: For Cosmos DB deployments, set throughput before deploy
4. Verify deployment

# After
## Deploy Application
1. Run `azd up`
2. Wait for provisioning
3. Verify deployment

See [Service-Specific Notes](references/services/README.md) for service-specific considerations.

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.