plugin-creator
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChinesePlugin Creator
插件创建工具
This skill provides guidance for creating plugins that extend Claude's capabilities. Supports two plugin types:
- Skills: SKILL.md-based plugins with bundled scripts, references, and assets
- MCPs: Server-based plugins that provide tools via the Model Context Protocol
本Skill为创建扩展Claude能力的插件提供指导。支持两种插件类型:
- Skills:基于SKILL.md的插件,包含捆绑脚本、参考资料和资源文件
- MCPs:通过Model Context Protocol提供工具的基于服务器的插件
About Skills
关于Skills
Skills are modular, self-contained packages that extend Claude's capabilities by providing
specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific
domains or tasks—they transform Claude from a general-purpose agent into a specialized agent
equipped with procedural knowledge that no model can fully possess.
Skills是模块化、独立的包,通过提供专业知识、工作流和工具来扩展Claude的能力。可以将它们视为特定领域或任务的“入门指南”——它们将Claude从通用Agent转变为具备程序知识的专业Agent,而这些知识是任何模型都无法完全拥有的。
What Skills Provide
Skills能提供什么
- Specialized workflows - Multi-step procedures for specific domains
- Tool integrations - Instructions for working with specific file formats or APIs
- Domain expertise - Company-specific knowledge, schemas, business logic
- Bundled resources - Scripts, references, and assets for complex and repetitive tasks
- 专业工作流 - 特定领域的多步骤流程
- 工具集成 - 处理特定文件格式或API的操作指南
- 领域专业知识 - 公司专属知识、架构、业务逻辑
- 捆绑资源 - 用于复杂和重复任务的脚本、参考资料和资源文件
Core Principles
核心原则
Concise is Key
简洁至上
The context window is a public good. Skills share the context window with everything else Claude needs: system prompt, conversation history, other Skills' metadata, and the actual user request.
Default assumption: Claude is already very smart. Only add context Claude doesn't already have. Challenge each piece of information: "Does Claude really need this explanation?" and "Does this paragraph justify its token cost?"
Prefer concise examples over verbose explanations.
上下文窗口是公共资源。Skills需要与Claude所需的其他所有内容共享上下文窗口:系统提示词、对话历史、其他Skills的元数据以及实际的用户请求。
默认假设:Claude已经非常智能。 只添加Claude尚不具备的上下文信息。对每一条信息都要提出质疑:“Claude真的需要这个解释吗?”以及“这段内容的令牌成本是否值得?”
优先使用简洁的示例而非冗长的解释。
Set Appropriate Degrees of Freedom
设置合适的自由度
Match the level of specificity to the task's fragility and variability:
High freedom (text-based instructions): Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.
Medium freedom (pseudocode or scripts with parameters): Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.
Low freedom (specific scripts, few parameters): Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.
Think of Claude as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).
根据任务的脆弱性和可变性匹配具体程度:
高自由度(基于文本的指令):当存在多种有效方法、决策依赖于上下文或需要启发式方法指导时使用。
中等自由度(带参数的伪代码或脚本):当存在首选模式、允许一定变化或配置会影响行为时使用。
低自由度(特定脚本,参数极少):当操作脆弱且容易出错、一致性至关重要或必须遵循特定序列时使用。
可以把Claude想象成在探索路径:两侧是悬崖的狭窄桥梁需要特定的护栏(低自由度),而开阔的田野则允许多种路线(高自由度)。
Anatomy of a Skill
Skill的结构
Every skill consists of a required SKILL.md file and optional bundled resources:
skill-name/
├── SKILL.md (required)
│ ├── YAML frontmatter metadata (required)
│ │ ├── name: (required)
│ │ └── description: (required)
│ └── Markdown instructions (required)
└── Bundled Resources (optional)
├── scripts/ - Executable code (Python/Bash/etc.)
├── references/ - Documentation intended to be loaded into context as needed
└── assets/ - Files used in output (templates, icons, fonts, etc.)每个Skill都包含一个必填的SKILL.md文件和可选的捆绑资源:
skill-name/
├── SKILL.md (必填)
│ ├── YAML前置元数据 (必填)
│ │ ├── name: (必填)
│ │ └── description: (必填)
│ └── Markdown指令 (必填)
└── 捆绑资源 (可选)
├── scripts/ - 可执行代码(Python/Bash等)
├── references/ - 可按需加载到上下文中的文档
└── assets/ - 输出中使用的文件(模板、图标、字体等)SKILL.md (required)
SKILL.md(必填)
Every SKILL.md consists of:
- Frontmatter (YAML): Contains and
namefields. These are the only fields that Claude reads to determine when the skill gets used, thus it is very important to be clear and comprehensive in describing what the skill is, and when it should be used.description - Body (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all).
每个SKILL.md都包含:
- 前置元数据(YAML):包含和
name字段。Claude仅通过这些字段来决定何时使用该Skill,因此清晰、全面地描述Skill的功能和适用场景至关重要。description - 主体内容(Markdown):使用Skill的指令和指南。仅在Skill被触发后才会加载(如果需要的话)。
Bundled Resources (optional)
捆绑资源(可选)
Scripts (scripts/
)
scripts/脚本(scripts/
)
scripts/Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.
- When to include: When the same code is being rewritten repeatedly or deterministic reliability is needed
- Example: for PDF rotation tasks
scripts/rotate_pdf.py - Benefits: Token efficient, deterministic, may be executed without loading into context
- Note: Scripts may still need to be read by Claude for patching or environment-specific adjustments
用于需要确定性可靠性或重复编写的任务的可执行代码(Python/Bash等)。
- 何时包含:当相同代码被重复编写或需要确定性可靠性时
- 示例:用于PDF旋转任务的
scripts/rotate_pdf.py - 优势:令牌效率高、确定性强,无需加载到上下文即可执行
- 注意:Claude可能仍需要读取脚本以进行补丁或特定环境的调整
References (references/
)
references/参考资料(references/
)
references/Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.
- When to include: For documentation that Claude should reference while working
- Examples: for financial schemas,
references/finance.mdfor company NDA template,references/mnda.mdfor company policies,references/policies.mdfor API specificationsreferences/api_docs.md - Use cases: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
- Benefits: Keeps SKILL.md lean, loaded only when Claude determines it's needed
- Best practice: If files are large (>100 lines), include a table of contents at the top and grep search patterns in SKILL.md
- Avoid duplication: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.
旨在按需加载到上下文中,为Claude的处理和思考提供信息的文档和参考资料。
- 何时包含:用于Claude在工作时需要参考的文档
- 示例:用于财务架构的、用于公司NDA模板的
references/finance.md、用于公司政策的references/mnda.md、用于API规范的references/policies.mdreferences/api_docs.md - 使用场景:数据库架构、API文档、领域知识、公司政策、详细工作流指南
- 优势:保持SKILL.md简洁,仅在Claude需要时加载
- 最佳实践:如果文件较大(>100行),在顶部添加目录,并在SKILL.md中包含grep搜索模式
- 避免重复:信息应仅存在于SKILL.md或参考文件中,不要重复。除非是Skill的核心内容,否则优先将详细信息放在参考文件中——这样可以保持SKILL.md简洁,同时确保信息可被发现而不会占用上下文窗口。仅在SKILL.md中保留必要的流程指令和工作流指南;将详细的参考资料、架构和示例移至参考文件。
Assets (assets/
)
assets/资源文件(assets/
)
assets/Files not intended to be loaded into context, but rather used within the output Claude produces.
- When to include: When the skill needs files that will be used in the final output
- Examples: for brand assets,
assets/logo.pngfor PowerPoint templates,assets/slides.pptxfor HTML/React boilerplate,assets/frontend-template/for typographyassets/font.ttf - Use cases: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
- Benefits: Separates output resources from documentation, enables Claude to use files without loading them into context
不需要加载到上下文中,而是用于Claude生成的输出中的文件。
- 何时包含:当Skill需要在最终输出中使用文件时
- 示例:用于品牌资产的、用于PowerPoint模板的
assets/logo.png、用于HTML/React模板的assets/slides.pptx、用于排版的assets/frontend-template/assets/font.ttf - 使用场景:模板、图片、图标、样板代码、字体、可复制或修改的示例文档
- 优势:将输出资源与文档分离,使Claude无需加载到上下文即可使用文件
What to Not Include in a Skill
Skill中不应包含的内容
A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files, including:
- README.md
- INSTALLATION_GUIDE.md
- QUICK_REFERENCE.md
- CHANGELOG.md
- etc.
The skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxilary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.
Skill应仅包含直接支持其功能的必要文件。请勿创建无关的文档或辅助文件,包括:
- README.md
- INSTALLATION_GUIDE.md
- QUICK_REFERENCE.md
- CHANGELOG.md
- 等等
Skill应仅包含AI Agent完成当前工作所需的信息。不应包含关于创建过程、设置和测试流程、面向用户的文档等辅助内容。创建额外的文档文件只会增加混乱和困惑。
Progressive Disclosure Design Principle
渐进式披露设计原则
Skills use a three-level loading system to manage context efficiently:
- Metadata (name + description) - Always in context (~100 words)
- SKILL.md body - When skill triggers (<5k words)
- Bundled resources - As needed by Claude (Unlimited because scripts can be executed without reading into context window)
Skills使用三级加载系统来高效管理上下文:
- 元数据(名称+描述) - 始终在上下文中(约100词)
- SKILL.md主体 - 当Skill被触发时(<5000词)
- 捆绑资源 - 由Claude按需加载(无限制,因为脚本可以在不读取到上下文窗口的情况下执行)
Progressive Disclosure Patterns
渐进式披露模式
Keep SKILL.md body to the essentials and under 500 lines to minimize context bloat. Split content into separate files when approaching this limit. When splitting out content into other files, it is very important to reference them from SKILL.md and describe clearly when to read them, to ensure the reader of the skill knows they exist and when to use them.
Key principle: When a skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details (patterns, examples, configuration) into separate reference files.
Pattern 1: High-level guide with references
markdown
undefined将SKILL.md主体保持在必要内容范围内,且不超过500行,以尽量减少上下文膨胀。当接近此限制时,将内容拆分为单独的文件。将内容拆分为其他文件时,非常重要的是从SKILL.md中引用它们,并清晰描述何时读取它们,以确保Skill的使用者知道它们的存在和使用时机。
核心原则:当Skill支持多种变体、框架或选项时,仅在SKILL.md中保留核心工作流和选择指南。将变体特定的详细信息(模式、示例、配置)移至单独的参考文件中。
模式1:带参考资料的高级指南
markdown
undefinedPDF Processing
PDF处理
Quick start
快速入门
Extract text with pdfplumber:
[code example]
使用pdfplumber提取文本:
[代码示例]
Advanced features
高级功能
- Form filling: See FORMS.md for complete guide
- API reference: See REFERENCE.md for all methods
- Examples: See EXAMPLES.md for common patterns
Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
**Pattern 2: Domain-specific organization**
For Skills with multiple domains, organize content by domain to avoid loading irrelevant context:
bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
├── finance.md (revenue, billing metrics)
├── sales.md (opportunities, pipeline)
├── product.md (API usage, features)
└── marketing.md (campaigns, attribution)
When a user asks about sales metrics, Claude only reads sales.md.
Similarly, for skills supporting multiple frameworks or variants, organize by variant:
cloud-deploy/
├── SKILL.md (workflow + provider selection)
└── references/
├── aws.md (AWS deployment patterns)
├── gcp.md (GCP deployment patterns)
└── azure.md (Azure deployment patterns)
When the user chooses AWS, Claude only reads aws.md.
**Pattern 3: Conditional details**
Show basic content, link to advanced content:
```markdown- 表单填充:完整指南请参见FORMS.md
- API参考:所有方法请参见REFERENCE.md
- 示例:常见模式请参见EXAMPLES.md
Claude仅在需要时加载FORMS.md、REFERENCE.md或EXAMPLES.md。
**模式2:按领域组织**
对于包含多个领域的Skills,按领域组织内容以避免加载无关上下文:
bigquery-skill/
├── SKILL.md(概述和导航)
└── reference/
├── finance.md(收入、计费指标)
├── sales.md(商机、销售管道)
├── product.md(API使用、功能)
└── marketing.md(营销活动、归因)
当用户询问销售指标时,Claude仅读取sales.md。
类似地,对于支持多个框架或变体的Skills,按变体组织:
cloud-deploy/
├── SKILL.md(工作流+提供商选择)
└── references/
├── aws.md(AWS部署模式)
├── gcp.md(GCP部署模式)
└── azure.md(Azure部署模式)
当用户选择AWS时,Claude仅读取aws.md。
**模式3:条件式详细内容**
显示基本内容,链接到高级内容:
```markdownDOCX Processing
DOCX处理
Creating documents
创建文档
Use docx-js for new documents. See DOCX-JS.md.
使用docx-js创建新文档。请参见DOCX-JS.md。
Editing documents
编辑文档
For simple edits, modify the XML directly.
For tracked changes: See REDLINING.md
For OOXML details: See OOXML.md
Claude reads REDLINING.md or OOXML.md only when the user needs those features.
**Important guidelines:**
- **Avoid deeply nested references** - Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md.
- **Structure longer reference files** - For files longer than 100 lines, include a table of contents at the top so Claude can see the full scope when previewing.对于简单编辑,直接修改XML。
对于跟踪更改:请参见REDLINING.md
对于OOXML详细信息:请参见OOXML.md
Claude仅在用户需要这些功能时才读取REDLINING.md或OOXML.md。
**重要指南**:
- **避免深层嵌套参考** - 参考资料应仅从SKILL.md一级链接。所有参考文件应直接从SKILL.md链接。
- **结构化较长的参考文件** - 对于超过100行的文件,在顶部添加目录,以便Claude在预览时可以看到完整范围。Plugin Creation Process
插件创建流程
Plugin creation involves these steps:
- Determine plugin type (skill vs MCP)
- Understand the plugin with concrete examples
- Plan reusable contents
- Initialize the plugin (run )
tools/init_plugin.py - Edit the plugin (implement resources and write manifest)
- Package the plugin (run )
tools/package_plugin.py - Iterate based on real usage
Follow these steps in order, skipping only if there is a clear reason why they are not applicable.
插件创建包含以下步骤:
- 确定插件类型(Skill vs MCP)
- 通过具体示例理解插件用途
- 规划可重用内容
- 初始化插件(运行)
tools/init_plugin.py - 编辑插件(实现资源并编写清单)
- 打包插件(运行)
tools/package_plugin.py - 根据实际使用情况迭代优化
按顺序执行这些步骤,仅在有明确理由不适用时才跳过。
Determining Plugin Type
确定插件类型
Choose based on how the plugin will be used:
| Aspect | Skill | MCP |
|---|---|---|
| Format | SKILL.md + optional resources | MCP.md + server.py |
| Invocation | Claude selects based on description | Tools always available |
| Use case | Workflows, procedures, domain knowledge | Persistent tools, external APIs |
| Examples | Document processing, code review | Session memory, database queries |
Choose Skill when: The plugin provides workflows, domain knowledge, or procedures that Claude should follow for specific tasks.
Choose MCP when: The plugin needs to provide tools that are always available, interact with external systems, or maintain persistent state.
根据插件的使用方式选择:
| 方面 | Skill | MCP |
|---|---|---|
| 格式 | SKILL.md + 可选资源 | MCP.md + server.py |
| 调用方式 | Claude根据描述选择 | 工具始终可用 |
| 使用场景 | 工作流、流程、领域知识 | 持久工具、外部API |
| 示例 | 文档处理、代码审查 | 会话记忆、数据库查询 |
选择Skill的场景:插件为特定任务提供Claude应遵循的工作流、领域知识或流程。
选择MCP的场景:插件需要提供始终可用的工具、与外部系统交互或维护持久状态。
Step 2: Understanding the Plugin with Concrete Examples
步骤2:通过具体示例理解插件用途
Skip this step only when the plugin's usage patterns are already clearly understood.
Clearly understand concrete examples of how the plugin will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
Example questions:
- "What functionality should this plugin support?"
- "Can you give examples of how this would be used?"
- "What would a user say that should trigger this?"
Conclude this step when there is a clear sense of the functionality the plugin should support.
仅当插件的使用模式已明确理解时才跳过此步骤。
清晰理解插件的具体使用示例。这种理解可以来自直接的用户示例,也可以来自经用户反馈验证的生成示例。
示例问题:
- “此插件应支持哪些功能?”
- “你能举例说明如何使用它吗?”
- “用户说什么应该触发这个插件?”
当明确了解插件应支持的功能时,结束此步骤。
Step 3: Planning the Reusable Contents
步骤3:规划可重用内容
For skills, identify what scripts, references, and assets would be helpful. For MCPs, identify what tools the server should provide.
Skill examples:
- - deterministic code for PDF rotation
scripts/rotate_pdf.py - - boilerplate template files
assets/hello-world/ - - domain documentation
references/schema.md
MCP examples:
- Tools for session persistence (save/load state)
- Tools for external API integration
- Tools for database queries
对于Skills,确定哪些脚本、参考资料和资源文件会有帮助。对于MCPs,确定服务器应提供哪些工具。
Skill示例:
- - 用于PDF旋转的确定性代码
scripts/rotate_pdf.py - - 样板模板文件
assets/hello-world/ - - 领域文档
references/schema.md
MCP示例:
- 用于会话持久化的工具(保存/加载状态)
- 用于外部API集成的工具
- 用于数据库查询的工具
Step 4: Initializing the Plugin
步骤4:初始化插件
Skip this step if the plugin already exists and only needs iteration or packaging.
Use to create a new plugin:
tools/init_plugin.pybash
undefined仅当插件已存在且只需迭代或打包时才跳过此步骤。
使用创建新插件:
tools/init_plugin.pybash
undefinedCreate a skill
创建Skill
tools/init_plugin.py skill <plugin-name> --path skills/
tools/init_plugin.py skill <plugin-name> --path skills/
Create an MCP
创建MCP
tools/init_plugin.py mcp <plugin-name> --path mcps/
**For skills**, the script creates:
- SKILL.md template with frontmatter
- Example `scripts/`, `references/`, and `assets/` directories
**For MCPs**, the script creates:
- MCP.md manifest with frontmatter
- server.py boilerplate with MCP SDK integration
- config.json for configuration
After initialization, customize or remove the generated files as needed.tools/init_plugin.py mcp <plugin-name> --path mcps/
**对于Skills**,脚本会创建:
- 带前置元数据的SKILL.md模板
- 示例`scripts/`、`references/`和`assets/`目录
**对于MCPs**,脚本会创建:
- 带前置元数据的MCP.md清单
- 集成MCP SDK的server.py样板文件
- 用于配置的config.json
初始化后,根据需要自定义或删除生成的文件。Step 5: Edit the Plugin
步骤5:编辑插件
Remember that plugins are created for another Claude instance to use. Include information that would be beneficial and non-obvious.
请记住,插件是为另一个Claude实例创建的。包含有益且非显而易见的信息。
For Skills
对于Skills
Frontmatter (SKILL.md):
- : hyphen-case, max 64 chars, must match directory name
name - : max 1024 chars, include what it does AND when to use it
description
Body: Instructions for using the skill and bundled resources.
See references/workflows.md for design patterns and references/validation-checklist.md before packaging.
前置元数据(SKILL.md):
- :连字符格式,最多64个字符,必须与目录名称匹配
name - :最多1024个字符,包含功能和适用场景
description
主体:使用Skill和捆绑资源的指令。
打包前,请参阅references/workflows.md了解设计模式,参阅references/validation-checklist.md进行验证。
For MCPs
对于MCPs
Frontmatter (MCP.md):
- : hyphen-case, max 64 chars, must match directory name
name - : max 1024 chars
description - : must be "mcp"
type - : main Python file (e.g., "server.py")
entry_point - : optional list of pip packages
dependencies - : optional config file path
config_file
Implementation:
- Define tools in server.py using MCP SDK
- Implement tool handlers
- Test locally before packaging
前置元数据(MCP.md):
- :连字符格式,最多64个字符,必须与目录名称匹配
name - :最多1024个字符
description - :必须为"mcp"
type - :主Python文件(例如"server.py")
entry_point - :可选的pip包列表
dependencies - :可选的配置文件路径
config_file
实现:
- 使用MCP SDK在server.py中定义工具
- 实现工具处理程序
- 打包前在本地测试
Step 6: Packaging the Plugin
步骤6:打包插件
Use to create a distributable file:
tools/package_plugin.py.pluginbash
tools/package_plugin.py <path/to/plugin-folder> [output-directory]使用创建可分发的文件:
tools/package_plugin.py.pluginbash
tools/package_plugin.py <path/to/plugin-folder> [output-directory]Examples
示例
tools/package_plugin.py skills/my-skill
tools/package_plugin.py mcps/my-mcp ./dist
**Dependency**: Requires PyYAML (`pip install pyyaml`).
The script:
1. **Validates** the plugin (frontmatter, naming, structure)
2. **Packages** into a `.plugin` file (ZIP format with MANIFEST.json)
For MCPs, after packaging use `tools/install_mcp.py` to install:
```bash
tools/install_mcp.py dist/my-mcp.plugintools/package_plugin.py skills/my-skill
tools/package_plugin.py mcps/my-mcp ./dist
**依赖**:需要PyYAML(`pip install pyyaml`)。
脚本会:
1. **验证**插件(前置元数据、命名、结构)
2. **打包**成`.plugin`文件(带MANIFEST.json的ZIP格式)
对于MCPs,打包后使用`tools/install_mcp.py`安装:
```bash
tools/install_mcp.py dist/my-mcp.pluginOr for development (symlink):
或开发模式(符号链接):
tools/install_mcp.py mcps/my-mcp --symlink
undefinedtools/install_mcp.py mcps/my-mcp --symlink
undefinedStep 7: Test and Iterate
步骤7:测试和迭代
Testing approach:
- Define 3+ realistic test scenarios
- Test with multiple models (Haiku, Sonnet, Opus)
- Check edge cases and boundary conditions
For MCPs specifically:
- Test tools individually before integration
- Verify error handling
- Test with Claude Desktop
Iteration workflow:
- Use on real tasks
- Notice struggles or inefficiencies
- Update plugin and test again
测试方法:
- 定义3个以上真实测试场景
- 使用多个模型测试(Haiku、Sonnet、Opus)
- 检查边缘情况和边界条件
针对MCPs的特殊测试:
- 集成前单独测试每个工具
- 验证错误处理
- 使用Claude Desktop测试
迭代工作流:
- 在实际任务中使用
- 注意遇到的困难或低效之处
- 更新插件并再次测试