This repository is a Claude Code marketplace containing plugins, agents, commands, hooks, skills, and scripts. When working in this codebase, you are developing Claude Code extensions - apply best practices accordingly.

CRITICAL: Before ANY modification to this package, use the developing-claude-plugins skill to ensure:

• Consistency with existing patterns and structure
• Adherence to current Claude Code best practices
• Optimal configuration and naming conventions

All Claude Code best practices are cached locally in .claude/docs-cache/*.md. This is the single source of truth for this repository.

• Configuration: .claude/docs-cache/sources.json (SINGLE SOURCE OF TRUTH)
• Auto-Update: The /optimize command checks for version changes and offers to update

Scripts:

Source types in sources.json:

• md: Direct Markdown files (downloaded as-is, relative links converted to absolute GitHub URLs)
• html: HTML pages (converted to Markdown via Turndown)
• spa: Single Page Applications (rendered with Playwright, then converted)
• pdf: PDF documents (manually converted to Markdown, not auto-updated by scripts)

Error handling: If a source fails to fetch, existing cache is preserved (no data loss)

If documentation cache is insufficient:

1. WebSearch: Use WebSearch with query: "Claude Code [topic] documentation site:anthropic.com OR site:claude.com"
2. Claude's Built-in Knowledge: Claude knows Claude Code best practices (Knowledge Cutoff: May 2025)

claude-code/
├── .claude/                  # Project-level Claude Code extensions
│   ├── docs-cache/           # Cached Claude Code documentation (Markdown)
│   │   ├── sources.json      # URL configuration (SINGLE SOURCE OF TRUTH)
│   │   └── *.md              # Auto-generated from sources.json
│   ├── scripts/              # Utility scripts
│   │   ├── update-docs-cache.ts    # Downloads & converts docs (parallel)
│   │   ├── check-cache-version.ts  # Checks if cache is outdated
│   │   ├── check-cache-integrity.ts # Verifies all cache files exist
│   │   ├── types.ts                # Shared TypeScript types
│   │   └── types.d.ts              # Module declarations
│   ├── skills/               # Project-specific skills
│   │   └── marketplace-optimizer/
│   │       └── SKILL.md              # Marketplace optimization orchestrator
│   ├── agents/               # Project-specific agents (optimizer specialists)
│   │   ├── optimizer-skills.md       # Skills optimization expert
│   │   ├── optimizer-commands.md     # Commands optimization expert
│   │   ├── optimizer-agents.md       # Agents optimization expert
│   │   ├── optimizer-hooks.md        # Hooks optimization expert
│   │   ├── optimizer-mcp.md          # MCP optimization expert
│   │   └── optimizer-marketplace.md  # Cross-references & features expert
│   └── commands/             # Project-specific commands
│       └── optimize.md       # /optimize command
├── .claude-plugin/
│   └── marketplace.json      # Marketplace definition
├── plugins/
│   └── lt-dev/               # Main plugin
│       ├── .claude-plugin/
│       │   └── plugin.json   # Plugin manifest
│       ├── agents/           # Autonomous agents (.md files)
│       ├── commands/         # Slash commands (.md files, can be nested)
│       ├── hooks/            # Event hooks
│       │   ├── hooks.json    # Hook definitions
│       │   └── scripts/      # Hook handler scripts (.sh, .ts)
│       ├── scripts/          # Plugin helper scripts referenced by commands/agents/skills
│       │                     # (e.g. discover-check-scripts.sh) — narrow Bash permission
│       │                     # pattern: Bash(bash ${CLAUDE_PLUGIN_ROOT}/scripts/*)
│       ├── skills/           # Context-aware expertise (SKILL.md + references)
│       ├── permissions.json  # Bash permission patterns for auto-approval
│       ├── permissions.schema.json  # JSON Schema for permissions validation
│       └── .mcp.json         # MCP server dependencies

CRITICAL: The plugins/ directory is deployed to client machines and runs in isolation.

Consequences:

• Elements in plugins/ cannot access .claude/docs-cache/, .claude/scripts/, or any other repository files
• Elements in plugins/ must use external sources (WebFetch to GitHub, WebSearch) for documentation
• Elements in .claude/ and CLAUDE.md can access plugins/ and all repository files

When developing plugin elements:

• Use WebFetch with GitHub raw URLs for documentation
• Use WebSearch for Claude Code documentation lookups
• Never reference paths like .claude/docs-cache/ or bun .claude/scripts/...

Defines Bash command patterns that can be auto-approved without user confirmation.

Update when:

• Adding new Bash commands to skills or agents (npm, lt, npx, etc.)
• Creating new skills that use CLI tools

Structure:

{
  "permissions": [
    {
      "pattern": "Bash(npm test:*)",
      "description": "Run npm test commands",
      "usedBy": ["skill-name-1", "skill-name-2"]
    }
  ]
}

Rules:

• Always add usedBy array with skill/agent names that need the permission
• Use wildcard patterns (:*) for flexible matching
• Keep descriptions clear and concise

Validation: Use permissions.schema.json for IDE autocompletion and validation. Reference it via "$schema": "./permissions.schema.json" in permissions.json.

Defines MCP (Model Context Protocol) servers required by the plugin.

Update when:

• Commands or skills require external MCP tools (Linear, Chrome DevTools, etc.)
• Adding new integrations that use MCP servers

Current servers:

Plugin manifest with metadata. Update version before releases.

• Skills: SKILL.md (main) + supporting .md files in skill directory
• Commands: command-name.md (kebab-case)
• Agents: agent-name.md (kebab-case)
• Hooks: hooks.json + referenced scripts

---
name: skill-name
description: Concise description for auto-detection (max 1024 chars). Must explain WHEN to use this skill. Include trigger terms for auto-detection.
# Optional fields:
allowed-tools: Read, Grep, Glob  # Restrict available tools
model: sonnet | opus | haiku     # Override default model
context: fork                     # Run in isolated sub-agent
user-invocable: false            # Hide from slash command menu
---

---
description: What this command does (shown in /help)
# Optional fields:
allowed-tools: Bash(git:*), Read  # Restrict available tools
argument-hint: "[branch-name]"    # MUST quote values with brackets (YAML parses [...] as arrays)
model: haiku                      # Use specific model
disable-model-invocation: false   # Prevent SlashCommand tool use
---

• argument-hint: Always quote values containing [...] brackets: "[arg-name]"
• description: Quote with single quotes when containing embedded "..." double quotes: 'Activates when user mentions "keyword"'
• Validation: Run claude plugin validate plugins/lt-dev to catch YAML parse errors

---
name: agent-name
description: When and how to use this agent
model: sonnet | opus | haiku
tools: Bash, Read, Grep, Glob, Write, Edit, ...
permissionMode: default | acceptEdits | dontAsk | bypassPermissions
skills: optional-skill-names
---

• Skills: Focus on WHEN to use (triggers auto-detection)
• Commands: Focus on WHAT it does
• Agents: Focus on WHAT tasks it handles autonomously

• Use consistent heading levels (# for title, ## for sections)
• Include examples for complex workflows
• Reference related elements explicitly
• Keep markdown clean and scannable

• One responsibility per element
• Clear separation between skill (expertise) and command (action)
• Prefer composition over duplication
• Document dependencies between elements
• Test all commands and workflows manually

• No history references: Never mention "new", "updated", "changed from", or version-specific info in descriptions
• Timeless documentation: Write as if features always existed (no "since v2.1" or "added in")
• Compact content: Minimize tokens while maintaining clarity and completeness
• No over-compression: Never remove important information for token savings

Use the /lt-dev:plugin:element command to interactively create new elements with:

• Best practice compliance
• Consistent structure
• Proper frontmatter
• Automatic placement

After creating elements, also update:

1. permissions.json - If the element uses new Bash commands
2. .mcp.json - If the element requires new MCP servers
3. Related Skills sections - Add cross-references to related skills
4. "When to Use" sections - For commands that are part of a workflow

If the conversation was reset with /clear or context was summarized, run:

/lt-dev:plugin:check

This restores best practice awareness and validates any pending changes.

For comprehensive optimization after context loss, use:

/optimize

When optimizing existing elements:

1. Read the documentation cache (.claude/docs-cache/*.md)
2. Analyze existing element against best practices
3. Propose specific improvements
4. Implement changes with minimal disruption
5. Verify consistency with related elements

For batch optimization with user selection, use:

/optimize

• All code, comments, and documentation: English
• Exception: User-facing German content where explicitly required (e.g., create-story.md)

Run /lt-dev:plugin:check periodically or before releases to verify:

• All SKILL.md have valid frontmatter (name, description)
• All referenced .md files exist
• "Related Skills" sections are present and accurate
• Descriptions include trigger terms for auto-detection

• All commands have description in frontmatter
• Complex/related commands have "When to Use" sections
• allowed-tools is set where appropriate (especially git commands)
• argument-hint is set for commands accepting arguments

• Frontmatter includes: name, description, model, tools, permissionMode
• Skills referenced in frontmatter exist
• Agent tasks are clearly defined

• hooks.json is valid JSON
• All referenced scripts in hooks/scripts/ exist
• Hook matchers are correctly configured

• permissions.json: All Bash patterns used by skills/agents are listed
• permissions.json: usedBy arrays are complete and accurate
• .mcp.json: All required MCP servers are configured
• plugin.json: Version is updated before release

• No history references in any element ("new", "updated", "since vX.Y")
• No version-specific markers in descriptions
• Content is complete (no over-compression)

• CLAUDE.md: Repository structure matches actual layout
• CLAUDE.md: Configuration file docs are current
• All cross-references between elements are valid