CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

write-a-skill

Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, build, or author a new skill.

60

Quality

75%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.gemini/skills/write-a-skill/SKILL.md

The canonical home for this skill is write-a-skill in alirezarezvani/claude-skills

SKILL.md
Quality
Evals
Security

Quality

Content

71%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A well-organized, mostly lean authoring guide with a clear 3-phase workflow, concrete templates, and quantitative heuristics. Its main weakness is that the companion tooling it directs the agent to (reference doc and checklist runner script) is not present in the bundle, breaking navigation and the one runnable validation path.

Suggestions

Ship the referenced bundle files (references/companion_tooling.md and scripts/skill_review_checklist_runner.py) or remove/inline the 'Tooling + Companions' section so no path dangles.

Add an explicit feedback loop after the Review Checklist (e.g., 'If any box fails, revise the draft and re-run the checklist before presenting to the user') to close the workflow's validation gap.

Trim the explanation of how skill descriptions are surfaced and selected in 'Description Requirements' — the agent already knows this; keep only the goal, format limits, and examples.

DimensionReasoningScore

Conciseness

The body is largely lean: a 3-phase process, directory layout, a copy-paste SKILL.md template, good/bad description examples, and concrete thresholds (100 lines, 1024 chars, 500 lines). Minor over-explanation could be trimmed — e.g., 'The description is the only thing your agent sees... It's surfaced in the system prompt alongside all other installed skills. Your agent reads these descriptions and picks the relevant skill' explains skill-dispatch mechanics the agent already knows, and the template's placeholder lines add padding.

4 / 5

Actionability

Guidance is mostly executable: a copy-paste-ready SKILL.md template, a directory-structure diagram, good/bad description examples, quantitative criteria (under 100 lines, max 1024 chars), and a checklist-runner command. Not a 5 because 'python scripts/skill_review_checklist_runner.py' and 'references/companion_tooling.md' are referenced but absent from the bundle, so the one runnable command cannot actually be executed as shipped here.

4 / 5

Workflow Clarity

The 3-phase workflow (Gather requirements → Draft → Review with user) is clearly sequenced with concrete sub-questions per phase, and the 6-item Review Checklist acts as an explicit post-draft validation checkpoint. Minor gap: no stated fix-and-recheck loop after the checklist fails, keeping it at the level-4 anchor 'clear sequence with most checkpoints present'.

4 / 5

Progressive Disclosure

Structure and signaling are good — one clearly labeled 'Tooling + Companions' section pointing to a single reference, one level deep, with the core authoring guidance kept inline. However, scored against the actual bundle, the referenced paths (references/companion_tooling.md, scripts/skill_review_checklist_runner.py) do not exist in the skill's directory, so navigation does not resolve and the advertised programmatic checklist cannot be found.

3 / 5

Total

15

/

20

Passed

Description

70%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A well-formed description that follows the what/when pattern with good verb-synonym trigger coverage. It could rise a level by naming more concrete actions (drafting SKILL.md, writing trigger descriptions, bundling references/scripts) and adding file-type or context triggers like 'SKILL.md'.

Suggestions

List 2-3 concrete actions instead of abstract attributes, e.g. 'Create new agent skills: draft SKILL.md with trigger descriptions, structure reference files and utility scripts.'

Add specific trigger objects users would mention, such as 'SKILL.md', '.claude/skills', or 'skill structure', to sharpen both trigger quality and distinctiveness from document-to-skill compilers.

DimensionReasoningScore

Specificity

The description names the domain ('Create new agent skills') plus output attributes ('proper structure, progressive disclosure, and bundled resources'), but offers only one concrete action — 'create' — with the rest being abstract qualities rather than distinct actions like 'drafts SKILL.md', 'writes trigger descriptions', or 'packages reference files'. This matches the anchor 'Names domain and 1-2 concrete actions, but not comprehensive' rather than the level-4 anchor, which expects several specific listed actions.

3 / 5

Completeness

Both parts are present: a clear 'what' ('Create new agent skills with proper structure, progressive disclosure, and bundled resources') and an explicit 'Use when...' clause with concrete trigger verbs. Not a 5 because the 'when' is limited to verb synonyms for making a skill and omits more specific triggers (e.g., SKILL.md authoring, structuring an existing skill, packaging resources) that would make it unambiguous.

4 / 5

Trigger Term Quality

'Use when user wants to create, write, build, or author a new skill' covers the common verb synonyms users would naturally say. It falls short of the level-5 anchor because it misses natural variations such as 'SKILL.md', '.claude/skills', 'make a skill', or 'skill structure/bundling'.

4 / 5

Distinctiveness Conflict Risk

'Agent skill creation' is a clear niche unlikely to fire for unrelated skills, but 'create... a new skill' could overlap with closely related skills such as compiling a document into a skill (the body itself acknowledges a book-to-skill sibling). Minor overlap risk with closely related skills matches the level-4 anchor.

4 / 5

Total

15

/

20

Passed

Validation

87%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

relative_links

Relative link issues: 2 missing

Warning

referenced_paths_exist

Referenced path issues: 3 missing

Warning

Total

14

/

16

Passed

Repository

alirezarezvani/claude-skills

Path

.gemini/skills/write-a-skill/SKILL.md

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.