编写跨代理 SKILL.md 技能
技能是一个包含 SKILL.md 文件的文件夹。该文件以 YAML frontmatter 块（名称 + 描述）开头，后跟 Markdown 格式的指令，代理会根据需要加载这些指令。由于 Claude Code、DeepSeek Harness (dsh)、Codex CLI、Gemini CLI、Copilot 和 Cursor 都读取这种相同格式，一份编写得当的技能可服务于所有代理。
结构
my-skill/
├── SKILL.md # 必需：frontmatter + 指令
├── references/ # 可选：代理按需读取的详细文档
└── scripts/ # 可选：技能可能运行的辅助脚本
---
name: my-skill
description: >-
一两句话：它做什么以及何时使用。这是代理匹配用户请求的触发条件 — 请像一个路由规则一样编写它。
---
# 我的技能
逐步指令。假设使用者是一位胜任的工程师；要具体，不要模糊。
决定技能是否有效的规则
name必须为 kebab-case — 小写字母、数字、连字符；最长 64 个字符。代理会拒绝或混淆其他形式的名称。aipx会为您标准化处理，但最好直接提交正确的格式。description是触发条件，而非文档。 错误示例：“用于处理东西的实用工具。” 正确示例：“从 URL 总结 YouTube/Bilibili 视频和播客。当用户粘贴视频或音频链接时使用。”- 保持 SKILL.md 在 ~500 行以内。 将深度内容放在
references/*.md中并链接到它们（例如“请参见 references/schema.md”）。代理仅当技能触发时才会加载正文；过大的正文会浪费上下文并稀释行为。 - 无嵌套技能。 发现机制仅扫描技能根目录的 直接 子目录 —
skills/a/SKILL.md会被找到，skills/a/b/SKILL.md则不会。 - 相对链接必须保持相对。 如果 SKILL.md 引用
scripts/x.py，整个文件夹必须一起移动 — 切勿链接到技能目录之外。
技能存储位置（用户根目录）
| 根目录 | 读取方 |
|---|---|
~/.agents/skills/<name>/SKILL.md | DeepSeek Harness (dsh), Codex CLI |
~/.claude/skills/<name>/SKILL.md | Claude Code |
~/.gemini/skills/<name>/SKILL.md | Gemini CLI |
~/.copilot/skills/<name>/SKILL.md | GitHub Copilot CLI |
也存在项目范围的等效目录（例如仓库中的 .claude/skills/、.agents/skills/）。不要手动复制 — 使用 aipx sync 将一份副本链接到每个代理根目录。
发布前测试
# 检查解析和发现是否正常
aipx install ./my-skill --dry-run
aipx install ./my-skillaipx list
然后打开您的代理并确认技能已出现（Claude Code：它会显示在技能列表中；dsh：/ 命令面板 → Skills 分组）。
发布检查清单
- 仓库中包含技能文件夹，路径稳定，例如
skills/my-skill/ -
description描述了触发条件，而不仅仅是功能 - 从全新安装可正常运行（
aipx install owner/repo#path:/skills/my-skill） - 添加 GitHub 主题标签以便发现：
agent-skills、claude-code、dsh-plugin（如果同时也提供 dsh 捆绑包）、deepseek（如果与 DS 相关） - 可选：双重目标打包 — 请参见
dsh-plugin-dev和claude-plugin-dev技能