CtrlK
BlogDocsLog inGet started
Tessl Logo

skill-authoring-general

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

Quality

77%

Does it follow best practices?

Impact

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./.agent/skills/skill-authoring-general/SKILL.md
SKILL.md
Quality
Evals
Security

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 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.

DimensionReasoningScore

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.')

DimensionReasoningScore

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.

Validation11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository
ucdavis/ai-skills-registry
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.