如何安装 skills-ref 并完成 Agent Skills 技能首次校验？

如何安装 skills-ref 并完成 Agent Skills 技能首次校验？

【免费下载链接】agentskillsSpecification and documentation for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/ag/agentskills

你写好了一个 Agent Skill（一个包含SKILL.md的文件夹），需要确认它的 frontmatter 合法、命名符合规范，再交给 agent 使用。agentskills 仓库中的skills-ref参考库提供了skills-ref validate命令完成这次首次校验。本文流程：在 Python 虚拟环境中安装 skills-ref，准备一个待校验的技能目录，运行校验命令，并根据输出和退出码判断结果。

前提条件与限制：

• Python 3.11 及以上。skills-ref/pyproject.toml 声明requires-python = ">=3.11"，依赖click>=8.0和strictyaml>=1.7.3会在安装时自动解析。
• skills-ref 的 README 明确说明：该库仅供演示（demonstration purposes only），不打算用于生产环境。
• 以下命令都在 agentskills 仓库的skills-ref/目录内执行（pip install -e .和uv sync都以该目录下的pyproject.toml为项目根）。

安装 skills-ref

macOS / Linux（pip）

python -m venv .venv source .venv/bin/activate pip install -e .

macOS / Linux（uv，可选替代）

uv sync source .venv/bin/activate

Windows（pip）

PowerShell：

python -m venv .venv .venv\Scripts\Activate.ps1 pip install -e .

Command Prompt：

python -m venv .venv .venv\Scripts\activate.bat pip install -e .

Windows 使用 uv（PowerShell）：

uv sync .venv\Scripts\Activate.ps1

安装成功的判断标准来自 README：在激活的虚拟环境中，skills-ref可执行文件会出现在PATH上。安装完成后直接进入下面的校验步骤即可确认它可用。

准备待校验的技能

一个技能是一个包含SKILL.md的文件夹，SKILL.md必须由 YAML frontmatter 开头，后接 Markdown 正文（正文本身没有格式限制，见 specification）。首次校验只检查 frontmatter 和命名规则，要求：

• name必填：最长 64 个字符，只允许小写字母、数字和连字符，不能以连字符开头或结尾，且必须与所在目录名一致；
• description必填：非空，最长 1024 个字符；
• frontmatter 中只接受name、description、license、allowed-tools、metadata、compatibility这些字段，出现其他字段会被判为校验错误；
• compatibility若填写，最长 500 个字符。

如果还没有现成的技能，可以直接用 Quickstart 中的roll-dice技能作为首次校验对象。创建目录roll-dice/，写入roll-dice/SKILL.md：

--- name: roll-dice description: Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.), roll dice, or generate a random dice roll. --- To roll a die, use the following command that generates a random number from 1 to the given number of sides: ```bash echo $((RANDOM % <sides> + 1)) ```

正文中的<sides>是技能指令内部给 agent 运行时替换的占位符（Quickstart 文档说明了替换方式），不是安装或校验前需要处理的模板变量——校验不解析正文内容。

执行首次校验

在激活虚拟环境的 shell 中，对技能目录运行：

skills-ref validate roll-dice

换成自己的技能时，把参数换成技能目录路径，例如 specification 中给出的形式：

skills-ref validate ./my-skill

参数要求（来自 CLI 实现）：

• 路径必须存在；
• 可以指向技能目录，也可以直接指向目录内的SKILL.md文件（小写skill.md也识别），直接指向文件时命令会自动改用其父目录；
• 退出码：0表示技能有效，1表示发现校验错误。

判读校验结果

成功时（退出码 0），输出形如：

Valid skill: roll-dice

失败时（退出码 1），输出Validation failed for <路径>:，随后每条错误单独一行，例如：

Validation failed for my-skill: - Skill name 'MySkill' must be lowercase

以上是按源码中实际的消息格式构造的示例结果，你的输出取决于具体的技能内容。出现失败时，按下面的对照表定位原因（消息文本来自 validator.py 与 parser.py）：

这些规则在 tests/test_validator.py 中有对应的测试用例，可以对照阅读每种失败的具体形态。

用 read-properties 交叉核对（可选）

校验通过后，可以用第二条命令确认 frontmatter 实际被解析成了什么：

skills-ref read-properties roll-dice

它会解析SKILL.md的 YAML frontmatter 并以 JSON 输出技能属性（name、description及可选字段）。退出码0表示成功，1表示解析错误，失败时输出Error: ...。这条命令不做完整校验，只反映 agent 发现技能时读取的元数据。

限制与下一步

• skills-ref validate检查的是 frontmatter 的合法性与命名规范；SKILL.md正文没有格式限制，校验不检查正文内容，也不检查技能实际能否完成任务。
• skills-ref是参考实现，仅供演示，生产用途请使用其他工具链。
• 下一步：技能校验通过后，可以用skills-ref to-prompt <技能目录> [更多技能目录]生成<available_skills>XML 块，放入 agent 的系统提示词；该格式推荐给 Anthropic 的模型，其他 Skill Client 可以自行调整格式（见 skills-ref README）。

【免费下载链接】agentskillsSpecification and documentation for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/ag/agentskills