开发者指南

Skill 是一段 Markdown 格式的 AI 系统指令，它告诉 AI Agent（如 Hermes） 在面对特定任务时应如何思考、执行和输出。你可以把 Skill 理解为给 AI 安装的「专业模块」—— AI 原本是通才，加载 Skill 后就变成了该领域的专家。

Skill 的典型用途

• 剧本创作：定义角色分析、对话润色、情节结构的系统方法
• 代码规范：强制特定的代码风格、命名约定和架构模式
• 翻译工作流：先理解语境→直译→本地化润色→质量检查的多步流水线
• 数据分析：从原始数据到可视化报告的完整分析框架
• 内容审核：敏感内容识别、合规检查的判定标准和输出格式

Skill 文件结构

---
name: 剧本内容填充
description: 帮助分析剧本，填充场景细节、角色对话和情感层次
tags: [writing, creative, script]
version: 3
---

## 角色设定
你是一位经验丰富的剧本顾问和故事架构师...

## 核心工作流
1. **需求分析**：理解用户提供的剧本草稿...
2. **结构优化**：检查三幕结构...
3. **内容填充**：逐场景扩展...

## 输出规范
- 保留原剧本的全部情节走向
- 新增内容用 **[新增]** 标记
- 修改建议用 **[建议]** 标记

关键字段：YAML 前置元数据（name / description / tags）用于市场展示和搜索； Markdown 正文即为 AI 加载的实际指令。

方式一：通过控制台发布

1. 登录 app.neowow.studio，在控制台选择「上传技能」模式
2. 填写 Skill 名称、简短描述和标签（用于市场分类和搜索）
3. 粘贴 Markdown 格式的 Skill 内容，或直接上传 .md 文件
4. 点击发布，Skill 即刻上架到市场，其他用户可以订阅

方式二：通过 API 上传

适合 CI/CD 流水线或 AI Agent 自动化发布：

POST https://app.neowow.studio/api/skills
Authorization: Bearer <your-access-token>
Content-Type: application/json

{
  "name": "剧本内容填充",
  "description": "帮助分析剧本...",
  "content": "# 技能内容\n\n## 角色设定\n...",
  "tags": ["writing", "creative"],
  "displayName": "费元华"
}

方式三：通过 Hermes Agent 终端

# 从本地 .md 文件发布
$ hermes skill-publish ./my-skill.md

# 通过对话创建
用户：帮我创建一个 Skill，名为"SEO 文章优化"...
Hermes：已创建并发布到市场 ✅

# 查看我的所有 Skill
$ hermes skills mine

当你修改 Skill 内容并重新发布时，系统会自动递增版本号。 所有已订阅该 Skill 的用户都会收到 「有新版本」 的提醒。

1. 在「我的分享」或「技能市场」中找到你的 Skill
2. 点击「更新」按钮，修改内容后保存
3. 版本号自动 +1，订阅者端显示更新提示
4. 订阅者点击「同步」即可获取最新版本

通过 API 更新

PUT https://app.neowow.studio/api/skills/skill-kwgtob7?ownerId=<your-id>
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "剧本内容填充 v2",
  "description": "新增了角色弧光分析功能",
  "content": "# 更新的内容...",
  "tags": ["writing", "creative", "character"]
}

浏览与订阅

1. 访问 市场 → 技能 浏览所有可用 Skill
2. 点击感兴趣的 Skill 卡片进入详情页
3. 查看简介、标签、订阅数和评论
4. 点击「订阅」—— 订阅后 Skill 自动同步到 Hermes Agent

在 Hermes Agent 中使用

# 已订阅的 Skill 自动出现在可用列表中
$ hermes skills list
  📝 剧本内容填充          v3    ⭐ 已安装
  🎨 资产设计              v1    ⭐ 已安装
  📊 数据分析框架          v2    🔄 有新版本

# 在对话中自动触发
用户：使用「剧本内容填充」优化这段剧本...
Hermes：（自动加载 Skill 指令，按 Skill 定义的工作流执行）

# 手动订阅
$ hermes skills subscribe skill-kwgtob7

# 同步最新版本
$ hermes skills sync skill-kwgtob7

# 取消订阅
$ hermes skills unsubscribe skill-kwgtob7

Skill 同步原理

支持的 Skill 类型

Anthropic Claude Skills 格式参考

官方文档:anthropic.com/news/skills

my-claude-skill/
├── SKILL.md         # 主文件,需要 YAML frontmatter
├── README.md        # (可选) 给人类读的文档
├── references/      # (可选) 额外上下文,如 example*.md
└── scripts/         # (可选) Python/shell 工具脚本

# SKILL.md 顶部 frontmatter 示例:
---
name: pdf-summary
description: Read a PDF and produce structured summary
license: MIT
---

# Skill 主体...

转换为 Hermes 标准 (复选框)

上传通用 / Claude 格式时,可勾选 "✨ 同时转换为 Neowow Hermes 标准"。 v1 仅打 convertedToHermes: true 标记 + 存原文不动;后续版本会:

• 在 SKILL.md 顶部注入 Hermes frontmatter
• 添加 hermes.yaml 声明能调用的平台能力(生图 / 视频 / KV / CLI 等)
• 引用商城里其他 Skill(skill-to-skill 调用)

💡 你现在勾上没什么副作用,等转换器上线后,标记过的 skill 会被批量处理一次。

文件大小限制

• 单文件 ≤ 500 KB
• 整个 skill (所有文件) 序列化后 ≤ 1.5 MB(TableStore 列上限是 2 MB,留 padding)
• Zip 上传 ≤ 10 MB(解压后还要满足上面两条)
• 非文本类型(图片/二进制) v1 拒绝 — 把图放外部 CDN,在 SKILL.md 里用 URL 引用

API 字段(给程序化上传用)

POST /api/skills?ownerId=<id>
{
  "name":              "my-skill",
  "description":       "...",
  "skillType":         "claude",            // 'generic'|'claude'|'hermes'
  "files":             {
    "SKILL.md":              "---\nname: ...\n---\n# ...",
    "references/example.md": "...",
    "scripts/helper.py":     "..."
  },
  // 多文件模式: content 可为空,服务器从 files 里挑 SKILL.md / README.md
  // 当镜像(向下兼容老 viewer)。也可显式传 content 覆盖
  "content":           "",
  "convertedToHermes": true,                // 转换标记
  "tags":              ["pdf"],
  "visibility":        "private",
  "allowedUsers":      ["1928091762437005312"]
}

访问规则

🔍 注意: 非授权用户得到的是 404 Not Found 而不是 403 Forbidden — 这是故意的,不让外部窥探"这个 Skill 是否存在"。

如何拿到对方的 userId

让对方在登录状态的浏览器 console 跑:

fetch('/api/me/whoami', { credentials: 'include' })
  .then(r => r.json())
  .then(d => console.log(d.userId));

返回 19 位数字(例如 1928091762437005312),粘到 "白名单" 输入框即可。每行一个,或用逗号分隔。

grandfathered subscribers (老订阅者保留访问)

技能从 公开 切换到 私有 后,已经订阅过的用户保留访问权限 — 你不需要为每个人手动加白名单。 作者只想未来不让陌生人订阅 时,直接切私有(白名单留空)就行。 想把现有订阅者也踢出 的话…目前 UI 没暴露这个功能,需要联系运营手动改 row。

API 字段(给程序化集成用)

POST /api/skills 创建时和 PUT /api/skills/{id} 更新时,body 接受:

{
  "name":         "我的私有技能",
  "content":      "...",
  "visibility":   "private",                  // 'private' (默认) | 'public'
  "allowedUsers": [
    "1928091762437005312",                    // 作者主账号
    "1922456789012345678"                     // 协作者 A
  ]
  // ... 其他常规字段
}

字段 allowedUsers 仅在 visibility="private" 时生效;visibility="public" 时即使列出也被忽略,但会保存以便日后切回私有时不丢失。

Phase ζ.8 起默认值已从 public 改为 private — 创作者没显式设置时技能不会被广播到公共市场。如需上架公共市场，发布时显式传 visibility: "public"。

申请-审批流(Phase ζ.8)：除 allowedUsers 之外，作者无需事先收集 userId。其他登录用户在私有技能详情页可点击「申请访问」自动提交请求；作者在该技能的「管理 ▾ → 待审批」菜单或 /skills 顶部的访问请求横幅审批通过即可。涉及的 API：

• POST /api/skills/{id}/access-requests — 申请访问（任意登录用户）。Body: { requesterDisplayName, message? }。幂等：同 userId 重复提交会刷新现有请求。
• GET /api/skills/{id}/access-requests?ownerId=... — 列出待审批请求（仅作者）。
• PUT /api/skills/{id}/access-requests?ownerId=... — 审批（仅作者）。Body: { requesterId, action: "approve" | "deny" }。approve 会把 requesterId 加入 allowedUsers。
• GET /api/me/access-requests?ownerId=...&ownerIds=... — 跨所有自己技能的待审批收件箱（用于 /skills 横幅）。

反爬虫：对未登录调用方，私有技能 GET 仍返回 404（不泄漏存在性）。登录用户在私有技能上无访问权时返回 200 + 元数据残缺（_canRequestAccess: true），用于展示申请按钮但不暴露内容/文件。