skill-authoring
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".
85
81%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Quality
Discovery
89%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This description is strong in completeness and trigger term quality, with an explicit WHEN clause containing a rich set of natural trigger phrases. Its main weakness is that the 'what' portion is somewhat vague — it says 'guidelines for writing Agent Skills' but doesn't enumerate specific concrete actions like validating frontmatter, generating templates, or checking compliance rules. Overall it would perform well in skill selection scenarios.
Suggestions
Expand the 'what' portion with specific concrete actions, e.g., 'Generates skill templates, validates YAML frontmatter, checks compliance with the agentskills.io specification, and reviews skill structure.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names the domain ('Agent Skills' complying with 'agentskills.io specification') and implies actions like writing and reviewing skills, but doesn't list multiple concrete actions (e.g., 'validates frontmatter fields, generates YAML metadata, checks compliance rules'). | 2 / 3 |
Completeness | Clearly answers both 'what' (guidelines for writing Agent Skills complying with agentskills.io spec) and 'when' (explicit WHEN clause with a comprehensive list of trigger phrases). | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger terms users would say: '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'. These are highly natural and varied. | 3 / 3 |
Distinctiveness Conflict Risk | Very distinct niche — specifically about the agentskills.io specification and SKILL.md format. The trigger terms are highly specific to this domain and unlikely to conflict with other skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
72%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured, concise skill that effectively uses progressive disclosure to keep the main file lean while pointing to detailed references. Its main weaknesses are the lack of a concrete copy-paste template/example for skill authoring and the absence of an explicit end-to-end workflow with feedback loops for the authoring process.
Suggestions
Add a concrete, copy-paste-ready example of a minimal SKILL.md (with frontmatter and body) to improve actionability.
Add an explicit end-to-end authoring workflow with numbered steps and a validate-fix-retry feedback loop (e.g., 1. Create directory → 2. Write SKILL.md → 3. Run validation → 4. If errors, fix and re-validate → 5. Submit PR).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and efficient. It avoids explaining concepts Claude already knows, uses terse constraint lists, and every section earns its place. No unnecessary preamble or padding. | 3 / 3 |
Actionability | Provides concrete validation commands and specific constraints (token limits, naming rules), but much of the guidance is directional rather than executable. For example, the structure section describes what goes where but doesn't show a concrete example of a well-formed SKILL.md frontmatter or a template to copy-paste. | 2 / 3 |
Workflow Clarity | The validation section provides a numbered checklist of integrity checks, and there are bash commands for validation. However, the overall authoring workflow (create → write → validate → fix → submit) is not explicitly sequenced with feedback loops. The integrity checks list steps but don't include explicit error recovery or a 'fix and re-validate' loop. | 2 / 3 |
Progressive Disclosure | Excellent progressive disclosure with a concise overview in SKILL.md and well-signaled, one-level-deep references to guidelines, token budgets, reference loading, checklist, and validation docs. Navigation is clear and appropriately structured. | 3 / 3 |
Total | 10 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- microsoft/github-copilot-for-azure
- Commit
a46a937
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.