agentleFS
Sign inStart free
Microsoft AzureKnown publisherAzure/azure-sdk-tools/.github/skills/skill-authoring/SKILL.md

skill-authoring

Skill135 starsChanged 2 months agoMITView on GitHub

Write 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". DO NOT USE FOR: general documentation. INVOKES: vally CLI.

We split this skill into the rules it gives an agent

10 rules. 0 are common, 1 is distinctive, and 9 are very specific to this project.

  • 0

    Common

    Most of the 68 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 9

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    USE FOR: write Agent Skills that comply with the agentskills.io specification.

    line 17
  2. Very specific:

    WHEN: "create a skill", "new skill", "write a skill", "skill template", "skill structure", "review skill", "skill PR", "skill compliance", …

    line 18
  3. Distinctive:

    DO NOT USE FOR: general documentation

    line 19
  4. Very specific:

    Use WHEN: with quoted trigger phrases (preferred over USE FOR:)

    line 25
  5. Very specific:

    run npm ci in .github/skills to install dependencies

    line 37
  6. Very specific:

    run npm run format to auto-format markdown and yaml files using Prettier

    line 38
  7. Very specific:

    Create skill directory with SKILL.md

    line 54
  8. Very specific:

    Add frontmatter: name, description, license

    line 55
  9. Very specific:

    Run vally lint {skill-name} to validate

    line 56
  10. Very specific:

    If vally lint reports broken links, verify reference file paths match exactly.

    line 65

“Common” is measured: kept by at least 6 in 10 of the 68 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Skill Authoring Guide

This skill helps write Agent Skills that comply with the agentskills.io specification by defining valid frontmatter, structure, and routing patterns, while guiding authors toward compliant SKILL.md files, supporting references, and local validation with the vally CLI.

Triggers

USE FOR: write Agent Skills that comply with the agentskills.io specification; skill template; skill structure; review skill; skill PR; skill compliance; SKILL.md format; skill frontmatter; skill best practices 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" DO NOT USE FOR: general documentation

Rules

  • name: 1-64 chars, lowercase + hyphens, match directory
  • description: inline double-quoted, ≤60 words, ≤1024 chars
  • Use WHEN: with quoted trigger phrases (preferred over USE FOR:)
  • SKILL.md: <500 tokens (soft), <5000 (hard)
  • references/*.md: <1000 tokens each

Structure

  • SKILL.md (required) — Frontmatter + instructions
  • references/ (optional) — Detailed docs, loaded on demand
  • scripts/ (optional) — Executable code

Formatting

  • run npm ci in .github/skills to install dependencies
  • run npm run format to auto-format markdown and yaml files using Prettier

Progressive Disclosure

Metadata loads at startup. SKILL.md on activation. References load when linked via markdown link.

MCP Tools

ToolPurpose
NoneCLI-only; uses local file tools

CLI fallback: Primary mode is CLI-based. No MCP servers required.

Steps

  1. Create skill directory with SKILL.md
  2. Add frontmatter: name, description, license
  3. Run vally lint {skill-name} to validate

Examples

  • "Create a new skill for code review"
  • "Review my skill for compliance"

Troubleshooting

If vally lint reports broken links, verify reference file paths match exactly.

References

  • Guidelines — Writing and structure
  • Validation — Checks and procedures
  • Reference Guide — Budgets, loading, checklist

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free