概述

Skills Marketplace 是一个面向 AI 代理工具的插件市场平台，旨在为 Claude Code 和 Codex CLI 提供可扩展的技能（Skills）生态系统。该项目遵循 Agent Skills 规范，确保与多种 Agent Skills 兼容工具的互操作性。

资料来源：README.md:1-10

核心定位

该市场平台充当插件注册中心（registry），聚合来自不同来源的插件，并为 Claude Code 和 Codex CLI 用户提供统一的安装和管理体验。

资料来源：README.md:1-5

架构设计

目录结构

graph TD
    A[skills-marketplace] --> B[registry/]
    A --> C[plugins/]
    A --> D[scripts/]
    B --> E[plugins.json]
    C --> F[plugin-a/]
    C --> G[plugin-b/]
    F --> H[SKILL.md]
    F --> I[rules/]
    F --> J[references/]
    F --> K[plugin.json]

项目的核心目录结构说明：

资料来源：README.md:15-20

插件清单机制

插件清单（Manifest）通过 scripts/generate-manifests.py 脚本生成，生成的 marketplace catalog 直接指向 GitHub 固定引用（pinned refs）。

graph LR
    A[GitHub Repo] --> B[generate-manifests.py]
    B --> C[Marketplace Catalog]
    C --> D[Claude Code]
    C --> E[Codex CLI]

资料来源：README.md:10-15

插件系统

插件结构

每个插件必须包含以下核心文件：

资料来源：README.md:15-20

插件配置示例

registry/plugins.json 中定义的插件条目包含以下字段：

{
  "name": "israel-services",
  "description": "Access Israeli citizen services...",
  "repository": "https://github.com/avivsinai/israel-services",
  "source": {
    "source": "github",
    "repo": "avivsinai/israel-services",
    "ref": "main",
    "sha": "ce0cd9b5ddceb56dd8f458e20cc93880f5a0ef3d"
  },
  "version": "ce0cd9b5ddce",
  "keywords": ["israel", "health", "banking", "clalit", "poalim"],
  "category": "Automation",
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_FIRST_USE"
  },
  "sync": {
    "mode": "main"
  }
}

资料来源：registry/plugins.json:50-80

插件分类

插件按功能领域分类：

资料来源：registry/plugins.json:20-45

技能（Skills）结构

技能文档类型

资料来源：plugins/amq-spec/skills/amq-spec/SKILL.md:1-10

消息格式规范

AMQ 消息采用 Markdown 文件格式，包含 JSON frontmatter 头部：

---json
{
  "schema": 1,
  "id": "<msg_id>",
  "from": "claude",
  "to": ["codex"],
  "thread": "p2p/claude__codex",
  "subject": "Optional summary",
  "kind": "question",
  "labels": ["bug", "parser"]
}

什么是 Skills Marketplace

Skills Marketplace 是一个基于 Agent Skills 规范的插件市场，为 Claude Code、Codex CLI 等 Agent 工具提供可扩展的技能集合。每个插件都包含一组预定义的命令、参考文档和工作流程，帮助用户完成特定领域的任务。

资料来源：README.md:1-5

核心概念

插件架构

插件采用标准化的目录结构，包含技能定义、命令规则和参考文档：

plugins/
├── plugin.json              # Codex 插件清单
└── skills/
    └── ...                  # 共享技能负载

资料来源：README.md:18-22

工作流程标签系统

平台使用标准 AMQ 消息格式，通过标签（labels）区分不同阶段的工作流程：

workflow:spec,phase:research   # 研究阶段
workflow:spec,phase:discuss     # 讨论阶段
workflow:spec,phase:draft       # 起草阶段
workflow:spec,phase:review       # 审查阶段

资料来源：plugins/amq-cli/skills/amq-cli/references/message-format.md:18-20

快速安装

前置要求

安装步骤

1. 克隆仓库

git clone https://github.com/avivsinai/skills-marketplace.git
cd skills-marketplace

1. 查看可用插件

查看 registry/plugins.json 文件获取所有可用插件列表。

1. 配置插件

对于 Claude Code，生成的市场目录直接指向固定的 GitHub 引用。资料来源：README.md:24-25

常用插件速查

AMQ 通信插件

用于多 Agent 之间异步通信和协作设计。

发送消息示例：

amq send --to <partner> --kind brainstorm \
  --labels workflow:spec,phase:research \
  --thread spec/<topic> --subject "Research: <topic>" \
  --body "<your findings>"

资料来源：plugins/amq-cli/skills/amq-spec/references/spec-workflow.md:12-16

查看线程：

amq thread --id spec/<topic> --include-body

监听消息：

amq watch --timeout 120s

Bitbucket 插件 (bkt)

检查构建状态和 CI 结果。

资料来源：plugins/bkt/skills/bkt/rules/status.md:4-18

示例：

# 显示提交状态
bkt status commit abc1234def5678

# 以 JSON 格式输出
bkt status commit abc1234 --format json

Jenkins 插件 (jk)

与 Jenkins CI 系统交互。

资料来源：plugins/jk/skills/jk/rules/run.md:4-11

示例：

# 搜索作业
jk run search --filter "deploy"

# 启动作业并跟踪
jk run start <jobPath> --follow

Langfuse 插件

用于 LLM 应用的可观测性和提示管理。

追踪工具：

提示管理：

资料来源：plugins/langfuse/skills/langfuse/references/tool-reference.md:1-45

协作设计工作流程

当使用多 Agent 进行协作设计时，遵循标准化的六阶段流程：

graph TD
    A[1. 研究阶段<br>Research] --> B[2. 讨论阶段<br>Discuss]
    B --> C[3. 起草阶段<br>Draft]
    C --> D[4. 审查阶段<br>Review]
    D --> E[5. 呈现阶段<br>Present]
    E --> F[6. 执行阶段<br>Execute]
    
    A -->|并行研究| A1[发起方研究]
    A -->|并行研究| A2[接收方研究]

禁止事项

• 独自研究后直接发送完整方案给搭档
• 跳过讨论阶段
• 在用户批准前实施

资料来源：plugins/amq-cli/skills/amq-spec/references/spec-workflow.md:45-60

添加新插件

如需为市场贡献新插件，按以下步骤操作：

资料来源：README.md:30-37

同步机制

平台采用多层次自动同步策略：

graph LR
    A[主插件<br>registry/plugins.json] --> B[GitHub Actions<br>sync-releases.yml]
    B --> C{检查更新}
    C -->|有新版本| D[更新清单<br>提交到 main]
    C -->|无更新| E[保持当前版本]

• 主模式插件由 .github/workflows/sync-releases.yml 检查
• 子仓库在默认分支推送时派发 plugin-update 事件
• 市场每周进行备用同步

资料来源：README.md:24-33

输出格式

大多数工具支持多种输出格式：

资料来源：plugins/langfuse/skills/langfuse/references/tool-reference.md:47-53

下一步

• 浏览 plugins/ 目录了解所有可用技能
• 查看 CONTRIBUTING.md 了解贡献指南
• 访问 Agent Skills 规范 了解技术标准

概述

Skills Marketplace 是一个插件市场仓库，用于托管和分发 Agent Skills 兼容的插件。该项目为 Claude Code 和 Codex CLI 等 Agent Skills 兼容工具提供统一的插件分发机制。

资料来源：README.md:1-10

核心架构组件

1. 仓库结构

项目采用标准化的目录结构，将插件代码与市场配置分离：

资料来源：README.md:30-40

2. 插件组织结构

每个插件在仓库中遵循统一目录结构：

plugins/
└── <plugin-name>/
    └── skills/
        └── <skill-name>/
            ├── SKILL.md           # 技能定义
            ├── references/        # 参考文档
            │   └── tool-reference.md
            └── rules/             # 规则定义
                └── status.md

资料来源：README.md:25-30

插件注册机制

registry/plugins.json 结构

注册表是插件市场的核心数据源，记录每个插件的引用信息：

资料来源：README.md:50-60

自动同步机制

工作流程架构

graph TD
    A[插件仓库推送] --> B{sync.mode 判断}
    B -->|auto| C[dispatch plugin-update 事件]
    B -->|manual| D[等待手动触发]
    C --> E[marketplace 接收事件]
    E --> F[更新 registry/plugins.json]
    F --> G[重新生成清单文件]
    G --> H[提交到 main 分支]
    
    I[每周定时同步] --> A
    J[手动运行工作流] --> A

同步模式

资料来源：README.md:42-48

技能系统架构

Agent Skills 规范

所有插件遵循 Agent Skills 规范，确保跨工具兼容性：

graph LR
    A[Claude Code] <-->|Agent Skills| B[skills-marketplace]
    A <-->|Agent Skills| C[Codex CLI]
    B --> D[插件市场分发]
    C --> D

技能组成

消息传递架构

某些插件（如 amq-cli、amq-spec）使用 AMQ 消息系统进行代理间通信。

消息格式

graph LR
    A[发送方] -->|JSON Frontmatter| B[Markdown Body]
    A --> C[消息元数据]
    C -->|schema| D[版本号]
    C -->|id| E[唯一标识]
    C -->|from/to| F[路由信息]
    C -->|thread| G[会话线程]
    C -->|kind| H[消息类型]
    C -->|labels| I[标签分类]

消息字段说明

资料来源：plugins/amq-cli/skills/amq-cli/references/message-format.md:1-30

协作工作流

Spec 工作流阶段

amq-spec 技能实现了多代理协作设计协议：

graph TD
    A[Phase 1: Research] -->|并行研究| B[交换研究成果]
    B --> C[Phase 2: Discuss]
    C -->|ping-pong 讨论| D[达成共识]
    D --> E[Phase 3: Draft]
    E -->|主代理起草| F[Phase 4: Review]
    F -->|合作伙伴审查| G[Phase 5: Present]
    G -->|用户批准| H[Phase 6: Execute]

工作流阶段表

资料来源：plugins/amq-spec/skills/amq-spec/SKILL.md:1-25

插件添加流程

添加新插件步骤

graph LR
    A[创建 plugin.json] --> B[添加 registry 入口]
    B --> C[运行生成脚本]
    C --> D[提交 PR]
    D --> E[合并到 main]
    E --> F[自动同步分发]

1. 确保仓库包含 .claude-plugin/plugin.json
2. 添加插件条目到 registry/plugins.json
3. 运行 python3 scripts/generate-manifests.py
4. 提交 PR 并等待合并

资料来源：README.md:52-58

数据模型

MCP 工具分类

以 langfuse 插件为例，工具按功能分类：

*注：标有 * 的工具在只读模式下禁用。*

资料来源：plugins/langfuse/skills/langfuse/references/tool-reference.md:1-35

技术标准

Agent Skills 兼容性要求

所有插件必须符合 Agent Skills 规范：

资料来源：README.md:60-62

许可证

本项目采用 MIT 许可证开源。

资料来源：README.md:65

概述

插件注册表是 skills-marketplace 项目的核心组件，负责管理和维护所有插件的元数据信息。该注册表以 JSON 格式存储于 registry/plugins.json 文件中，为 Claude Code 和 Codex CLI 等 Agent Skills 兼容工具提供插件目录服务。

资料来源：README.md:1-10

核心职责

资料来源：README.md:15-25

概述

插件列表（Plugin List）是 skills-marketplace 仓库的核心组件，定义了所有可用 Agent Skills 插件的元数据、版本信息和同步配置。该仓库作为一个集中化的插件市场，为 Claude Code 和 Codex CLI 提供插件分发服务。

插件市场遵循 Agent Skills 规范，确保与多种 Agent Tools 兼容。资料来源：README.md:1-5

仓库结构

skills-marketplace/
├── registry/
│   ├── plugins.json           # 插件注册表（主清单）
│   └── ...                    # 其他注册相关文件
├── plugins/                    # 本地生成的插件包（Codex 使用）
│   ├── amq-cli/               # AMQ CLI 插件
│   ├── amq-spec/              # AMQ 规范插件
│   ├── langfuse/              # Langfuse 追踪插件
│   ├── bkt/                   # Bitbucket 插件
│   ├── jk/                    # Jenkins 插件
│   └── shaon/                 # Hilan 考勤系统插件
├── scripts/
│   └── generate-manifests.py # 清单生成脚本
└── .github/workflows/         # GitHub Actions 工作流

插件注册机制

注册表文件格式

registry/plugins.json 是插件市场的主清单文件，包含所有插件的详细配置：

{
  "plugins": [
    {
      "name": "插件名称",
      "version": "版本号",
      "repo": "GitHub 仓库地址",
      "sync": {
        "mode": "auto | manual"
      }
    }
  ]
}

插件配置项

现有插件列表

当前市场中包含以下官方插件：

资料来源：README.md:8-20

插件架构

插件内部结构

每个插件遵循统一的目录结构：

plugin-name/
├── plugin.json          # Codex 插件清单
├── skills/
│   ├── skill-name/
│   │   ├── SKILL.md     # 技能主文档
│   │   ├── references/  # 参考文档
│   │   │   ├── tool-reference.md
│   │   │   └── message-format.md
│   │   └── rules/       # 规则定义
│   │       ├── status.md
│   │       └── run.md

插件类型分类

graph TD
    A[插件类型] --> B[通信类]
    A --> C[CI/CD 集成类]
    A --> D[LLM 观测类]
    A --> E[业务系统类]
    
    B --> B1[amq-cli]
    B --> B2[amq-spec]
    
    C --> C1[bkt]
    C --> C2[jk]
    
    D --> D1[langfuse]
    
    E --> E1[shaon]

AMQ 通信插件

amq-cli 插件

amq-cli 插件提供点对点（P2P）消息通信能力，支持多代理之间的任务协调和状态同步。资料来源：plugins/amq-cli/skills/amq-cli/references/message-format.md:1-30

消息格式规范：

AMQ 消息采用 Markdown 文件格式，包含 JSON frontmatter 元数据头：

---json
{
  "schema": 1,
  "id": "<消息ID>",
  "from": "发送者",
  "to": ["接收者"],
  "thread": "线程ID",
  "kind": "消息类型",
  "labels": ["标签列表"]
}

概述

AMQ（Agent Message Queue）插件是一个基于消息队列的多智能体协作框架，用于在AI代理之间实现结构化的通信与协作。该插件是技能市场（Skills Marketplace）项目的重要组成部分，为代理提供了一套完整的通信原语，支持双人协作（Coop Mode）、群体协作（Swarm Mode）以及跨项目通信等场景。

AMQ的核心设计理念是通过标准化的消息格式和工作流规范，使多个AI代理能够高效地分工协作，同时保持通信的清晰性和可追溯性。

资料来源：plugins/amq-cli/skills/amq-cli/SKILL.md

核心通信原语

AMQ提供了三个基础命令作为通信原语，所有协作功能都建立在这三个原语之上。

命令概览

资料来源：plugins/amq-spec/skills/amq-spec/SKILL.md

amq send

发送消息是最基础的通信操作，支持丰富的元数据配置：

amq send --to <partner> --kind brainstorm \
  --labels workflow:spec,phase:research \
  --thread spec/<topic> --subject "Research: <topic>" \
  --body "<message body>"

关键参数说明：

资料来源：plugins/amq-spec/skills/amq-spec/SKILL.md

amq thread

用于查看线程中的完整消息历史：

amq thread --id spec/<topic> --include-body

amq drain 与 amq watch

队列消费命令，用于接收消息：

amq drain --include-body
amq watch --timeout 120s

消息格式规范

AMQ消息采用Markdown格式，消息头部包含JSON格式的元数据。

消息结构

---json
{
  "schema": 1,
  "id": "<msg_id>",
  "from": "claude",
  "to": ["codex"],
  "thread": "p2p/claude__codex",
  "subject": "Optional summary",
  "created": "<RFC3339 timestamp>",
  "refs": ["<related_msg_id>"],
  "priority": "normal",
  "kind": "question",
  "labels": ["bug", "parser"],
  "context": {"paths": ["internal/cli/send.go"], "focus": "error handling"},
  "reply_to": "claude@collab",
  "reply_project": "my-project",
  "from_project": "my-project"
}

概述

Langfuse插件是一个基于MCP（Model Context Protocol）的AI可观测性工具，用于调试AI代理和LLM应用程序。它通过Langfuse平台提供追踪、异常发现、会话管理、提示词版本控制等功能，帮助开发者深入分析AI应用的运行状态和性能瓶颈。

该插件是langfuse-mcp的面向代理伴侣，为Claude Code和Codex提供何时使用Langfuse、首先调用哪个MCP工具、以及如何从广泛的追踪发现到具体根因假设的完整指导。

资料来源：plugins/langfuse/skills/langfuse/SKILL.md:1-20

兼容性

资料来源：plugins/langfuse/skills/langfuse/SKILL.md:6-7

触发条件

Langfuse插件会在以下关键词或短语出现时自动激活：

资料来源：plugins/langfuse/skills/langfuse/SKILL.md:14-15

安装配置

环境变量配置

Langfuse插件通过环境变量进行配置，主要配置项如下：

资料来源：plugins/langfuse/skills/langfuse/references/setup.md:1-12

安装范围

全局安装命令：

cp -r skills/langfuse ~/.claude/skills/   # Claude Code
cp -r skills/langfuse ~/.codex/skills/    # Codex CLI

资料来源：plugins/langfuse/skills/langfuse/references/setup.md:14-23

MCP工具分类

Langfuse MCP提供了丰富的工具集，按功能分为以下类别：

资料来源：plugins/langfuse/skills/langfuse/references/tool-reference.md:6-25

只读模式

部分工具在只读模式下会被禁用（当设置--read-only或LANGFUSE_MCP_READ_ONLY=true时）：

资料来源：plugins/langfuse/skills/langfuse/references/tool-reference.md:24-25

输出模式

部分工具支持通过output_mode参数控制输出格式：

资料来源：plugins/langfuse/skills/langfuse/references/tool-reference.md:27-36

提示词管理

创建文本提示

{
  "name": "prompt_name",
  "prompt": "Hello {{name}}, welcome to {{app}}!",
  "labels": ["staging"],
  "config": {
    "model": "gpt-4",
    "temperature": 0.7,
    "max_tokens": 1000,
    "top_p": 1.0
  },
  "tags": ["production"],
  "commit_message": "feat: add personalized greeting"
}

资料来源：plugins/langfuse/skills/langfuse/references/tool-reference.md:38-72

重要特性

提示词不可变性：提示词一旦创建不可修改，创建新版本是更新内容的唯一方式。

标签唯一性：标签在整个版本中是唯一的，在此分配标签会从其他版本移除。

资料来源：plugins/langfuse/skills/langfuse/references/tool-reference.md:67-70

调试工作流

异常排查流程

graph TD
    A[发现异常报告] --> B[find_exceptions查找异常]
    B --> C[get_exception_details获取详情]
    C --> D[分析根因]
    D --> E[定位问题代码]
    
    F[文件级异常] --> G[find_exceptions_in_file]
    G --> C

追踪分析流程

graph TD
    A[开始调试] --> B[fetch_traces获取追踪列表]
    B --> C[筛选相关追踪]
    C --> D[fetch_trace获取详细信息]
    D --> E[fetch_observations获取观测点]
    E --> F[定位性能瓶颈或错误]

数据集管理流程

graph LR
    A[list_datasets] --> B[get_dataset]
    B --> C[list_dataset_items]
    C --> D[get_dataset_item]
    D --> E[分析数据集项]

安全注意事项

资料来源：plugins/langfuse/skills/langfuse/references/setup.md:25-30

版本信息

资料来源：plugins/langfuse/skills/langfuse/SKILL.md:1-7

插件架构概述

skills-marketplace 采用插件化架构，每个插件包含独立的 SKILL.md 定义文件和规则集。插件通过统一的命令行工具前缀（bkt、jk、yoetz 等）暴露功能，遵循 Agent Skills 规范，确保与 Claude Code、Codex CLI 等工具的兼容性。

graph TB
    subgraph "skills-marketplace 插件生态"
        subgraph "Bitbucket 插件"
            BKT["bkt 插件"]
            BKT_STATUS["bkt status"]
            BKT_WEBHOOK["bkt webhook"]
            BKT_ISSUE["bkt issue"]
        end
        
        subgraph "Jenkins 插件"
            JK["jk 插件"]
            JK_QUEUE["jk queue"]
            JK_RUN["jk run"]
            JK_TEST["jk test"]
        end
        
        subgraph "AI 辅助插件"
            YOETZ["yoetz 插件"]
        end
    end
    
    BKT --> BKT_STATUS
    BKT --> BKT_WEBHOOK
    BKT --> BKT_ISSUE
    JK --> JK_QUEUE
    JK --> JK_RUN
    JK --> JK_TEST

Bitbucket 工具插件（bkt）

bkt 插件提供与 Bitbucket Cloud 和 Data Center 的交互能力，支持查看构建状态、管理 Webhook、查看问题等操作。该插件针对不同 Bitbucket 部署类型（Cloud 和 Data Center）提供差异化的功能支持。

功能模块

bkt status 子命令

bkt status 命令用于检查与提交和拉取请求关联的构建和 CI 状态，支持 Data Center 提交状态、PR head-commit 状态以及 Cloud pipeline 运行状态查询。

主要子命令：

Usage 示例：

# 查看提交的构建状态（Data Center）
bkt status commit abc1234

# 查看特定 SHA 的完整构建状态
bkt status commit 6f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a

# 查看 Cloud pipeline 运行
bkt status pipeline {pipeline-uuid}

# 检查 API 速率限制
bkt status rate-limit

通用参数：

资料来源：plugins/bkt/skills/bkt/rules/status.md:1-50

bkt webhook 子命令

bkt webhook 命令用于测试 Webhook 功能，支持指定项目或仓库进行测试。

Usage 示例：

# 通过 ID 测试 Webhook
bkt webhook test 42

# 在特定仓库中测试 Webhook
bkt webhook test 7 --project MYPROJ --repo my-repo

参数说明：

资料来源：plugins/bkt/skills/bkt/rules/webhook.md:1-30

bkt issue 子命令

bkt issue 命令用于管理 Bitbucket Cloud 问题，支持查看问题状态和详细信息。

主要子命令：

bkt issue view 参数：

Usage 示例：

# 显示当前用户的问题
bkt issue status

# 显示问题详情（包含评论）
bkt issue view 123 --comments

# 在浏览器中打开问题
bkt issue view 123 --web

资料来源：plugins/bkt/skills/bkt/rules/issue.md:1-40

Jenkins 工具插件（jk）

jk 插件提供与 Jenkins CI/CD 系统的交互能力，支持构建队列管理、运行控制、测试结果检查等功能。该插件支持通过上下文配置连接不同的 Jenkins 实例。

功能模块

jk queue 子命令

jk queue 命令用于检查和管理 Jenkins 构建队列。

Usage 示例：

# 列出排队的项目
jk queue ls

# 取消特定队列项
jk queue cancel <id>

通用参数：

资料来源：plugins/jk/skills/jk/rules/queue.md:1-45

jk run 子命令

jk run 命令用于与任务运行进行交互，是 Jenkins 插件中最核心的功能模块。

Usage 示例：

# 取消正在运行的作业
jk run cancel <jobPath> <buildNumber> --mode kill

# 列出最近的运行
jk run ls --filter "branch=main"

# 搜索作业
jk run search --job-glob "*/deploy-*"

# 触发新运行并跟踪
jk run start my-job --follow

# 查看运行详情
jk run view <jobPath> <buildNumber> --summary

资料来源：plugins/jk/skills/jk/rules/run.md:1-50

jk test 子命令

jk test 命令用于检查聚合测试结果。

Usage 示例：

# 显示聚合测试报告
jk test report <jobPath> <buildNumber>

资料来源：plugins/jk/skills/jk/rules/test.md:1-30

AI 辅助工具插件（yoetz）

yoetz 插件提供 AI 辅助开发功能，包括代码审查、差异对比、文件打包、图像生成、定价估算和浏览器操作等能力。该插件支持多模型协作（Council）功能，可以并行获取多个 LLM 的意见。

核心功能

多模型协作（Council）

yoetz 支持通过 --models 参数并行调用多个 LLM 提供者，获取不同模型的共识意见。

yoetz council \
  -p "Should we use async traits or callbacks for this API?" \
  -f src/lib.rs -f src/api/*.rs \
  --models openai/gpt-5.4,gemini/gemini-3.1-pro-preview,openrouter/xai/grok-4.20-multi-agent-beta \
  --format json

模型指定说明：

• 模型 ID 通过 yoetz models frontier 或 yoetz models resolve 命令获取
• 支持跨提供者组合：openai/<FRONTIER>,gemini/<FRONTIER>

输出格式

yoetz 支持多种输出格式，通过 --format 参数指定：

资料来源：plugins/yoetz/skills/yoetz/SKILL.md:1-50

通用参数体系

所有开发工具插件遵循统一的参数规范，确保跨插件使用体验的一致性。

输出格式参数

上下文管理

graph LR
    A[用户命令] --> B{--context 参数}
    B -->|指定上下文| C[使用指定上下文]
    B -->|未指定| D{环境变量}
    D -->|存在| E[使用环境变量上下文]
    D -->|不存在| F[使用默认上下文]
    
    C --> G[连接到对应服务实例]
    E --> G
    F --> G

插件配置与管理

上下文配置

开发工具插件通过上下文配置连接不同的服务实例。例如，Jenkins 插件可以通过以下方式配置多个 Jenkins 实例：

# 设置 Jenkins 上下文
export JK_CONTEXT=production

# 或者通过命令行覆盖
jk run start my-job --context staging

插件清单结构

每个插件在仓库中遵循统一的目录结构：

plugins/<plugin-name>/
├── plugin.json          # Codex 插件清单
└── skills/
    └── <plugin-name>/
        ├── SKILL.md     # 主技能定义
        └── rules/       # 子命令规则文档
            ├── <command1>.md
            └── <command2>.md

资料来源：README.md:1-60

工作流集成示例

CI/CD 状态检查工作流

graph TD
    A[代码提交触发 CI] --> B[CI 系统更新 Bitbucket 状态]
    B --> C{bkt status commit}
    C -->|查看状态| D[SUCCESS/FAILED/INPROGRESS]
    D --> E{状态检查结果}
    E -->|失败| F[触发告警]
    E -->|成功| G[继续部署流程]

Jenkins 构建管理流程

graph LR
    A[jk queue ls] --> B{队列中有任务?}
    B -->|是| C[查看队列详情]
    B -->|否| D[等待]
    C --> E{需要取消?}
    E -->|是| F[jk queue cancel]
    E -->|否| G[jk run view]
    G --> H{需要重跑?}
    H -->|是| I[jk run rerun --follow]
    H -->|否| J[查看构建日志]

技术规范与标准

所有开发工具插件遵循 Agent Skills 规范，确保跨平台兼容性：

• Claude Code 兼容：通过 marketplace 目录直接指向固定的 GitHub refs
• Codex CLI 兼容：通过 plugins/ 目录下的本地 bundle 支持
• 自动同步：主模式插件通过 .github/workflows/sync-releases.yml 自动检查更新
• 手动模式：可通过 sync.mode: "manual" 设置保持固定版本

资料来源：README.md:1-60

总结

开发工具插件为 AI 代理提供了与外部开发系统集成的标准化能力。通过 bkt 插件连接 Bitbucket 平台实现代码状态和问题的管理，通过 jk 插件连接 Jenkins 实现 CI/CD 流程的控制，通过 yoetz 插件提供 AI 辅助开发功能。这些插件共同构成了一个完整的开发辅助工具链，支持从代码提交到部署的完整流程自动化。

概述

skills-marketplace 是一个 Agent Skills 插件市场，用于托管和分发兼容的插件。该项目支持两种目标平台：

所有插件遵循 Agent Skills 规范，确保跨平台兼容性。

目录结构

skills-marketplace/
├── registry/
│   └── plugins.json            # 插件注册表
├── plugins/                     # Codex 本地插件包
│   ├── <plugin-name>/
│   │   ├── plugin.json          # Codex 插件清单
│   │   └── skills/              # 共享技能负载
│   └── ...
└── scripts/
    └── generate-manifests.py    # 清单生成脚本

添加新插件

前置条件

在提交插件之前，请确保满足以下要求：

1. 仓库必须包含 .claude-plugin/plugin.json 文件
2. 如需 Codex 支持，还需包含 .codex-plugin/plugin.json 文件
3. 插件必须遵循 Agent Skills 规范

操作流程

将插件添加到 marketplace 需要以下步骤：

graph TD
    A[准备插件仓库] --> B[创建 plugin.json 清单]
    C[添加插件条目到 registry/plugins.json] --> D[生成清单和产物]
    B --> C
    D --> E[提交 PR]
    E --> F[等待审核合并]

#### 详细步骤

资料来源：README.md:1-20

plugin.json 清单格式

插件清单是插件的核心描述文件，包含以下关键字段：

自动同步机制

同步模式

marketplace 支持两种同步模式：

资料来源：README.md:22-30

同步触发条件

自动同步在以下情况下触发：

graph LR
    A[子仓库推送] -->|dispatch plugin-update| B[Marketplace 接收事件]
    C[每周定时任务] --> B
    D[手动触发] --> B
    B --> E[更新 registry/plugins.json]
    E --> F[重新生成清单]
    F --> G[提交到 main 分支]

1. 事件驱动：子仓库推送时触发 plugin-update 事件
2. 定时同步：每周执行一次备用同步
3. 手动执行：支持按需手动触发

同步流程

当仓库 HEAD 发生变更时，同步流程执行以下操作：

1. 更新 registry/plugins.json 中的插件引用
2. 重新生成插件清单和产物
3. 直接提交到 main 分支

插件标准

所有提交到 marketplace 的插件必须符合以下标准：

常见问题

如何手动更新固定版本插件？

对于 sync.mode: "manual" 的插件，需要手动更新注册表：

1. 编辑 registry/plugins.json 中的版本引用
2. 运行 python3 scripts/generate-manifests.py
3. 提交更改到仓库

生成的产物包含哪些内容？

运行清单生成脚本后会创建：

• Codex 插件本地包（位于 plugins/）
• 更新的注册表条目
• 元数据缓存文件

同步失败怎么办？

检查以下事项：

1. 触发仓库是否有推送事件
2. 工作流权限是否足够
3. registry/plugins.json 格式是否正确

相关资源

• Agent Skills 规范
• CONTRIBUTING.md
• 同步工作流源码

插件开发规范

本文档定义了 skills-marketplace 仓库中插件（Plugin）的开发标准与提交流程。所有插件遵循 Agent Skills 规范，确保与 Claude Code、Codex CLI 及其他 Agent Skills 兼容工具的互操作性。

Pitfall Log / 踩坑日志

项目：avivsinai/skills-marketplace

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

1. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 skills-marketplace 与安装入口 skills 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
• 复现命令：npx skills
• 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
• 证据：identity.distribution | github_repo:1122660400 | https://github.com/avivsinai/skills-marketplace | repo=skills-marketplace; install=skills

2. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
• 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
• 证据：capability.host_targets | github_repo:1122660400 | https://github.com/avivsinai/skills-marketplace | host_targets=mcp_host, claude, claude_code

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:1122660400 | https://github.com/avivsinai/skills-marketplace | README/documentation is current enough for a first validation pass.

4. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:1122660400 | https://github.com/avivsinai/skills-marketplace | last_activity_observed missing

5. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:1122660400 | https://github.com/avivsinai/skills-marketplace | no_demo; severity=medium

6. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:1122660400 | https://github.com/avivsinai/skills-marketplace | no_demo; severity=medium

7. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:1122660400 | https://github.com/avivsinai/skills-marketplace | issue_or_pr_quality=unknown

8. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:1122660400 | https://github.com/avivsinai/skills-marketplace | release_recency=unknown