This skill should be used when the user asks to "validate plugin structure", "review manifest files", "check frontmatter compliance", "verify tool invocation patterns", "explain plugin component types", or needs Claude Code plugin architectural guidance.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
This skill should be used when the user asks to "validate plugin structure", "review manifest files", "check frontmatter compliance", "verify tool invocation patterns", "explain plugin component types", or needs Claude Code plugin architectural guidance.
user-invocable
false
Plugin Validation & Best Practices
Validates Claude Code plugins against architectural standards. This file is a navigation guide; detailed content lives in references/.
MUST / MUST NOT: Absolute requirement or prohibition
SHOULD / SHOULD NOT: Recommended practice with known exceptions
MAY: Truly optional
See ./references/rfc-2119.md for complete RFC 2119 specification.
Critical Patterns
Tool Invocation Rules
Tool
Style
Example
Read, Write, Edit, Glob, Grep
Implicit
"Find files matching..."
Bash
Implicit
"Run git status"
Task
Implicit
"Launch plugin-name:agent-name agent"
Skill
Explicit
"Load plugin-name:skill-name skill using the Skill tool"
TaskCreate
Explicit
"Use TaskCreate tool to track progress"
AskUserQuestion
Explicit
"Use AskUserQuestion tool to [action]"
MCP Tools
Implicit
"Query the database for user records"
Qualified names: MUST use plugin-name:component-name format for plugin components.
allowed-tools: NEVER use bare Bash - always use filters like Bash(git:*).
Inline Bash: Use inline syntax (exclamation + backtick + command + backtick) for dynamic context.
MCP Tool Invocation: Use natural language to describe intent — Claude automatically identifies the appropriate MCP tool. Never specify exact MCP tool names like mcp__server__tool in skill content.
See ./references/tool-invocations.md for complete patterns and anti-patterns.
See ./references/mcp-patterns.md for MCP-specific invocation patterns.
Skill Frontmatter (Official Best Practices)
Required fields:
name: Max 64 chars, lowercase letters/numbers/hyphens only. Naming convention by type: instruction-type skills use a use-<action> prefix (e.g., use-kicad-cli); knowledge-type skills use a using-<topic> prefix (e.g., using-git-worktrees).
description: Max 1024 chars. MUST use third-person voice with specific trigger phrases.
Description Best Practices:
Requirement
Description
Person
Third-person only ("This skill should be used when...")
Structure
[What it does]. Use when [scenario 1], [scenario 2], or [user phrases].
Purpose
Skill discovery - Claude uses this to select from 100+ skills
Trigger phrases
Include specific user phrases like "validate plugin", "check frontmatter"
Additional fields are supported but affect progressive disclosure alignment.
See ./references/components/skills.md for complete frontmatter specification.
Agent Frontmatter
Required fields (per upstream spec):
name: 3-50 chars, kebab-case
description: trigger conditions plus 2-4 <example> blocks
Forbidden fields in plugin agents (security): hooks, mcpServers, permissionMode.
Field order: name → description (a | block scalar containing trigger conditions and the <example> blocks) → other YAML fields → closing ---. Bare <example> blocks outside the description break YAML parsing.
See ./references/components/agents.md for complete agent design guidelines including CO-STAR framework.
Task Management
Tasks with 3+ distinct steps, multi-file work, or sequential dependencies warrant TaskCreate. Single-file edits and 1-2 step operations do not.
Core Requirements:
Dual form naming: subject ("Run tests") + activeForm ("Running tests")
Mark in_progress BEFORE starting, completed AFTER finishing
Only mark completed when FULLY done
See ./references/task-management.md for complete patterns and examples.
MCP Server Configuration
MCP servers are configured in .mcp.json at plugin root or inline in plugin.json under mcpServers. Three transport types are supported: stdio (local CLI tools), http (remote APIs, most widely supported), and sse (real-time streaming).
NEVER hardcode secrets — always use ${ENV_VAR} syntax.
See ./references/mcp-patterns.md for complete MCP integration patterns.
See ./references/components/mcp-servers.md for component configuration details.
Hook Configuration
Hook events cover the full session lifecycle (28+ events including PreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch, PermissionRequest, PermissionDenied, UserPromptSubmit, UserPromptExpansion, Setup, Notification, Stop/StopFailure, SubagentStart/SubagentStop, TaskCreated/TaskCompleted, TeammateIdle, InstructionsLoaded, ConfigChange, CwdChanged, FileChanged, WorktreeCreate/WorktreeRemove, PreCompact/PostCompact, Elicitation/ElicitationResult, SessionStart/SessionEnd). Five hook types: command, http, mcp_tool, prompt, agent.
See ./references/components/hooks.md for the full event table and AI-native structured output patterns.
Agent Teams vs Subagents
Subagents are isolated, single-direction sub-processes returning results to the caller. Agent Teams are multiple independent sessions sharing a task list with direct peer-to-peer communication — suited for parallel investigation, multi-module features, and competing hypotheses.
Subagents
Agent Teams
Context
Returns to caller
Fully independent
Communication
To main agent only
Direct peer-to-peer
Token cost
Lower (summarized)
Higher (full instances)
Agent Teams are experimental. Enable with export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
See ./references/agent-teams.md for complete guide and ./references/parallel-execution.md for parallel coordination patterns.
