CtrlK
BlogDocsLog inGet started
Tessl Logo

plugin-structure

This skill should be used when the user asks to "create a plugin", "scaffold a plugin", "understand plugin structure", "organize plugin components", "set up plugin.json", "use ${CLAUDE_PLUGIN_ROOT}", "add commands/agents/skills/hooks", "configure auto-discovery", or needs guidance on plugin directory layout, manifest configuration, component organization, file naming conventions, or Claude Code plugin architecture best practices.

69

1.96x
Quality

53%

Does it follow best practices?

Impact

100%

1.96x

Average score across 3 eval scenarios

SecuritybySnyk

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./plugins/plugin-dev/skills/plugin-structure/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Discovery

72%

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 excels at trigger term coverage and distinctiveness, providing numerous specific phrases that would help Claude select this skill accurately. However, it is structurally imbalanced — it reads almost entirely as a 'Use when...' clause without first establishing what the skill actually does (e.g., 'Guides creation and scaffolding of Claude Code plugins, including directory layout, manifest configuration, and component organization'). Adding a clear capability statement would significantly improve it.

Suggestions

Add a leading capability statement before the trigger phrases, e.g., 'Guides the creation and scaffolding of Claude Code plugins, including directory structure setup, plugin.json manifest configuration, and component organization for commands, agents, skills, and hooks.'

Rewrite in third person active voice describing what the skill does (e.g., 'Scaffolds plugin projects, configures plugin.json manifests, organizes plugin components') before listing when to use it.

DimensionReasoningScore

Specificity

The description names the domain (Claude Code plugins) and references several actions like 'create a plugin', 'scaffold a plugin', 'set up plugin.json', 'add commands/agents/skills/hooks', but these are embedded in trigger phrases rather than stated as concrete capabilities the skill performs. It lacks a clear 'what it does' statement listing specific actions.

2 / 3

Completeness

The description has a strong 'when' clause with explicit trigger phrases, but the 'what does this do' part is essentially missing — it never clearly states what the skill actually does or produces. It's almost entirely trigger-focused without describing the skill's capabilities or outputs.

2 / 3

Trigger Term Quality

Excellent coverage of natural trigger terms users would say: 'create a plugin', 'scaffold a plugin', 'plugin structure', 'plugin.json', '${CLAUDE_PLUGIN_ROOT}', 'auto-discovery', 'commands/agents/skills/hooks', 'plugin directory layout', 'manifest configuration'. These are highly specific and natural phrases a user would use.

3 / 3

Distinctiveness Conflict Risk

The description is highly specific to Claude Code plugin architecture, with distinct terms like 'plugin.json', '${CLAUDE_PLUGIN_ROOT}', 'auto-discovery', and 'Claude Code plugin architecture'. This is a clear niche unlikely to conflict with other skills.

3 / 3

Total

10

/

12

Passed

Implementation

35%

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

This skill serves as a comprehensive reference document for Claude Code plugin structure but suffers from significant verbosity—it explains many concepts Claude already knows (JSON format, kebab-case, semantic versioning, what markdown is) and includes extensive examples that could be in separate reference files. The content would benefit greatly from being condensed to essential rules and patterns, with detailed examples and best practices moved to referenced files.

Suggestions

Cut content by 50-60%: Remove explanations of concepts Claude already knows (kebab-case definition, semantic versioning explanation, what markdown frontmatter is) and trim metadata examples to just the required fields with a reference link for optional fields.

Add a concrete step-by-step workflow for scaffolding a new plugin (e.g., 'Step 1: Create directory, Step 2: Create plugin.json with minimum fields, Step 3: Verify plugin loads, Step 4: Add components') with validation checkpoints.

Move detailed sections (File Naming Conventions, Best Practices, Troubleshooting, Common Patterns) into separate referenced files to improve progressive disclosure and reduce the main skill's token footprint.

Add an executable scaffold command or script example that Claude can actually run to create the directory structure, rather than just showing the tree diagram.

DimensionReasoningScore

Conciseness

This skill is extremely verbose at ~350+ lines, explaining many concepts Claude already understands (directory structures, JSON formats, kebab-case naming, semantic versioning, what markdown frontmatter is). Sections like 'File Naming Conventions', 'Best Practices', and extensive metadata examples add significant token bloat without proportional value.

1 / 3

Actionability

The skill provides concrete directory structures, JSON examples, and file format templates that are useful references. However, it's more of a reference document than actionable step-by-step guidance—there are no executable commands to scaffold a plugin, and the examples are illustrative rather than copy-paste-ready workflows.

2 / 3

Workflow Clarity

While the auto-discovery mechanism section provides a numbered sequence, there's no clear step-by-step workflow for actually creating a plugin from scratch. The troubleshooting section helps but lacks validation checkpoints during the creation process (e.g., 'verify plugin loads before adding more components').

2 / 3

Progressive Disclosure

The content is a monolithic wall of text with everything inline. Sections like the full metadata example, file naming conventions, best practices, and troubleshooting could easily be split into referenced files. The final line references 'references/' and 'examples/' directories but the bulk of content that belongs there is inline.

2 / 3

Total

7

/

12

Passed

Validation

90%

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

Validation10 / 11 Passed

Validation for skill structure

CriteriaDescriptionResult

frontmatter_unknown_keys

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

Warning

Total

10

/

11

Passed

Repository
anthropics/claude-plugins-official
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.