Back to Details

skill-publish

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill Publish

技能发布

Publish Claude Code plugins and standalone Agent Skills with proper versioning, changelog management, and git workflow.
通过规范的版本控制、变更日志管理和Git工作流，发布Claude Code插件和独立Agent Skills。

Determine Publish Type

确定发布类型

Before starting, identify the publish type based on project structure:
IndicatorType
.claude-plugin/plugin.json
exists		Claude Code Plugin
Standalone 
SKILL.md
with no plugin manifest		Standalone Agent Skill
Claude Code plugins publish by pushing to GitHub — the marketplace picks up the latest commit on the default branch automatically. No registry upload or OTP is needed.
Standalone Agent Skills follow the agentskills.io specification and distribute as directories containing 
SKILL.md
.
开始前，请根据项目结构确定发布类型：
判定指标类型
存在 
.claude-plugin/plugin.json
Claude Code 插件
独立的 
SKILL.md
文件且无插件清单		独立Agent Skill
Claude Code插件通过推送到GitHub发布——市场会自动获取默认分支的最新提交。无需注册上传或一次性密码（OTP）。
独立Agent Skills遵循agentskills.io规范，以包含
SKILL.md
的目录形式分发。

Claude Code Plugin Workflow

Claude Code插件工作流

1. Check Current State

1. 检查当前状态

bash
undefined
bash
undefined

Read current version from manifest

Read current version from manifest

cat .claude-plugin/plugin.json | grep '"version"'
cat .claude-plugin/plugin.json | grep '"version"'

Check git is clean and up to date

Check git is clean and up to date

git fetch origin && git status
git fetch origin && git status

Review commits since last version bump

Review commits since last version bump

git log --oneline $(git describe --tags --abbrev=0 2>/dev/null || echo HEAD~10)..HEAD
undefined
git log --oneline $(git describe --tags --abbrev=0 2>/dev/null || echo HEAD~10)..HEAD
undefined

2. Bump Version in plugin.json

2. 升级plugin.json中的版本

Edit 
.claude-plugin/plugin.json
to increment the version field. For early-stage plugins (0.x.x or 1.0.x), bump the patch version unless the user requests otherwise:
0.1.6 → 0.1.7
1.0.23 → 1.0.24
编辑
.claude-plugin/plugin.json
以递增版本号。对于早期阶段的插件（0.x.x或1.0.x版本），除非用户另有要求，否则升级补丁版本：
0.1.6 → 0.1.7
1.0.23 → 1.0.24

3. Update CHANGELOG.md

3. 更新CHANGELOG.md

If a changelog exists, add an entry following the existing format:
markdown
undefined
如果存在变更日志，请按照现有格式添加条目：
markdown
undefined

[X.X.X] - YYYY-MM-DD

[X.X.X] - YYYY-MM-DD

Added

Added

  • New features
  • New features

Changed

Changed

  • Changes to existing functionality
  • Changes to existing functionality

Fixed

Fixed

  • Bug fixes

Summarize commits since the last release into appropriate categories.
  • Bug fixes

将上次发布以来的提交总结到相应类别中。

4. Validate Plugin Structure

4. 验证插件结构

Before publishing, verify the plugin is well-formed:
  • .claude-plugin/plugin.json
    has required 
    name
    field
  • Component directories (commands/, agents/, skills/, hooks/) contain valid files
  • Skills have 
    SKILL.md
    with valid YAML frontmatter (name + description)
  • Agents and commands have 
    .md
    files with YAML frontmatter
  • Referenced files and scripts exist
发布前，请验证插件格式正确：
  • .claude-plugin/plugin.json
    包含必填的
    name
    字段
  • 组件目录（commands/, agents/, skills/, hooks/）包含有效文件
  • 技能包含带有有效YAML前置元数据（名称+描述）的
    SKILL.md
  • Agent和命令包含带有YAML前置元数据的
    .md
    文件
  • 引用的文件和脚本均存在

5. Commit and Push

5. 提交并推送

Critical: Pushing to the default branch IS publishing. The Claude Code plugin marketplace automatically picks up the latest commit.
bash
git add .claude-plugin/plugin.json CHANGELOG.md
关键注意：推送到默认分支即完成发布。 Claude Code插件市场会自动获取最新提交。
bash
git add .claude-plugin/plugin.json CHANGELOG.md

Also stage any changed skill/agent/command files

Also stage any changed skill/agent/command files

git add -A git commit -m "Release vX.X.X" git push origin <default-branch>
undefined
git add -A git commit -m "Release vX.X.X" git push origin <default-branch>
undefined

6. Verify Publication

6. 验证发布结果

After pushing, verify the plugin update is available:
bash
CLAUDECODE= claude plugin update <plugin-name>@<publisher>
The 
CLAUDECODE=
prefix is required to avoid nested session errors when running from within Claude Code.
Note: The marketplace may take a few minutes to reflect the new version.
推送完成后，验证插件更新是否可用：
bash
CLAUDECODE= claude plugin update <plugin-name>@<publisher>
从Claude Code内部运行时，必须加上
CLAUDECODE=
前缀以避免嵌套会话错误。
注意： 市场可能需要几分钟时间来同步新版本。

7. Update Downstream References

7. 更新下游引用

If the plugin version is tracked elsewhere (e.g., a marketplace page, documentation, or 
lib/plugins.ts
), update those references to match the new version.
如果插件版本在其他地方被跟踪（例如市场页面、文档或
lib/plugins.ts
），请更新这些引用以匹配新版本。

Standalone Agent Skill Workflow

独立Agent Skill工作流

For skills not bundled in a Claude Code plugin, follow the agentskills.io specification.
对于未捆绑在Claude Code插件中的技能，请遵循agentskills.io规范。

1. Validate SKILL.md

1. 验证SKILL.md

Verify frontmatter meets the spec. For details, consult 
references/agentskills-spec.md
.
Required fields:
  • name
    : 1-64 chars, lowercase alphanumeric + hyphens, must match directory name
  • description
    : 1-1024 chars, describes what and when
Optional fields:
  • license
    , 
    compatibility
    , 
    metadata
    , 
    allowed-tools
验证前置元数据是否符合规范。详情请参考
references/agentskills-spec.md
。
必填字段：
  • name
    ：1-64字符，小写字母数字+连字符，必须与目录名称匹配
  • description
    ：1-1024字符，描述技能用途和适用场景
可选字段：
  • license
    、
    compatibility
    、
    metadata
    、
    allowed-tools

2. Validate Structure

2. 验证结构

skill-name/
├── SKILL.md          # Required
├── scripts/          # Optional executables
├── references/       # Optional docs loaded on demand
└── assets/           # Optional static resources
skill-name/
├── SKILL.md          # Required
├── scripts/          # Optional executables
├── references/       # Optional docs loaded on demand
└── assets/           # Optional static resources

3. Version via Metadata

3. 通过元数据管理版本

Track version in the frontmatter 
metadata
field:
yaml
metadata:
  author: org-name
  version: "1.1.0"
在前置元数据的
metadata
字段中跟踪版本：
yaml
metadata:
  author: org-name
  version: "1.1.0"

4. Distribute

4. 分发

Standalone skills distribute as directories. Common methods:
  • Git repository (push to GitHub)
  • Archive (zip the skill directory)
  • Package registry (if applicable)
独立技能以目录形式分发。常见方式：
  • Git仓库（推送到GitHub）
  • 压缩包（将技能目录打包为ZIP）
  • 包注册表（如适用）

Common Issues

常见问题

Plugin Not Updating

插件未更新

If 
claude plugin update
does not pick up changes:
  • Verify the push landed on the default branch (usually 
    main
    or 
    master
    )
  • Check that 
    .claude-plugin/plugin.json
    is valid JSON
  • Wait a few minutes for marketplace propagation
如果
claude plugin update
未检测到变更：
  • 验证推送是否已到达默认分支（通常为
    main
    或
    master
    ）
  • 检查
    .claude-plugin/plugin.json
    是否为有效的JSON格式
  • 等待几分钟，给市场同步时间

Version Already Exists

版本已存在

If the version string was already used in a previous commit, bump again to the next patch before pushing.
如果版本字符串已在之前的提交中使用，请先升级到下一个补丁版本再推送。

Nested Session Error

嵌套会话错误

Always prefix CLI commands with 
CLAUDECODE=
when running from within an active Claude Code session to avoid the "nested session" error.
从活跃的Claude Code会话中运行CLI命令时，必须始终添加
CLAUDECODE=
前缀以避免“嵌套会话”错误。

Additional Resources

额外资源

Reference Files

参考文件

  • references/agentskills-spec.md
     — Complete agentskills.io specification summary for standalone skills
  • references/agentskills-spec.md
     — 独立技能的完整agentskills.io规范摘要