---
id: sm-skill-authoring
name: "skill-authoring"
url: https://skills.yangsir.net/skill/sm-skill-authoring
author: microsoft
domain: ai-skill-platform-ecosystem
tags: ["ai-agent-development", "prompt-engineering", "llm-customization", "skill-definition-language", "ai-workflow-automation"]
install_count: 942
rating: 4.20 (38 reviews)
github: https://github.com/microsoft/github-copilot-for-azure
---

# skill-authoring

> 专注于AI工程领域的技能创作，利用GitHub Copilot for Azure等工具辅助开发和优化。

**Stats**: 942 installs · 4.2/5 (38 reviews)

## Before / After 对比

### Agent技能编写规范与合规性

| Metric | Before | After | Change |
|---|---|---|---|
| - | - | - | - |
| - | - | - | - |
| - | - | - | - |

## Readme

# skill-authoring

# Skill Authoring Guide

This skill provides guidance for writing Agent Skills that comply with the [agentskills.io specification](https://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](https://github.com/microsoft/github-copilot-for-azure/blob/HEAD/.github/skills/skill-authoring/references/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:

- **No broken links** - All referenced files exist

- **No orphaned references** - All reference files are linked

- **Token budgets** - References under 1000 tokens (split if exceeded)

- **No duplicates** - Consolidate repeated content

- **No out-of-place guidance** - Service-specific content belongs in service-specific references

See [Validation](https://github.com/microsoft/github-copilot-for-azure/blob/HEAD/.github/skills/skill-authoring/references/validation/README.md) for detailed procedures.

## Reference Documentation

- [Guidelines](https://github.com/microsoft/github-copilot-for-azure/blob/HEAD/.github/skills/skill-authoring/references/guidelines/README.md) - Detailed writing guidelines

- [Token Budgets](https://github.com/microsoft/github-copilot-for-azure/blob/HEAD/.github/skills/skill-authoring/references/token-budgets.md) - Limits and splitting guidance

- [Reference Loading](https://github.com/microsoft/github-copilot-for-azure/blob/HEAD/.github/skills/skill-authoring/references/REFERENCE-LOADING.md) - How references load

- [Checklist](https://github.com/microsoft/github-copilot-for-azure/blob/HEAD/.github/skills/skill-authoring/references/CHECKLIST.md) - Pre-submission checklist

- [Validation](https://github.com/microsoft/github-copilot-for-azure/blob/HEAD/.github/skills/skill-authoring/references/validation/README.md) - Link and reference validation

- [agentskills.io/specification](https://agentskills.io/specification) - Official spec

Weekly Installs292Repository[microsoft/githu…or-azure](https://github.com/microsoft/github-copilot-for-azure)GitHub Stars157First SeenFeb 3, 2026Security Audits[Gen Agent Trust HubPass](/microsoft/github-copilot-for-azure/skill-authoring/security/agent-trust-hub)[SocketPass](/microsoft/github-copilot-for-azure/skill-authoring/security/socket)[SnykPass](/microsoft/github-copilot-for-azure/skill-authoring/security/snyk)Installed oncodex270gemini-cli266opencode237github-copilot234cursor228kimi-cli227

---
*Source: https://skills.yangsir.net/skill/sm-skill-authoring*
*Markdown mirror: https://skills.yangsir.net/api/skill/sm-skill-authoring/markdown*