Create well-formatted Agent Skills following the agentskills.io specification. Use when writing, authoring, scaffolding, or reviewing a new skill, SKILL.md file, or skill directory structure.
65
77%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.agent/skills/skill-authoring-general/SKILL.mdQuality
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 solid description with excellent trigger terms, clear completeness (both what and when), and a highly distinctive niche. Its main weakness is that the specificity of capabilities could be improved by listing more concrete actions beyond the somewhat overlapping verbs (writing, authoring, scaffolding, reviewing), such as mentioning YAML frontmatter generation, instruction section creation, or spec validation.
Suggestions
Expand specificity by listing concrete actions like 'generates YAML frontmatter, creates instruction sections, sets up directory structure, validates against the agentskills.io spec' instead of relying on near-synonymous verbs.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (Agent Skills / SKILL.md) and some actions (writing, authoring, scaffolding, reviewing), but doesn't describe concrete capabilities like 'generates YAML frontmatter, creates instruction sections, validates against spec'. The actions listed are somewhat synonymous and don't convey distinct concrete operations. | 2 / 3 |
Completeness | Clearly answers both 'what' (create well-formatted Agent Skills following the agentskills.io specification) and 'when' (Use when writing, authoring, scaffolding, or reviewing a new skill, SKILL.md file, or skill directory structure). Has an explicit 'Use when...' clause with trigger scenarios. | 3 / 3 |
Trigger Term Quality | Includes strong natural trigger terms users would say: 'skill', 'SKILL.md', 'skill directory structure', 'agentskills.io', 'scaffolding', 'writing', 'authoring', 'reviewing'. These cover multiple natural phrasings a user might use when requesting help creating a skill. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive niche — creating Agent Skills per the agentskills.io spec is a very specific task unlikely to conflict with other skills. The mention of 'SKILL.md', 'agentskills.io specification', and 'skill directory structure' are unique identifiers that clearly separate this from general coding or documentation skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
64%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a solid, actionable skill with concrete templates, validation rules, and a publishing checklist. Its main weaknesses are moderate verbosity (some sections explain concepts Claude already knows, like SemVer) and a workflow that lacks an explicit feedback loop between validation and fixing errors. The skill would benefit from practicing what it preaches — moving detailed reference material to separate files.
Suggestions
Add an explicit feedback loop around validation: 'Run validate → if errors, fix → re-validate → only publish when clean'
Move the detailed field rules tables and versioning semantics into a references/ file, keeping SKILL.md as a concise overview with pointers
Trim the SemVer explanation to a single line — Claude already knows what semantic versioning is; just specify the policy (e.g., 'Use SemVer. Start new skills at 1.0.0. Update skills.json.')
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is mostly efficient but includes some unnecessary explanation (e.g., the 'Writing a Good description' section explains concepts Claude already understands about writing descriptions). The templates and tables are well-structured but the overall content could be tightened — for instance, the versioning section is somewhat verbose for what amounts to 'use SemVer and update skills.json'. | 2 / 3 |
Actionability | The skill provides concrete, copy-paste-ready templates (minimal and full), specific field validation rules with exact character limits and regex-like constraints, a validation command, and a detailed checklist. The examples for good vs poor descriptions are actionable and specific. | 3 / 3 |
Workflow Clarity | The checklist at the end provides a good sequence, and the validation step is included, but there's no explicit feedback loop (validate → fix → re-validate). The overall authoring workflow is implied rather than explicitly sequenced — the reader must piece together the order from separate sections (structure → format → instructions → description → versioning → validation → checklist). | 2 / 3 |
Progressive Disclosure | The content is well-organized with clear sections and headers, but at ~130 lines it includes detailed reference material (field rules, versioning semantics) that could be split into reference files. Since no bundle files are provided, there's no actual progressive disclosure to external references despite the skill itself recommending moving detailed content to references/. | 2 / 3 |
Total | 9 / 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.
c0b2e4b
Table of Contents
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.