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".
Install with Tessl CLI
npx tessl i github:microsoft/github-copilot-for-azure --skill skill-authoring90
Does it follow best practices?
If you maintain this skill, you can automatically optimize it using the tessl CLI to improve its score:
npx tessl skill review --optimize ./path/to/skillValidation for skill structure
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 is a well-structured description with excellent trigger term coverage and clear 'when' guidance. The main weakness is the 'what' portion could be more specific about concrete actions the skill enables (e.g., validating structure, generating templates, checking compliance). The explicit WHEN clause format is effective for skill selection.
Suggestions
Expand the 'what' portion to list specific concrete actions like 'validate skill structure', 'generate compliant templates', 'check frontmatter fields' rather than just 'Guidelines for writing'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (Agent Skills, agentskills.io specification) and implies actions like writing/creating/reviewing skills, but doesn't list specific concrete actions like 'validate frontmatter fields', 'generate YAML headers', or 'check compliance rules'. | 2 / 3 |
Completeness | Clearly answers both what ('Guidelines for writing Agent Skills that comply with the agentskills.io specification') and when (explicit 'WHEN:' clause with comprehensive trigger terms). The explicit trigger guidance is present and thorough. | 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 all realistic user phrases. | 3 / 3 |
Distinctiveness Conflict Risk | Very specific niche targeting agentskills.io specification and SKILL.md files. The trigger terms are highly specific to this domain ('skill frontmatter', 'SKILL.md format', 'agentskills.io') and unlikely to conflict with general coding or documentation skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
87%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-crafted skill that demonstrates strong conciseness and actionability with specific constraints, executable commands, and clear structure. The progressive disclosure is exemplary with well-organized references. The main weakness is the lack of an explicit step-by-step workflow for creating a skill from scratch with validation checkpoints.
Suggestions
Add a numbered 'Creating a New Skill' workflow section with explicit steps (e.g., 1. Create directory, 2. Write frontmatter, 3. Validate with npm run tokens, etc.) including validation checkpoints between steps
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and efficient, avoiding explanations of concepts Claude already knows. Every section provides specific, actionable information without padding or unnecessary context. | 3 / 3 |
Actionability | Provides concrete constraints with specific values (token limits, character counts), executable validation commands, and clear structural requirements. The bash commands are copy-paste ready. | 3 / 3 |
Workflow Clarity | While the validation section provides clear commands and the integrity checks list verification steps, the overall skill authoring workflow lacks explicit sequencing. There's no clear 'create skill' workflow with validation checkpoints between steps. | 2 / 3 |
Progressive Disclosure | Excellent structure with a concise overview and well-signaled one-level-deep references. The Reference Documentation section clearly links to detailed materials with descriptive labels, and content is appropriately split across files. | 3 / 3 |
Total | 11 / 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.
- 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.