CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

skill-authoring

Principles for writing skills that behave the same way every run — use when adding, editing, or reviewing a skill in this plugin

Quality

77%

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 ./.claude/skills/skill-authoring/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

75%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 tight, highly actionable advisory skill: concrete rules, named verification commands, explicit stop rules, and exemplary conditional references. The weaknesses are minor — a duplicated environment-variable path expression, no worked example for the most common use (reviewing a skill in a PR), and invocation mechanics that could be pushed down to the assembly standard.

Suggestions

State the "${CLAUDE_PLUGIN_ROOT:-…}" path expression once and refer to it as "that path" afterward instead of repeating it in full.

Add one worked example — a before/after description rewrite or a sample five-item review report — to cover the most common use, reviewing a skill in a PR.

Push the invocation-mechanics detail (path resolution and loading contract) down to `docs/PLUGIN-ASSEMBLY-STANDARD.md` and keep only the governing principle in this body.

DimensionReasoningScore

Conciseness

The body is dense and opinionated with no beginner-level explanations — e.g. "Push too little down and the top bloats; push too much and the agent never finds what it needs". The waste that exists is minor: the "${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-${HOME}/.claude-octopus/plugin}}" expression is spelled out in full twice within three lines, plus a provenance paragraph ("Adapted from `writing-great-skills`…"), matching anchor 4's minor trimmable instances rather than anchor 3's some-unnecessary-explanation.

4 / 5

Actionability

For an instruction-only skill the guidance is concrete: exact flags ("disable-model-invocation: true"), exact file paths, named checks ("tests/unit/test-explicit-activation.sh", "make sync", "hooks/user-prompt-submit.sh"), and a five-item Output Contract. It stops short of anchor 5 because the common cases lack worked examples — there is no before/after description rewrite or sample review report.

4 / 5

Workflow Clarity

The Workflow subsections form a coherent order (description → hierarchy → completion criteria → enforcement), and the Stop Or Checkpoint Rules plus the Verification checklist give explicit checkpoints ("Every step has a criterion the agent can evaluate"). No ordered end-to-end procedure links the sections into a single review run, so it fits anchor 4 rather than anchor 5's fully sequenced workflow with feedback loops; no destructive/batch cap applies.

4 / 5

Progressive Disclosure

Conditional, clearly signaled one-level-deep references are used well ("Load `skills/blocks/domain-modeling.md` when a skill discusses providers, models, access, billing, reviewers, or votes"). However, no bundle files ship with this skill, the referenced files live elsewhere in the plugin and cannot be verified, and assembly mechanics (the full invocation-path contract) are inlined where the referenced `docs/PLUGIN-ASSEMBLY-STANDARD.md` might carry them — minor organization gaps matching anchor 4.

4 / 5

Total

16

/

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.

The description is terse, correctly third-person, and answers both what and when with an explicit, well-scoped trigger clause. Its weaknesses are an abstract what-clause ("Principles for…") that names no concrete capabilities, and trigger coverage that omits common synonyms like creating or updating a skill.

Suggestions

Replace the abstract "Principles for writing skills" with 1-2 concrete capabilities, e.g. "Review and write skill descriptions, content hierarchies, and completion criteria so skills behave the same way every run".

Add natural trigger synonyms such as "creating", "updating", or "building" a skill to the use-when clause.

DimensionReasoningScore

Specificity

The what-clause is abstract — "Principles for writing skills that behave the same way every run" names the domain and a quality goal but no concrete capabilities; the concrete actions ("adding, editing, or reviewing a skill") appear only in the trigger clause. This matches anchor 3 (domain plus a couple of concrete actions, not comprehensive) rather than 2, since the trigger actions are specific rather than generic, and not 4, since no capability list (e.g. writing descriptions, structuring hierarchy, defining completion criteria) is given.

3 / 5

Completeness

Both parts are explicit: what ("Principles for writing skills that behave the same way every run") and an explicit "use when adding, editing, or reviewing a skill in this plugin" clause with concrete triggers. It falls short of anchor 5 because the what is an abstract noun phrase rather than concrete actions, and sits clearly above anchor 3 because the when-clause is explicit and specific rather than weakly implied.

4 / 5

Trigger Term Quality

Natural phrases a user would say are present — "adding", "editing", "reviewing", and (in the what-clause) "writing" a skill, scoped by "in this plugin". Common variations such as "creating", "updating", or "building" a skill are missing, which fits anchor 4 (good coverage, a few natural terms missing) rather than the comprehensive anchor 5.

4 / 5

Distinctiveness Conflict Risk

"a skill in this plugin" scopes the skill to a clear niche (skill authoring/review) with specific triggers, giving low conflict risk with unrelated skills. Minor overlap remains with closely related meta-content the plugin itself references (e.g. "skill-meta-prompt" and the assembly standard), matching anchor 4 rather than the minimal-conflict anchor 5.

4 / 5

Total

15

/

20

Passed

Validation

93%

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

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

15

/

16

Passed

Repository

nyldn/claude-octopus

Path

.claude/skills/skill-authoring/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.