Claude Code插件生态全实战：发现、安装到自研发布

graph LR
    A["阶段一<br/>CLAUDE.md 手工指令"] --> B["阶段二<br/>Skills 单文件封装"]
    B --> C["阶段三<br/>Plugins 标准化分发"]

    style A fill:#e8f4f8
    style B fill:#b8d4e3
    style C fill:#4a90d9,color:#fff

graph TB
    subgraph "Plugin Architecture"
        P["plugin.json<br/>元数据"]
        P --> SK["skills/<br/>知识 & 命令"]
        P --> CM["commands/<br/>斜杠命令 (legacy)"]
        P --> AG["agents/<br/>专业Agent"]
        P --> HK["hooks/<br/>事件钩子"]
        P --> MCP[".mcp.json<br/>外部工具"]
    end

    SK --> |"自动匹配"| CL["Claude 主循环"]
    CM --> |"/command"| CL
    AG --> |"Task dispatch"| CL
    HK --> |"事件触发"| CL
    MCP --> |"工具调用"| CL

    style P fill:#2d3748,color:#fff
    style CL fill:#4a90d9,color:#fff

> /plugin

  Plugin Manager
  ────────────────────────────────────────
  1. Installed     (3 plugins)
  2. Discover      (browse official marketplace)
  3. Browse        (search all marketplaces)

# 从官方目录安装
claude plugin install commit-commands@claude-plugins-official

# 从自定义Marketplace安装
claude plugin install my-plugin@my-company-marketplace

# 从本地路径安装（开发模式）
claude plugin install ./path/to/my-plugin

{
  "plugins": {
    "enabled": [
      "commit-commands@claude-plugins-official",
      "code-review@claude-plugins-official",
      "security-guidance@claude-plugins-official"
    ]
  }
}

# 列出所有已安装插件
claude plugin list

# 查看特定插件详情
claude plugin details commit-commands

# 检查插件健康状态
/doctor

claude plugin install code-review@claude-plugins-official

> /code-review

claude plugin install security-guidance@claude-plugins-official

claude plugin install feature-dev@claude-plugins-official

> /feature-dev 添加用户导出CSV功能

graph TD
    D["Phase 1<br/>需求发现"] --> E["Phase 2<br/>代码库探索"]
    E --> F["Phase 3<br/>澄清问题"]
    F --> G["Phase 4<br/>架构设计"]
    G --> H["Phase 5<br/>实现"]
    H --> I["Phase 6<br/>代码审查"]
    I --> J["Phase 7<br/>交付"]

    style D fill:#e2f0d9
    style G fill:#d9e2f3
    style H fill:#fde9d9
    style J fill:#d9d2e9

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # 必需：插件元数据
├── skills/                  # 推荐：Skills目录
│   ├── my-skill/
│   │   └── SKILL.md         # 自动匹配的Skill
│   └── my-command/
│       └── SKILL.md         # 用户触发的斜杠命令
├── agents/                  # 可选：Agent定义
│   └── my-agent.md
├── hooks/                   # 可选：事件钩子
│   └── session-start.sh
├── .mcp.json               # 可选：MCP服务器配置
└── README.md               # 推荐：文档

{
  "name": "my-plugin",
  "description": "一句话描述插件功能",
  "version": "1.0.0",
  "author": {
    "name": "你的名字",
    "email": "[email protected]",
    "url": "https://github.com/yourname"
  },
  "homepage": "https://github.com/yourname/my-plugin",
  "repository": {
    "type": "git",
    "url": "https://github.com/yourname/my-plugin.git"
  },
  "license": "MIT",
  "keywords": ["git", "workflow", "automation"],
  "dependencies": {
    "other-plugin@marketplace-name": ">=1.0.0"
  }
}

---
name: api-design-patterns
description: Use when designing REST or GraphQL APIs, including endpoint design, error handling, and versioning strategies
version: 1.0.0
---

---
name: gen-api
description: Generate API endpoint boilerplate
argument-hint: <method> <path>
allowed-tools: [Read, Write, Edit, Glob, Grep]
---

---
name: db-schema-analyzer
description: Analyzes database schema for normalization issues and optimization opportunities
tools: [Read, Glob, Grep, Task]
effort: high
model: sonnet
---

You are a database schema analysis specialist. Your job is to:

1. Read all migration files and schema definitions
2. Identify normalization violations (1NF, 2NF, 3NF)
3. Check for missing indexes on foreign keys
4. Suggest query optimization opportunities
5. Return a list of the 5-10 most important files for the main agent to review

{
  "name": "my-plugin",
  "description": "...",
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "echo '🚀 Session started at $(date)'"
      }
    ],
    "PreToolUse": [
      {
        "type": "command",
        "command": "scripts/check-security.sh",
        "matcher": "Edit|Write"
      }
    ]
  }
}

{
  "my-database": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "my-db-mcp-server"],
    "env": {
      "DB_URL": "${DB_CONNECTION_STRING}"
    }
  },
  "my-api": {
    "type": "http",
    "url": "https://api.example.com/mcp",
    "headers": {
      "Authorization": "Bearer ${API_TOKEN}"
    }
  }
}

mkdir ts-guardian && cd ts-guardian
mkdir -p .claude-plugin skills/ts-guard skills/ts-type-safety agents hooks

{
  "name": "ts-guardian",
  "description": "TypeScript type safety analysis with automated checking, expert guidance, and pre-commit validation",
  "version": "1.0.0",
  "author": {
    "name": "Your Name",
    "url": "https://github.com/yourname"
  },
  "homepage": "https://github.com/yourname/ts-guardian",
  "license": "MIT",
  "keywords": ["typescript", "type-safety", "static-analysis"],
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "bash hooks/pre-edit-typecheck.sh",
        "matcher": "Edit|Write"
      }
    ]
  }
}

---
name: ts-guard
description: Analyze TypeScript type safety across the project
argument-hint: [path or glob pattern]
allowed-tools: [Read, Glob, Grep, Bash, Task, TodoWrite]
---

# TypeScript Type Safety Analysis

Analyze the TypeScript project for type safety issues. Follow this systematic approach:

## Step 1: Project Scan

Run a comprehensive type check:

```bash
npx tsc --noEmit --strict 2>&1 | head -100

# Find 'as any' casts
grep -rn "as any" --include="*.ts" --include="*.tsx" $ARGUMENTS .

# Find non-null assertions (!)
grep -rn "!\." --include="*.ts" --include="*.tsx" $ARGUMENTS .

# Find @ts-ignore / @ts-expect-error
grep -rn "@ts-" --include="*.ts" --include="*.tsx" $ARGUMENTS .

## Type Safety Report

### Summary
- Total files scanned: X
- Critical issues: X
- Warnings: X
- Info: X

### Critical Issues
| File | Line | Issue | Suggestion |
|------|------|-------|------------|
| ... | ... | ... | ... |

### Recommended Fixes
[Prioritized list of changes]

### 5.4 自动触发 Skill

创建 `skills/ts-type-safety/SKILL.md`：

```yaml
---
name: ts-type-safety
description: Use when writing or editing TypeScript code, providing type safety guidance and best practices
version: 1.0.0
allowed-tools: [Read, Edit, Glob, Grep]
---

# TypeScript Type Safety Guidelines

When working with TypeScript code in this project, follow these principles:

## Strict Type Practices

1. **Never use `any`** - Use `unknown` for truly unknown types, then narrow with type guards
2. **Prefer interfaces over type aliases** for object shapes (better error messages and declaration merging)
3. **Use discriminated unions** for state machines and polymorphic data
4. **Enable strict mode** - Ensure `tsconfig.json` has `"strict": true`

## Common Patterns

### Instead of `as any`:
```typescript
// Bad
const data = response as any;

// Good
const data: unknown = response;
if (isValidResponse(data)) {
  // data is now properly typed
}

// Bad
const user = users.find(u => u.id === id)!;

// Good
const user = users.find(u => u.id === id);
if (!user) throw new Error(`User ${id} not found`);

function isString(value: unknown): value is string {
  return typeof value === 'string';
}

function hasProperty<T extends string>(
  obj: unknown, 
  prop: T
): obj is Record<T, unknown> {
  return typeof obj === 'object' && obj !== null && prop in obj;
}

### 5.5 专业 Agent

创建 `agents/ts-type-deep-analyzer.md`：

```yaml
---
name: ts-type-deep-analyzer
description: Deep analysis of complex TypeScript type issues, tracing type flow through the codebase
tools: [Read, Glob, Grep]
effort: high
model: sonnet
---

You are a TypeScript type system expert. Your task is to perform deep analysis of type safety issues in specific files.

## Analysis Process

1. **Read the target file completely** - understand the full type context
2. **Trace type origins** - find where problematic types are defined or inferred
3. **Check upstream dependencies** - what functions/APIs feed into this code?
4. **Identify root causes** - is the issue from missing generics, loose types, or type assertions?
5. **Return findings** with:
   - List of 5-10 most important related files
   - Root cause analysis for each issue
   - Concrete type-safe fix suggestions with code examples

## Focus Areas

- Generic type parameter inference failures
- Excess property checking bypass
- Covariance/contravariance issues in function types
- Conditional type complexity
- Template literal type patterns
- Module augmentation side effects

#!/bin/bash
# Pre-edit type safety check
# Only runs for TypeScript files

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Only check TypeScript files
if [[ "$FILE_PATH" =~ \.(ts|tsx)$ ]]; then
    # Check if tsc is available
    if command -v npx &>/dev/null; then
        ERRORS=$(npx tsc --noEmit 2>&1 | tail -5)
        ERROR_COUNT=$(npx tsc --noEmit 2>&1 | grep -c "error TS" || echo "0")

        if [ "$ERROR_COUNT" -gt 0 ]; then
            echo "⚠️  TypeScript has $ERROR_COUNT errors. Recent:"
            echo "$ERRORS"
        fi
    fi
fi

# Exit 0 to allow the edit (this is advisory only)
exit 0

chmod +x hooks/pre-edit-typecheck.sh

ts-guardian/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── ts-guard/
│   │   └── SKILL.md          # /ts-guard 斜杠命令
│   └── ts-type-safety/
│       └── SKILL.md          # 自动触发的类型安全指南
├── agents/
│   └── ts-type-deep-analyzer.md  # 深度分析Agent
├── hooks/
│   └── pre-edit-typecheck.sh     # 编辑前检查脚本
└── README.md

# 在测试项目中安装本地插件
cd ~/projects/my-ts-project
claude plugin install ~/path/to/ts-guardian

> /help
# 应该看到 /ts-guard 命令

> /ts-guard src/
# 运行类型安全分析

> 创建一个 UserService 类
# ts-type-safety skill 应自动激活，提供类型安全指导

> /doctor

  Plugin: ts-guardian
  ├── Status: ✅ loaded
  ├── Skills: 2 (ts-guard, ts-type-safety)
  ├── Agents: 1 (ts-type-deep-analyzer)
  ├── Hooks: 1 (PreToolUse → pre-edit-typecheck.sh)
  └── MCP Servers: 0

# 创建Marketplace仓库
mkdir my-company-plugins && cd my-company-plugins
git init

# 创建manifest文件
cat > manifest.json << 'MANIFEST'
{
  "name": "my-company-plugins",
  "description": "Internal plugins for My Company",
  "plugins": {
    "ts-guardian": {
      "ref": "main",
      "sha": "abc123...",
      "path": "plugins/ts-guardian"
    }
  }
}
MANIFEST

# 添加插件目录
mkdir -p plugins
# 将 ts-guardian 复制到 plugins/ts-guardian/

git add . && git commit -m "Initial marketplace"
git remote add origin [email protected]:mycompany/claude-plugins.git
git push -u origin main

claude plugin marketplace add my-company-plugins \
  --source [email protected]:mycompany/claude-plugins.git

{
  "dependencies": {
    "security-guidance@claude-plugins-official": ">=1.0.0"
  }
}

❌ Cannot disable "security-guidance": "ts-guardian" depends on it.
   Disable chain: disable ts-guardian first, then security-guidance.

💡 Tip: Install the ts-guardian plugin for automatic TypeScript type checking.
   Run: claude plugin install ts-guardian@claude-plugins-official

# 差 - 太泛
description: Use when working with TypeScript

# 好 - 精确
description: Use when writing or editing TypeScript code that involves type annotations, generics, type guards, or strict null checks

# 查看插件加载日志
/doctor

# 验证插件结构
claude plugin validate ./ts-guardian

# 查看插件详情和预估token成本
claude plugin details ts-guardian

# 检查特定Hook的触发情况
/permissions

flowchart TB
    subgraph "发现阶段"
        A["/plugin > Discover"] --> B["选择插件"]
        B --> C["查看详情<br/>组件清单 + token成本"]
    end

    subgraph "安装阶段"
        C --> D["claude plugin install"]
        D --> E["配置环境变量<br/>（如需要）"]
        E --> F["验证 /doctor"]
    end

    subgraph "使用阶段"
        F --> G{插件类型}
        G --> |"Command"| H["/command-name 触发"]
        G --> |"Skill"| I["Claude 自动匹配"]
        G --> |"Agent"| J["Task 工具分发"]
        G --> |"Hook"| K["事件自动触发"]
        G --> |"MCP"| L["Claude 主动调用"]
    end

    subgraph "管理阶段"
        H --> M["claude plugin list"]
        I --> M
        J --> M
        K --> M
        L --> M
        M --> N["update / disable / uninstall"]
    end

    style A fill:#4a90d9,color:#fff
    style D fill:#2d3748,color:#fff
    style G fill:#7c3aed,color:#fff
    style M fill:#059669,color:#fff

skills/
└── ts-guard/          # 目录名
    └── SKILL.md       # name: ts-guard  ← 必须匹配

> /ts-guardian:ts-guard

# 在有网络的机器上下载
git clone https://github.com/yourorg/claude-plugins.git /tmp/plugins

# 打包传输
tar czf plugins.tar.gz -C /tmp/plugins .

# 在离线机器上
tar xzf plugins.tar.gz -C ~/company-plugins
claude plugin marketplace add company --source ~/company-plugins
claude plugin install ts-guardian@company