skill-authoring

Name: skill-authoring
Author: microsoft

Writing Community

Repo stars 205
License MIT
Author repo GitHub-Copilot-for-Azure

Interpretation is structured for decision-making; original keeps the upstream SKILL.md unchanged.

Decide Fit First

Core job: Guidelines for writing Agent Skills that comply with the agentskills.io specification. WHEN: "create a skill", "new skill"…
Best fit: Use it when the task has reusable inputs, steps, and validation criteria rather than a one-off answer.
Avoid forcing it: If the source lacks commands, platform support, or external-service evidence, keep those fields unknown instead of guessing.

Design Intent

Structure: The skill is organized around “When to Use”, “Constraints”, “Structure”, “Progressive Disclosure”, showing how the author expects the agent to judge fit, collect context, and produce verifiable output.
Trigger evidence: Prioritize the author’s wording around when to use it, what context to collect, and what output shape to produce.
Evidence boundary: Author text states facts, repository files prove commands and paths, and Fluxly only adds fit, limits, and usage judgment.

How To Use It

Inputs: Provide target material, scope, expected result, forbidden changes, and validation method.
Invocation: Name skill-authoring directly; if the source includes slash commands, start with the command and then add task context.
Validation: Start small and check whether the result follows “When to Use / Constraints / Structure” before expanding.

Boundaries And Review

Dependencies: It usually needs no extra API key, so start with a small validation task.
Permissions: Declared permissions include read / write / shell-exec; ask the agent to state file, command, and rollback boundaries before acting.
Quality bar: A useful result names the deliverable, evidence, and next action. Generic prose means the task needs tighter context.

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:)
Avoid DO NOT USE FOR: unless the skill has trigger overlap with a broader skill (see frontmatter guidelines)
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:

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

Reference Documentation

Guidelines - Detailed writing guidelines
Token Budgets - Limits and splitting guidance
Reference Loading - How references load
Checklist - Pre-submission checklist
Validation - Link and reference validation
agentskills.io/specification - Official spec

Fluxly profile Author and license come from source; runtime, permissions, and network are Fluxly detections or estimates

Fluxly category: Writing
Author-declared agents: No explicit declaration found; this is not inferred or tested compatibility
Static check: 94 / 100 · heuristic scan, not runtime safety proof
Author / version / license: @microsoft · MIT
Fluxly token estimate: Lean
Fluxly setup estimate: Guided setup
External API key: No requirement detected
Detected OS requirements: macOS · Linux · Windows
Runtime requirements: Unspecified
Detected file/system behavior: Read-only
Write / modify
Shell exec
Detected network behavior: Local-only
Install commands: None (reference only)

Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.

Heads up: 未限定 allowed-tools，默认拥有全部工具权限。

Output preview skill-authoring-microsoft.preview

The current SKILL.md does not define a fixed output example.

SKILL.md SKILL.md

# 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:`)
- Avoid `DO NOT USE FOR:` unless the skill has trigger overlap with a broader skill (see [frontmatter guidelines](references/guidelines/frontmatter.md))
- 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](references/REFERENCE-LOADING.md) for details.

## Validation

```bash

…

Evidence boundary and execution chain

Author text anchors workflow facts; Fluxly only indexes current sections, terms, files, and commands.

sections -> When to Use → Constraints → Structure → Progressive Disclosure → Reference Loading → Validation
terms    -> only when explicitly linked · Link to files, not folders · No broken links · No orphaned references · Token budgets · No duplicates · No out-of-place guidance
files/cmd -> name · description · WHEN: · USE FOR: · DO NOT USE FOR: · references/ · scripts/ · [text](references/file.md)
body sha256 -> 32e398562805