概述

在不安装 Skill 的情况下校验结构化 Skill 对象或原始 SKILL.md 文本。业务层面的校验失败不会使用 HTTP 错误：只要请求结构合法，接口仍返回 HTTP 200，并通过 result.valid=false 和 result.errors 表示内容不合规。
strict 语义。name 和 description 缺失始终是 error。目录名不一致、名称长度/字符集不合规、description 超长在 strict=false 时是 warning，在 strict=true 时升级为 error。strict=true 且正文超过 500 行仍只产生 warning。

请求接口

URI	`/api/v1/skills/validate`
请求方法	POST
Content-Type	`application/json`
认证	`Authorization: Bearer {API_KEY}`

请求参数

参数	类型	必选	默认值	说明
`data`	string / object	是	—	待校验的原始 SKILL.md 文本或结构化 Skill 对象。
`strict`	bool	否	false	是否将目录名不一致、名称长度/字符集、description 长度等规则升级为 error。
`source_path`	string	否	null	来源路径标签，仅回显到响应中，便于批量校验定位文件。
`skill_dir_name`	string	否	null	预期目录名，用于检查是否与 Skill 的 name 一致。
`target_uri`	string	否	null	当前请求模型接收该字段，但校验实现不读取它；它不会改变校验规则或结果，建议不要传。

响应消息

字段	类型	说明
`result.valid`	bool	是否通过校验。
`result.strict`	bool	本次是否启用 strict 模式。
`result.name`	string	解析出的 Skill 名称。
`result.description`	string	解析出的 Skill 描述。
`result.tags`	array	解析并归一化后的标签。
`result.allowed_tools`	array	解析并归一化后的允许工具列表。
`result.body_lines`	integer	Markdown 正文行数。
`result.source_path`	string	请求中 source_path 的回显。
`result.skill_dir_name`	string	请求中 skill_dir_name 的回显。
`result.errors`	array	错误项；每项包含 rule、message，必要时包含 field。
`result.warnings`	array	警告项，结构同 errors。

完整示例

curl -X POST "{BASE_URL}/api/v1/skills/validate" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "data": "---\nname: search-web\ndescription: 搜索互联网中的最新信息\n---\n\n# Search Web\n\n执行网络搜索。",
    "strict": true,
    "source_path": "skills/search-web/SKILL.md",
    "skill_dir_name": "search-web"
  }'

{
  "status": "ok",
  "result": {
    "valid": true,
    "strict": true,
    "name": "search-web",
    "description": "搜索互联网中的最新信息",
    "tags": [],
    "allowed_tools": [],
    "body_lines": 3,
    "source_path": "skills/search-web/SKILL.md",
    "skill_dir_name": "search-web",
    "errors": [],
    "warnings": []
  }
}

未通过校验示例

{
  "status": "ok",
  "result": {
    "valid": false,
    "strict": false,
    "errors": [
      {
        "rule": "description_required",
        "message": "description is required",
        "field": "description"
      }
    ],
    "warnings": []
  }
}

常见规则名

rule	说明
`yaml_format`	缺少 YAML frontmatter 或 YAML 无法解析。
`name_required`	缺少 name。
`description_required`	缺少 description。
`name_matches_directory`	name 与 skill_dir_name 不一致。
`name_max_length`	name 超过 64 个字符。
`name_allowed_characters`	name 含 ASCII 字母、数字、下划线、连字符以外的字符。
`description_max_length`	description 超过 1024 个字符。
`body_max_lines`	strict=true 且正文超过 500 行；当前仍为 warning。

最近更新时间：2026.07.22 18:07:44

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

概述 #

请求接口 #

请求参数 #

响应消息 #

完整示例 #

未通过校验示例 #