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 the specific actions the skill enables (e.g., generating templates, validating structure, reviewing compliance). The distinctiveness is excellent given the narrow domain.
Suggestions
Add specific concrete actions to the 'what' portion, e.g., 'Generates skill templates, validates YAML frontmatter, checks compliance with the agentskills.io specification, and structures SKILL.md files.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | It 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., 'validate frontmatter fields, generate YAML metadata, structure markdown sections'). | 2 / 3 |
Completeness | Clearly answers both 'what' (guidelines for writing Agent Skills compliant 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 specific niche — Agent Skills conforming to the agentskills.io specification. The trigger terms are highly domain-specific ('SKILL.md format', 'skill frontmatter', 'skill compliance') 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 skill that effectively uses progressive disclosure and maintains good conciseness. Its main weaknesses are the lack of concrete examples (e.g., a sample frontmatter block or minimal SKILL.md template) and the absence of an explicit step-by-step authoring workflow with validation feedback loops. The reference organization is exemplary.
Suggestions
Add a concrete example of well-formed frontmatter YAML and a minimal SKILL.md template to improve actionability (e.g., a copy-paste-ready skeleton).
Add an explicit numbered workflow for creating a new skill from scratch (create directory → write frontmatter → write body → add references → validate → fix errors → re-validate) with a feedback loop on validation failure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and efficient. It avoids explaining concepts Claude already knows (like what YAML is or how markdown works), and every section delivers specific, actionable constraints and rules. The introductory sentence is slightly unnecessary but overall token usage is well-justified. | 3 / 3 |
Actionability | The skill provides concrete constraints (character limits, token budgets, naming conventions) and executable validation commands, but lacks concrete examples of a well-formed SKILL.md frontmatter or body. A before/after example or a template would make this significantly more actionable for skill creation. | 2 / 3 |
Workflow Clarity | The validation section provides clear commands and an integrity checklist, but the overall authoring workflow lacks explicit sequencing. There's no clear 'Step 1: Create directory, Step 2: Write frontmatter, Step 3: Write body, Step 4: Validate' flow. The integrity checks are listed but lack a feedback loop (what to do when validation fails). | 2 / 3 |
Progressive Disclosure | Excellent progressive disclosure structure. SKILL.md serves as a concise overview with well-signaled, one-level-deep references to detailed documentation (guidelines, token budgets, reference loading, checklist, validation). References are clearly labeled with descriptive text and organized logically. | 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
771a666
- 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.