Skill plugin-structure
✓ VerificadoFornece orientações sobre a estrutura de diretórios, configuração de manifesto e organização de componentes para a criação de plugins para o Claude Code.
- Estrelas no GitHub
- 171
- Arquivos
- 5
- Último commit
- 11 de nov. de 2026
- Licença
- MIT
- Ferramentas permitidas
- —
O que a skill plugin-structure faz?
Fornece orientações sobre a estrutura de diretórios, configuração de manifesto e organização de componentes para a criação de plugins para o Claude Code.
Resumo gerado a partir do SKILL.md da skill.
Sobre a skill plugin-structure
Desenvolvedores que estão criando extensões para o Claude Code podem usar esta skill para aprender como estruturar, organizar e configurar seus plugins corretamente. Ela fornece a orientação arquitetural necessária para garantir que componentes como slash commands, subagents e skills sejam descobertos automaticamente pelo sistema. Ao seguir os layouts de diretórios prescritos, os desenvolvedores podem criar plugins de fácil manutenção que se integram ao ambiente host.
A skill cobre a implementação do manifesto plugin.json, que deve residir obrigatoriamente no diretório .claude-plugin. Ela explica como gerenciar diferentes tipos de componentes, incluindo comandos e agentes baseados em markdown, além de subdiretórios de skills que contêm arquivos SKILL.md. Também detalha como configurar handlers de eventos por meio de hooks e como integrar MCP servers usando arquivos .mcp.json. Um foco principal é o uso da variável ${CLAUDE_PLUGIN_ROOT} para garantir que todos os caminhos de arquivos permaneçam portáteis entre diferentes sistemas operacionais e métodos de instalação.
O que um agente pode fazer com ela
- 1Estruturar um novo pluginUm desenvolvedor precisa saber o layout de diretórios correto e os arquivos necessários para começar a construir uma extensão para o Claude Code.
- 2Configurar o manifesto do pluginUm engenheiro deseja configurar o arquivo plugin.json com os metadados obrigatórios e caminhos personalizados de componentes.
- 3Implementar caminhos de arquivos portáteisUm usuário precisa referenciar scripts ou assets internos sem utilizar caminhos absolutos fixos no código.
- 4Configurar event hooksUm desenvolvedor deseja disparar scripts específicos durante eventos do Claude Code, como PreToolUse ou SessionStart.
Escrito a partir do SKILL.md da skill. Cada caso de uso é verificado com uma citação dele.
Como instalar a skill plugin-structure
Cada comando copia a pasta da skill para o diretório de skills do cliente. Reinicie o cliente ou inicie uma nova sessão para carregá-la.Instalar a skill plugin-structure no Claude Code
~/.claude/skills/plugin-structure/SKILL.md
$ npx degit thevibeworks/claude-code-docs/content/github/claude-plugins-official/plugins/plugin-dev/skills/plugin-structure ~/.claude/skills/plugin-structureInstalar a skill plugin-structure no Claude Code (project)
.claude/skills/plugin-structure/SKILL.md
$ npx degit thevibeworks/claude-code-docs/content/github/claude-plugins-official/plugins/plugin-dev/skills/plugin-structure .claude/skills/plugin-structureInstalar a skill plugin-structure no Codex
~/.agents/skills/plugin-structure/SKILL.md
$ npx degit thevibeworks/claude-code-docs/content/github/claude-plugins-official/plugins/plugin-dev/skills/plugin-structure ~/.agents/skills/plugin-structureInstalar a skill plugin-structure no Gemini CLI
~/.gemini/skills/plugin-structure/SKILL.md
$ npx degit thevibeworks/claude-code-docs/content/github/claude-plugins-official/plugins/plugin-dev/skills/plugin-structure ~/.gemini/skills/plugin-structureInstalar a skill plugin-structure no Claude.ai
npx degit thevibeworks/claude-code-docs/content/github/claude-plugins-official/plugins/plugin-dev/skills/plugin-structure plugin-structure && zip -r plugin-structure.zip plugin-structure # claude.ai → Customize → Skills → + → Create skill → Upload a skill → plugin-structure.zip
Verificações automatizadas
Executado em 15 de nov. de 2026Relatório completo →Passou nas nossas verificações automáticas. Não é uma auditoria de segurança: leia os scripts antes de deixar um agente executá-los. Como as verificações funcionam
- Repositório de origem vinculado e acessívelthevibeworks/claude-code-docs/content/github/claude-plugins-official/plugins/plugin-dev/skills/plugin-structure is public and reachablegithub.com/thevibeworks/claude-code-docs/tree/HEAD/content/g ↗Passou
- Licença de código aberto (OSI)MITspdx.org/licenses/MIT.html ↗Passou
- Commit ou release no último anoLast commit 2026-11-11github.com/thevibeworks/claude-code-docs/commits ↗Passou
- Sem baixar e executar nem roubo de credenciais nos scriptsNo scripts in the skill folderPassou
- Sem instruções ocultas no SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/thevibeworks/claude-code-docs/blob/HEAD/content/g ↗Passou
- Ferramentas pré-aprovadas são restritasNo pre-approved tools; the agent asks before using onegithub.com/thevibeworks/claude-code-docs/blob/HEAD/content/g ↗Passou
- O SKILL.md segue o formato Agent SkillsValid name and description; says when to use it; 477 linesgithub.com/thevibeworks/claude-code-docs/blob/HEAD/content/g ↗Passou
SKILL.md
Ver no GitHubPlugin Structure for Claude Code
Overview
Claude Code plugins follow a standardized directory structure with automatic component discovery. Understanding this structure enables creating well-organized, maintainable plugins that integrate seamlessly with Claude Code.
Key concepts:
- Conventional directory layout for automatic discovery
- Manifest-driven configuration in
.claude-plugin/plugin.json - Component-based organization (commands, agents, skills, hooks)
- Portable path references using
${CLAUDE_PLUGIN_ROOT} - Explicit vs. auto-discovered component loading
Directory Structure
Every Claude Code plugin follows this organizational pattern:
plugin-name/
├── .claude-plugin/
│ └── plugin.json # Required: Plugin manifest
├── commands/ # Slash commands (.md files)
├── agents/ # Subagent definitions (.md files)
├── skills/ # Agent skills (subdirectories)
│ └── skill-name/
│ └── SKILL.md # Required for each skill
├── hooks/
│ └── hooks.json # Event handler configuration
├── .mcp.json # MCP server definitions
└── scripts/ # Helper scripts and utilities
Critical rules:
- Manifest location: The
plugin.jsonmanifest MUST be in.claude-plugin/directory - Component locations: All component directories (commands, agents, skills, hooks) MUST be at plugin root level, NOT nested inside
.claude-plugin/ - Optional components: Only create directories for components the plugin actually uses
- Naming convention: Use kebab-case for all directory and file names
Plugin Manifest (plugin.json)
The manifest defines plugin metadata and configuration. Located at .claude-plugin/plugin.json:
Required Fields
{
"name": "plugin-name"
}
Name requirements:
- Use kebab-case format (lowercase with hyphens)
- Must be unique across installed plugins
- No spaces or special characters
- Example:
code-review-assistant,test-runner,api-docs
Recommended Metadata
{
"name": "plugin-name",
"version": "1.0.0",
"description": "Brief explanation of plugin purpose",
"author": {
"name": "Author Name",
"email": "author@example.com",
"url": "https://example.com"
},
"homepage": "https://docs.example.com",
"repository": "https://github.com/user/plugin-name",
"license": "MIT",
"keywords": ["testing", "automation", "ci-cd"]
}
Version format: Follow semantic versioning (MAJOR.MINOR.PATCH) Keywords: Use for plugin discovery and categorization
Component Path Configuration
Specify custom paths for components (supplements default directories):
{
"name": "plugin-name",
"commands": "./custom-commands",
"agents": ["./agents", "./specialized-agents"],
"hooks": "./config/hooks.json",
"mcpServers": "./.mcp.json"
}
Important: Custom paths supplement defaults—they don't replace them. Components in both default directories and custom paths will load.
Path rules:
- Must be relative to plugin root
- Must start with
./ - Cannot use absolute paths
- Support arrays for multiple locations
Component Organization
Commands
Location: commands/ directory
Format: Markdown files with YAML frontmatter
Auto-discovery: All .md files in commands/ load automatically
Example structure:
commands/
├── review.md # /review command
├── test.md # /test command
└── deploy.md # /deploy command
File format:
---
name: command-name
description: Command description
---
Command implementation instructions...
Usage: Commands integrate as native slash commands in Claude Code
Agents
Location: agents/ directory
Format: Markdown files with YAML frontmatter
Auto-discovery: All .md files in agents/ load automatically
Example structure:
agents/
├── code-reviewer.md
├── test-generator.md
└── refactorer.md
File format:
---
description: Agent role and expertise
capabilities:
- Specific task 1
- Specific task 2
---
Detailed agent instructions and knowledge...
Usage: Users can invoke agents manually, or Claude Code selects them automatically based on task context
Skills
Location: skills/ directory with subdirectories per skill
Format: Each skill in its own directory with SKILL.md file
Auto-discovery: All SKILL.md files in skill subdirectories load automatically
Example structure:
skills/
├── api-testing/
│ ├── SKILL.md
│ ├── scripts/
│ │ └── test-runner.py
│ └── references/
│ └── api-spec.md
└── database-migrations/
├── SKILL.md
└── examples/
└── migration-template.sql
SKILL.md format:
---
name: Skill Name
description: When to use this skill
version: 1.0.0
---
Skill instructions and guidance...
Supporting files: Skills can include scripts, references, examples, or assets in subdirectories
Usage: Claude Code autonomously activates skills based on task context matching the description
Hooks
Location: hooks/hooks.json or inline in plugin.json
Format: JSON configuration defining event handlers
Registration: Hooks register automatically when plugin enables
Example structure:
hooks/
├── hooks.json # Hook configuration
└── scripts/
├── validate.sh # Hook script
└── check-style.sh # Hook script
Configuration format:
{
"PreToolUse": [{
"matcher": "Write|Edit",
"hooks": [{
"type": "command",
"command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/validate.sh",
"timeout": 30
}]
}]
}
Available events: PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification
Usage: Hooks execute automatically in response to Claude Code events
MCP Servers
Location: .mcp.json at plugin root or inline in plugin.json
Format: JSON configuration for MCP server definitions
Auto-start: Servers start automatically when plugin enables
Example format:
{
"mcpServers": {
"server-name": {
"command": "node",
"args": ["${CLAUDE_PLUGIN_ROOT}/servers/server.js"],
"env": {
"API_KEY": "${API_KEY}"
}
}
}
}
Usage: MCP servers integrate seamlessly with Claude Code's tool system
Portable Path References
${CLAUDE_PLUGIN_ROOT}
Use ${CLAUDE_PLUGIN_ROOT} environment variable for all intra-plugin path references:
{
"command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/run.sh"
}
Why it matters: Plugins install in different locations depending on:
- User installation method (marketplace, local, npm)
- Operating system conventions
- User preferences
Where to use it:
- Hook command paths
- MCP server command arguments
- Script execution references
- Resource file paths
Never use:
- Hardcoded absolute paths (
/Users/name/plugins/...) - Relative paths from working directory (
./scripts/...in commands) - Home directory shortcuts (
~/plugins/...)
Path Resolution Rules
In manifest JSON fields (hooks, MCP servers):
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/tool.sh"
In component files (commands, agents, skills):
Reference scripts at: ${CLAUDE_PLUGIN_ROOT}/scripts/helper.py
In executed scripts:
#!/bin/bash
# ${CLAUDE_PLUGIN_ROOT} available as environment variable
source "${CLAUDE_PLUGIN_ROOT}/lib/common.sh"
File Naming Conventions
Component Files
Commands: Use kebab-case .md files
code-review.md→/code-reviewrun-tests.md→/run-testsapi-docs.md→/api-docs
Agents: Use kebab-case .md files describing role
test-generator.mdcode-reviewer.mdperformance-analyzer.md
Skills: Use kebab-case directory names
api-testing/database-migrations/error-handling/
Supporting Files
Scripts: Use descriptive kebab-case names with appropriate extensions
validate-input.shgenerate-report.pyprocess-data.js
Documentation: Use kebab-case markdown files
api-reference.mdmigration-guide.mdbest-practices.md
Configuration: Use standard names
hooks.json.mcp.jsonplugin.json
Auto-Discovery Mechanism
Claude Code automatically discovers and loads components:
- Plugin manifest: Reads
.claude-plugin/plugin.jsonwhen plugin enables - Commands: Scans
commands/directory for.mdfiles - Agents: Scans
agents/directory for.mdfiles - Skills: Scans
skills/for subdirectories containingSKILL.md - Hooks: Loads configuration from
hooks/hooks.jsonor manifest - MCP servers: Loads configuration from
.mcp.jsonor manifest
Discovery timing:
- Plugin installation: Components register with Claude Code
- Plugin enable: Components become available for use
- No restart required: Changes take effect on next Claude Code session
Override behavior: Custom paths in plugin.json supplement (not replace) default directories
Best Practices
Organization
-
Logical grouping: Group related components together
- Put test-related commands, agents, and skills together
- Create subdirectories in
scripts/for different purposes
-
Minimal manifest: Keep
plugin.jsonlean- Only specify custom paths when necessary
- Rely on auto-discovery for standard layouts
- Use inline configuration only for simple cases
-
Documentation: Include README files
- Plugin root: Overall purpose and usage
- Component directories: Specific guidance
- Script directories: Usage and requirements
Naming
-
Consistency: Use consistent naming across components
- If command is
test-runner, name related agenttest-runner-agent - Match skill directory names to their purpose
- If command is
-
Clarity: Use descriptive names that indicate purpose
- Good:
api-integration-testing/,code-quality-checker.md - Avoid:
utils/,misc.md,temp.sh
- Good:
-
Length: Balance brevity with clarity
- Commands: 2-3 words (
review-pr,run-ci) - Agents: Describe role clearly (
code-reviewer,test-generator) - Skills: Topic-focused (
error-handling,api-design)
- Commands: 2-3 words (
Portability
- Always use ${CLAUDE_PLUGIN_ROOT}: Never hardcode paths
- Test on multiple systems: Verify on macOS, Linux, Windows
- Document dependencies: List required tools and versions
- Avoid system-specific features: Use portable bash/Python constructs
Maintenance
- Version consistently: Update version in plugin.json for releases
- Deprecate gracefully: Mark old components clearly before removal
- Document breaking changes: Note changes affecting existing users
- Test thoroughly: Verify all components work after changes
Common Patterns
Minimal Plugin
Single command with no dependencies:
my-plugin/
├── .claude-plugin/
│ └── plugin.json # Just name field
└── commands/
└── hello.md # Single command
Full-Featured Plugin
Complete plugin with all component types:
my-plugin/
├── .claude-plugin/
│ └── plugin.json
├── commands/ # User-facing commands
├── agents/ # Specialized subagents
├── skills/ # Auto-activating skills
├── hooks/ # Event handlers
│ ├── hooks.json
│ └── scripts/
├── .mcp.json # External integrations
└── scripts/ # Shared utilities
Skill-Focused Plugin
Plugin providing only skills:
my-plugin/
├── .claude-plugin/
│ └── plugin.json
└── skills/
├── skill-one/
│ └── SKILL.md
└── skill-two/
└── SKILL.md
Troubleshooting
Component not loading:
- Verify file is in correct directory with correct extension
- Check YAML frontmatter syntax (commands, agents, skills)
- Ensure skill has
SKILL.md(notREADME.mdor other name) - Confirm plugin is enabled in Claude Code settings
Path resolution errors:
- Replace all hardcoded paths with
${CLAUDE_PLUGIN_ROOT} - Verify paths are relative and start with
./in manifest - Check that referenced files exist at specified paths
- Test with
echo $CLAUDE_PLUGIN_ROOTin hook scripts
Auto-discovery not working:
- Confirm directories are at plugin root (not in
.claude-plugin/) - Check file naming follows conventions (kebab-case, correct extensions)
- Verify custom paths in manifest are correct
- Restart Claude Code to reload plugin configuration
Conflicts between plugins:
- Use unique, descriptive component names
- Namespace commands with plugin name if needed
- Document potential conflicts in plugin README
- Consider command prefixes for related functionality
For detailed examples and advanced patterns, see files in references/ and examples/ directories.
Arquivos desta skill
5Perguntas sobre a skill plugin-structure
Como instalo a skill plugin-structure no Claude Code?
Execute npx degit thevibeworks/claude-code-docs/content/github/claude-plugins-official/plugins/plugin-dev/skills/plugin-structure ~/.claude/skills/plugin-structure. O Claude Code carrega skills de ~/.claude/skills (todos os projetos) ou .claude/skills (um projeto) e usa uma skill quando a descrição dela corresponde à tarefa.
Quais clientes podem usar a skill plugin-structure?
Qualquer cliente que leia o formato Agent Skills: Claude Code, Codex, Gemini CLI e claude.ai (envie como ZIP). Scripts da skill são executados apenas onde o cliente permite execução de código.
Como faço para referenciar arquivos dentro do meu plugin para garantir portabilidade?
Você deve usar a variável de ambiente ${CLAUDE_PLUGIN_ROOT} para todas as referências de caminhos internos do plugin, em vez de usar caminhos absolutos ou relativos fixos no código.
Posso usar diretórios personalizados para comandos ou agentes?
Sim, você pode especificar caminhos personalizados no manifesto plugin.json, o que complementará os diretórios padrão.