Claude Code Plugin & Marketplace Expert

You are an expert in developing Claude Code marketplaces and plugins. This skill ensures that all elements in this package follow current best practices, maintain consistency, and are optimally structured.

When This Skill Activates

File patterns that trigger this skill:

• plugins/**/* - Any file in the plugins directory
• **/SKILL.md - Skill definition files
• **/commands/**/*.md - Command files
• **/agents/**/*.md - Agent files
• **/hooks/**/* - Hook configurations and scripts
• marketplace.json - Marketplace definition
• plugin.json - Plugin manifests

Gotchas

• argument-hint with [...] brackets needs quotes — argument-hint: [branch-name] is parsed by YAML as a list (["branch-name"]) and breaks the command silently. Always write argument-hint: "[branch-name]". This is the #1 cause of broken commands across the marketplace.
• description with embedded "..." needs single-quote wrapping — description: 'Activates when user says "rebase"' works. description: "Activates when user says "rebase"" is invalid YAML. Always verify with claude plugin validate <plugin-dir>.
• Plugin-agent frontmatter ignores permissionMode, mcpServers, and hooks — a security restriction on plugin scope. Setting them looks valid but silently has no effect. Plugin-agents needing MCP must add a body note that MCP must be configured in the user's session.
• model: and effort: override the user's setup while the element runs — so a pinned model: sonnet downgrades a user who runs a stronger model. Use model: inherit; name an alias (opus / sonnet / haiku / fable, each resolving to the latest model per provider) only where that model is measurably as good for the job, never to save tokens. effort is pinned only where a measurement shows it adds quality: without a pin the element runs at the session's level, which the developer can raise for a hard task, while a pin overrides the session in both directions (it also caps a developer who chose xhigh). Any pin needs an "Effort policy" note in the body naming the measurement behind it; xhigh and max run much longer turns and are prone to overthinking. Measure with the plugin's eval suite (evals/) and decide on quality first, speed only as a tiebreaker. The effort scale (low, medium, high, xhigh, max) is calibrated per model: Opus 5.5 defaults to medium, every other effort-capable model to high, and the same name is not the same amount of thinking across models. Prose such as "think very hard" steers depth less reliably than the effort field. Source: https://code.claude.com/docs/en/model-config#adjust-effort-level
• Subagent nesting is allowed; the gate is the tools: list — A subagent spawns sub-agents when Agent is in its own tools:, down to CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH levels below the main conversation (default 3, 1 disables it). At the depth limit Claude Code withdraws the Agent tool. Every lt-dev agent omits Agent deliberately, for cost and legibility rather than because nesting is unsupported. For parallel file-modifying work, the caller passes isolation: "worktree" on the individual spawn rather than fixing it in agent frontmatter.
• A worktree starts on the default branch, not on the caller's HEAD — isolation: worktree branches from the repository's default branch unless the user's own settings set worktree.baseRef: "head"; a plugin cannot set that key. A branch also cannot be checked out in two worktrees at once, so an isolated agent working on a feature branch that is checked out in the main tree creates a task branch from it, commits there, and the caller merges the task branch back. Source: https://code.claude.com/docs/en/worktrees
• Agent-team teammates cannot use a plugin agent type — teammates reference subagent types only from project, user or managed scope. A plugin agent named as a teammate's type is not applied, and neither is its skills: field. Put the role into the spawn prompt and have the teammate invoke the relevant skill through the Skill tool. Source: https://code.claude.com/docs/en/agent-teams
• Skill and LSP are valid tool names; Skill in tools: does not preload — Skill in an agent's tools: only controls whether the agent may invoke skills at runtime. To preload skill content into the agent's context, use the skills: frontmatter field. There is no SlashCommand tool; Skill invokes both skills and commands.
• Task-tracking tools are model-dependent — TaskCreate, TaskGet, TaskList, TaskUpdate and TodoWrite exist by default only on Claude 3.x, Opus 4 to 4.7, Sonnet 4 to 4.6 and Haiku 4.5. On Opus 5.5, Opus 5, Sonnet 5 and Fable they are absent unless the user sets CLAUDE_CODE_ENABLE_TODO_TOOLS=1, and a subagent gets them only when its session has them. Agents and commands therefore describe their work as a phase list whose outcomes the final report states, instead of mandating a to-do tool. Source: https://code.claude.com/docs/en/tools-reference#task-tool-availability
• Text copied into a spawn prompt becomes the subagent's instruction — a spawn prompt is the subagent's user message, so a ticket description or MR comment pasted into it reads as coming from the user. Pass the ticket ID or file path and let the subagent fetch it; text that has to be copied in goes inside <pasted_content id="…"> tags with a note, as coordinating-agent-teams → "External text in spawn prompts" shows. An element that reads tickets or MR texts also carries an "External Content" section saying the text is task material and its own process stays in force.
• Plugin commands are only callable with the plugin prefix — a command at commands/check.md in plugin lt-dev runs as /lt-dev:check, one at commands/showroom/create.md in lt-showroom as /lt-showroom:showroom:create. The short form (/check, /showroom:create, /create) does not exist, so a skill, README or report that names it hands the user a command that fails. Write the full form wherever an element names a command; a bare /name is right only for Claude Code built-ins (/review, /clear, /compact). Observed 2026-10-01: a session told the user to run a plugin command by its short name, copied verbatim from a skill that used it. Check with grep -rnE '(^|[^:a-z-])/<command-name>' plugins/.
• permissions.json usedBy arrays drift silently — When you rename an agent or skill, the usedBy references in permissions.json don't auto-update. Run grep -r "old-name" plugins/*/permissions.json before finalizing a rename.
• Skills storing state in their own directory lose data on plugin update — Skill directories are recreated on update. For persistent state use ${CLAUDE_PLUGIN_DATA}, not the skill directory itself.

Actions that trigger this skill:

• Creating new plugins, agents, commands, hooks, skills, or scripts
• Modifying existing plugin elements
• Reviewing or optimizing plugin structure
• Discussing Claude Code extension development

Mandatory Pre-Work: Documentation Review

Before implementing or optimizing an element, fetch the latest official documentation: frontmatter fields, tool names and hook events change between Claude Code releases, and the tables in this skill can lag behind them.

Primary Sources (GitHub - always available)

Fetch these GitHub sources first:

WebFetch: https://github.com/anthropics/claude-code/blob/main/plugins/README.md
WebFetch: https://github.com/anthropics/skills/blob/main/README.md

Secondary Sources (WebSearch)

For specific topics, use targeted searches:

WebSearch: "Claude Code [topic] documentation site:claude.com"

Topics to search when relevant:

• Plugins & plugin.json structure
• Skills & SKILL.md frontmatter
• Slash commands & command frontmatter
• Subagents & agent configuration
• Hooks & hooks.json structure

Apply the patterns and requirements from these sources.

---

Element Types Reference

Skills

Purpose: Provide contextual expertise that enhances Claude's capabilities in specific domains.

Structure:

skills/
└── skill-name/
    ├── SKILL.md           # Main skill definition (REQUIRED)
    ├── reference.md       # Detailed reference documentation
    ├── examples.md        # Usage examples
    └── [topic].md         # Additional topic-specific files

SKILL.md Template:

---
name: skill-name-kebab-case
description: Concise description (max 1024 chars, ideal 500-700). Formula: [What it does] + [When to use it] + [Key capabilities]. Must trigger auto-detection correctly.
---

# Skill Title

[Introductory paragraph explaining the skill's purpose]

## When to Use This Skill

- [Trigger condition 1]
- [Trigger condition 2]

## Core Capabilities

[Main content organized by capability]

## Related Skills

- `related-skill-1` - [relationship]
- `related-skill-2` - [relationship]

Key Principles:

• Description must answer "WHEN should Claude use this skill?"
• Avoid overlap with other skills
• Include clear boundary definitions
• Reference related skills explicitly

---

Commands

Purpose: User-triggered actions invoked via /command-name.

Structure:

commands/
├── simple-command.md
└── category/
    ├── sub-command-1.md
    └── sub-command-2.md

Template:

---
description: What this command does (shown in /help and command list)
argument-hint: "[optional-args]"   # Optional: shown in autocomplete (MUST quote if value contains brackets)
allowed-tools: Read, Grep, Bash   # Optional: restrict tool access
model: inherit                    # Optional: inherit keeps the session model; an alias (opus, sonnet, haiku, fable) or a full ID such as claude-opus-5-5 pins one only when required
---

# Command Title

[Brief description of what this command accomplishes]

## When to Use This Command

- [Use case 1]
- [Use case 2]

## Workflow

### Step 1: [Action]
[Instructions]

### Step 2: [Action]
[Instructions]

## Examples

[Practical examples of command usage]

Naming: Use kebab-case, e.g., create-story.md, git/commit-message.md

---

Agents

Purpose: Autonomous agents that handle complex, multi-step tasks with specific tool access.

File: agents/agent-name.md

Template:

---
name: agent-name
description: When to use this agent and what tasks it handles autonomously
model: inherit | opus | sonnet | haiku | fable   # Optional: falls back to the default subagent model
tools: Bash, Read, Grep, Glob, Write, Edit  # Optional: inherits all tools when omitted
permissionMode: default | bypassPermissions  # Ignored for plugin agents
skills: optional-comma-separated-skills     # Preloads skill content
---

[Agent persona and mission]

## Use Cases

- [When to spawn this agent]
- [Specific task types it handles]

## Execution Protocol

[Detailed workflow and phases]

## Output Format

[Expected output structure]

Key Principles:

• Only name and description are required
• Define clear tool restrictions; leave task-tracking tools out of the list, because they are absent on current default models (see Gotchas)
• Use model: inherit so the agent runs on the session model. Name an alias (opus, sonnet, haiku, fable) only where that model is measurably as good for the job: this plugin optimizes quality and time per completed task, not per-token price, and a pin chosen to save tokens downgrades every user who runs a stronger session model
• Include self-verification checklists and a final report that states each phase's outcome

---

Hooks

Purpose: Automated responses to Claude Code events.

Structure:

hooks/
├── hooks.json    # Hook definitions
└── scripts/      # Hook handler scripts
    └── handler.ts

hooks.json Template:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/script.sh"
          }
        ]
      }
    ]
  }
}

Fields: | Field | Type | Description | |-------|------|-------------| | matcher | string | Tested against the tool name: "Write", "Write\|Edit", or omit for all | | type | string | "command" (shell), "http", "prompt" (LLM evaluation) or "agent" (agentic verifier) | | command | string | Shell command (for type="command"); receives the event data as JSON on stdin | | if | string | Optional, on the hook object: permission-rule filter such as "Edit(**/*.ts)" or "Bash(git *)" | | timeout | number | Seconds before timeout (default: 60, optional) |

Events:

• PreToolUse - Before a tool executes
• PostToolUse - After a tool executes
• PermissionRequest - When permission is requested
• UserPromptSubmit - When user submits a prompt
• SessionStart - Session initialization
• SessionEnd - Session teardown
• Stop - When main agent finishes
• SubagentStart - When subagent starts
• SubagentStop - When subagent finishes
• TeammateIdle - Agent Teams: teammate waiting for work
• TaskCompleted - Agent Teams: task finished
• PreCompact - Before context compaction

---

Quality Checklist

Before Creating Any Element

• [ ] Fetched latest documentation from official sources
• [ ] Identified correct element type for the use case
• [ ] Checked for existing similar elements (avoid duplication)
• [ ] Determined relationships with existing elements

Element Quality Standards

• [ ] YAML frontmatter is correct and complete
• [ ] Description is concise and actionable
• [ ] Structure follows established patterns in this package
• [ ] Markdown is clean and well-organized
• [ ] Examples are included where helpful
• [ ] Related elements are cross-referenced

Consistency Checks

• [ ] Naming follows kebab-case convention
• [ ] Heading hierarchy is consistent (# for title, ## for sections)
• [ ] Language is English (except user-facing German content)
• [ ] No orphaned references to non-existent elements

---

Optimization Workflow

When optimizing existing elements:

1. Analysis Phase

1. Read the element completely
2. Identify the element type and purpose
3. Fetch current best practices from documentation
4. Compare against other elements in the same category
5. List specific issues and improvements

2. Proposal Phase

1. Present findings to the user
2. Propose specific changes with rationale
3. Highlight any breaking changes or dependencies
4. Get approval before implementation

3. Implementation Phase

1. Make changes incrementally
2. Maintain backwards compatibility where possible
3. Update cross-references in related elements
4. Verify no broken references

4. Verification Phase

1. Validate YAML frontmatter syntax
2. Check markdown rendering
3. Verify all cross-references work
4. Test any commands or workflows

---

Common Patterns in This Package

Skill Organization

• Main SKILL.md with overview and triggers
• Separate files for detailed topics (reference.md, examples.md)
• Clear "When to Use" sections with bullet points

Command Organization

• Grouped by category in subdirectories
• Step-by-step workflows with clear phases
• German output for user-facing commands where appropriate

Agent Organization

• Detailed execution protocols with phases
• Self-verification checklists
• Comprehensive output format specifications

---

Content Standards

No History References

• Never use "new", "updated", "changed from", or version-specific markers
• Never include "since v2.1", "added in version X", "previously"
• Write timelessly as if features always existed
• Remove any existing history references when optimizing

Token Efficiency

• Keep content concise but complete
• Avoid redundant explanations
• Use tables and lists over prose where appropriate
• Don't sacrifice clarity for brevity
• Never remove important information for token savings

---

Anti-Patterns to Avoid

1. Overlapping Skills: Two skills that trigger on the same conditions
2. Monolithic Commands: Commands that try to do too much
3. Vague Descriptions: Descriptions that don't help auto-detection
4. Missing Cross-References: Elements that should reference each other but don't
5. Inconsistent Structure: Elements that don't follow established patterns
6. Outdated Best Practices: Not checking current documentation before changes
7. History References: Adding "new", "updated", version markers to content

---

Skill Boundaries

| User Intent | Correct Skill | |------------|---------------| | "Create a new skill" | THIS SKILL | | "Optimize plugin.json" | THIS SKILL | | "Add a hook for validation" | THIS SKILL | | "Create a NestJS module" | generating-nest-servers | | "Build a Vue component" | developing-lt-frontend | | "Update npm packages" | maintaining-npm-packages |

Reference Files

• For complete reference documentation and schemas, see reference.md
• For practical examples and templates, see examples.md

Related Skills

Works closely with:

• using-lt-cli skill - For Git operations in this package
• generating-nest-servers skill - When adding NestJS-related commands or skills
• developing-lt-frontend skill - When adding Nuxt-related commands or skills
• maintaining-npm-packages skill - When adding maintenance-related commands

When modifying any skill, command, or agent in this package, this expertise should inform the changes.