技术实践 on Tao

Claude Plugin 进阶：Marketplace 与项目规则实践

di4urp@gmail.com (taevas) — Thu, 12 Mar 2026 15:00:00 +0800

背景

在上文从零构建 Claude Skill中，我们完成了 hugo skill 的基础功能。本文记录二阶段开发：接入 Marketplace 和建立项目规则，以及过程中遇到的问题。

Marketplace 接入

marketplace.json 结构

{
 "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
 "name": "taevas-plugins",
 "version": "0.1.0",
 "description": "Taevas Plugins Marketplace",
 "owner": {
 "name": "743v45",
 "email": "noreply@743v45.com"
 },
 "plugins": [
 {
 "name": "hugo",
 "source": "./plugins/hugo",
 "category": "content",
 "description": "Publish content to Hugo blog..."
 }
 ]
}

关键字段说明：

字段	作用
`$schema`	JSON Schema 验证
`plugins[].source`	相对于 marketplace.json 的插件路径
`plugins[].category`	分类：content/notifications/development 等

插件目录结构规范

从 Skill 升级为 Plugin，需要遵循更严格的目录结构：

plugins/hugo/
├── .claude-plugin/
│ └── plugin.json # 插件元数据
├── skills/
│ └── hugo/ # 以 skill 名称命名的目录
│ ├── SKILL.md # 核心指令
│ ├── references/ # 参考文档
│ └── scripts/ # 脚本工具
└── README.md

遇到的问题

问题一：Skill 目录结构重构

现象： 最初 skills 目录结构混乱，无法正确加载。

原因： Skills 应该放在以 skill 名称命名的子目录中，而不是直接放在 skills/ 下。

解决： 重构目录结构

# 错误 ❌
skills/
├── hugo.md
├── references/
└── scripts/
# 正确 ✓
skills/
└── hugo/
├── SKILL.md
├── references/
└── scripts/

对应的 git commits:

f9be4f6 refactor(hugo): 重构插件目录结构
a6b6426 refactor(hugo): 重构 skill 目录结构

问题二：plugin.json 描述过于简单

现象： 插件加载后功能描述不清晰，用户不知道如何使用。

解决： 扩展 description 字段，详细说明所有使用模式：

{
 "description": "Publish content to Hugo blog. Supports: (1) /hugo alone - check installation, (2) /hugo with content - create/update post, (3) /hugo new <content> - force create, (4) /hugo update <content> - force update, (5) /hugo ... -c - preview with hugo server"
}

问题三：文章更新模式缺失

现象： 只能创建新文章，无法更新已有文章。

解决： 添加三种操作模式

模式	命令	行为
CREATE	`/hugo new <content>`	强制创建，存在则报错
UPDATE	`/hugo update <content>`	强制更新，不存在则报错
AUTO	`/hugo <content>`	搜索匹配文章，让用户选择

实现搜索功能需要扩展 detect_hugo_site.py：

def search_posts(directory: str, keywords: str) -> list:
 """Search posts by title or filename, return sorted by match score."""
 # 计算匹配分数
 # 标题匹配 +20，文件名匹配 +10
 # 分词匹配每个词 +5/+3

项目规则建立

Commit 规范

采用 Conventional Commits：

<type>(<scope>): <description>
类型：feat/fix/refactor/docs/style/test/chore
范围：hugo/sound-hooks 等

目录结构规则

.claude-plugin/
├── marketplace.json # 市场配置（项目根）
└── plugins/
└── <plugin-name>/
├── .claude-plugin/
│ └── plugin.json # 插件元数据
├── skills/
│ └── <skill-name>/
│ ├── SKILL.md
│ ├── references/
│ └── scripts/
└── README.md

文件命名规则

SKILL.md 大写，作为 skill 入口
脚本使用 snake_case: detect_hugo_site.py
参考文档使用 kebab-case: front-matter.md

总结

二阶段开发的核心工作：

接入 Marketplace - 建立 marketplace.json 和目录规范
重构目录结构 - skills 放入以名称命名的子目录
完善功能 - 添加文章搜索和更新模式
建立规则 - commit 规范、目录结构、命名约定

参考资料

从零构建 Claude Skill：以 Hugo 博客发布为例

di4urp@gmail.com (taevas) — Thu, 12 Mar 2026 12:00:00 +0800

背景

Claude Code 支持 Skill 系统，允许用户创建可复用的能力模块。本文以实际创建的 hugo skill 为例，详解 Skill 的构建过程。

什么是 Skill

Skill 是 Claude Code 的扩展机制，本质是一个包含指令和资源的目录：

skill-name/
├── SKILL.md # 核心：YAML frontmatter + Markdown 指令
├── scripts/ # 可执行脚本
├── references/ # 参考文档
└── assets/ # 输出资源

创建步骤

第一步：定义使用场景

明确 skill 要解决的问题。以 hugo skill 为例：

场景	用户输入	预期行为
检查环境	`/hugo`	检测 Hugo 安装和站点
创建文章	`/hugo 写一篇 Go 教程`	生成内容并发布
指定路径	`/hugo --path ~/myblog`	使用指定站点

第二步：规划资源需求

分析需要哪些辅助资源：

hugo/
├── scripts/
│ └── detect_hugo_site.py # 检测 Hugo 站点
├── references/
│ └── front-matter.md # Front matter 格式参考
└── SKILL.md

脚本的作用：检测站点需要遍历目录、检查配置文件，逻辑复杂，用 Python 脚本更可靠。

参考文档的作用：Front matter 有多种格式（TOML/YAML），放入 reference 按需加载。

第三步：编写 SKILL.md

Frontmatter 设计

---
name: hugo
description: "Publish content to Hugo blog. Use when user invokes /hugo command..."
---

description 是触发机制的关键：

必须包含 skill 功能
必须包含触发条件
会被 Claude 持续加载在上下文中

工作流设计

## Workflow

1. **Check Hugo installation**
2. **Determine Hugo site path**
3. **Determine content**
4. **Determine front matter format**
5. **Create the post**

每一步都有明确的指令，包括命令示例和预期输出。

第四步：实现脚本

# scripts/detect_hugo_site.py
def is_hugo_site(directory: str) -> dict:
 # 检查 config.toml / hugo.toml / config.yaml
 config_names = ["config", "hugo"]
 config_extensions = [".toml", ".yaml", ".yml", ".json"]

 # 返回检测结果
 return {
 "is_hugo_site": bool,
 "config_file": str,
 "content_dir": str,
 "existing_posts": list
 }

第五步：验证和迭代

# 测试脚本
python3 scripts/detect_hugo_site.py /path/to/hugo/site

# 实际调用
/hugo 写一篇测试文章

设计原则

1. 渐进式披露

Skill 采用三层加载机制：

层级	内容	加载时机
Metadata	name + description	始终
SKILL.md body	工作流指令	触发后
references/	详细文档	按需

2. 简洁至上

SKILL.md 应控制在 500 行以内，详细内容放入 references。

3. 自由度匹配

自由度	适用场景	hugo skill 示例
高	多种有效方案	文章内容由 LLM 生成
中	有首选模式	Front matter 格式检测
低	必须精确执行	站点检测脚本

最终结构

hugo/
├── SKILL.md # 2.8KB，核心指令
├── scripts/
│ └── detect_hugo_site.py # 92 行，站点检测
├── references/
│ └── front-matter.md # Front matter 格式参考
└── LICENSE.txt

总结

构建 Skill 的核心是明确场景 → 规划资源 → 精简指令。好的 skill 应该：

在 description 中清晰描述触发条件
用脚本处理确定性任务
用 references 存放详细文档
保持 SKILL.md 精简