90 lines
2.4 KiB
Markdown
90 lines
2.4 KiB
Markdown
# Plugin Caching Reference
|
|
|
|
How Claude Code caches plugins and implications for plugin structure.
|
|
|
|
## How Plugin Caching Works
|
|
|
|
When plugins are installed, Claude Code copies them to a cache directory for security. This affects how you structure shared resources.
|
|
|
|
## Path Traversal Limitation
|
|
|
|
Paths that traverse outside the plugin root will not work after installation:
|
|
|
|
```
|
|
# BROKEN after install - traverses outside plugin
|
|
../../shared-utils/helper.sh
|
|
../other-plugin/rules/FORMATTING.md
|
|
```
|
|
|
|
Only files within the plugin directory are copied to the cache.
|
|
|
|
## Shared Resources Within a Plugin
|
|
|
|
Organize shared resources inside your plugin:
|
|
|
|
```
|
|
my-plugin/
|
|
├── .claude-plugin/
|
|
│ └── plugin.json
|
|
├── rules/ # Shared rules
|
|
│ └── FORMATTING.md
|
|
├── scripts/ # Shared scripts
|
|
│ └── validate.sh
|
|
└── skills/
|
|
└── my-skill/
|
|
└── SKILL.md # Can reference ../../rules/FORMATTING.md
|
|
```
|
|
|
|
Skills can reference `../../rules/FORMATTING.md` because it stays within the plugin.
|
|
|
|
## Cross-Plugin Dependencies
|
|
|
|
If plugins need to share resources across plugin boundaries, you have three options:
|
|
|
|
### Option 1: Symlinks
|
|
|
|
Create symlinks within your plugin that point to external files. Symlinks are followed during the copy:
|
|
|
|
```bash
|
|
# Inside your plugin directory
|
|
ln -s /path/to/shared-utils ./shared-utils
|
|
```
|
|
|
|
### Option 2: Restructure Marketplace
|
|
|
|
Set the marketplace source to a parent directory containing all plugins:
|
|
|
|
```json
|
|
{
|
|
"name": "my-plugin",
|
|
"source": "./",
|
|
"description": "Plugin with access to sibling directories",
|
|
"commands": ["./plugins/my-plugin/commands/"],
|
|
"skills": ["./plugins/my-plugin/skills/"],
|
|
"strict": false
|
|
}
|
|
```
|
|
|
|
This copies the entire marketplace root, giving plugins access to siblings.
|
|
|
|
### Option 3: Skill Invocation (Recommended)
|
|
|
|
Instead of file references, use skill invocation for cross-plugin patterns:
|
|
|
|
```markdown
|
|
## Related Skills
|
|
|
|
- **outfitter:tdd** - Test-driven development patterns
|
|
- **outfitter:debugging** - Systematic debugging methodology
|
|
```
|
|
|
|
Reference skills by `plugin:skill-name` and invoke with the Skill tool.
|
|
|
|
## Best Practice
|
|
|
|
**Prefer Option 3** (skill invocation) when possible. It:
|
|
- Avoids caching complexity
|
|
- Works regardless of installation method
|
|
- Maintains clean plugin boundaries
|
|
- Enables proper versioning of dependencies
|