如何写出可信的Skill CardNVIDIA Agent Skills技能治理文档编写标准【免费下载链接】skillsAgent Skills for NVIDIA products — install into Claude Code, Codex, and other coding agents to run Physical AI, robotics, simulation, CUDA, and RAG workflows end to end.项目地址: https://gitcode.com/gh_mirrors/skills36/skillsNVIDIA Agent Skills 是面向 Claude Code、Codex 等 AI 编程代理的官方技能目录覆盖 CUDA、Physical AI、机器人仿真与 RAG 等端到端工作流。每个技能在发布前都会配一份Skill Card技能卡片——一种面向人类的治理文档它记录技能的负责人、用途、风险、输出形态与参考证据让用户不打开源码就能判断这个技能是否可信、是否值得安装。本文带你掌握 NVIDIA 官方的 Skill Card 编写标准从 11 个必答问题、风险描述的强写法到用自动化工具生成初稿并完成人工审核。一、为什么需要 Skill Card信任管线的人类可读层 一份技能目录里的技能本质上是在指挥 AI 代理执行命令、读写文件、调用 API——它是一条新的软件供应链。NVIDIA 用五层证据回答信任问题而 Skill Card 恰好补足机器无法替人类回答的部分信任问题证据载体谁产出这个技能安全吗扫描报告SkillSpector / Tier 1自动扫描它真的让代理更强吗BENCHMARK.md基准报告Tier 3沙箱实测发布的就是审查过的那份吗skill.oms.sig分离签名签名管线它到底做什么、谁负责、边界在哪Skill Card作者撰写 人工审核扫描报告告诉审查者自动检查发现了什么签名告诉用户产物有没有被改动过而Skill Card 告诉用户你正在接受的是什么。详见 docs/agent-skill-trust-pipeline.mdx。二、Skill Card 必须回答的 11 个问题 一张可信的技能卡片每一节都在回答一个具体问题。对照 docs/skill-cards.mdx 的官方定义章节它回答的问题Description 描述这个技能一句话说清做什么Owner 负责人谁为这个技能负责License 许可证使用与再分发受什么规则约束Use Case 用例谁、在什么任务场景下使用Deployment Geography 部署地域技能面向全球还是特定区域Requirements 依赖运行它需要哪些组件与凭证Risks and Mitigations 风险与缓解可能出什么错如何降低该风险References 参考有哪些文档、论文或模型卡背书Skill Output 输出产出什么、什么格式Skill Version 版本这张卡片对应哪个发布/签名标识Ethical Considerations 伦理使用者应保持哪些治理意识核心原则描述必须与可执行行为一致——卡片里写的能力就是SKILL.md里实际会发生的行为不多不少。三、最小可用卡片10 个必备章节清单 ✅官方给出了一份最小发布模板写卡片时可以逐项打勾章节填写要点1. Description一句话具体行为 使用姿态商用 / 仅研发 / 仅演示2. Owner具体的人或可问责的团队不写某团队3. License/Terms直接写许可证名称如 Apache 2.0不要贴文件摘录4. Use Case点名目标用户与任务如开发者安装并验证 cuOpt5. Deployment Geography默认 Global除非文档明确限制6. Requirements声明是否需要 API Key 等外部凭证及类型7. Known Risks风险与缓解措施成对出现用大白话8. References真实文档 / 论文 / 扫描报告链接勿堆砌9. Skill Output输出类型、格式、参数与其他属性副作用、保留策略10. Skill Version版本号并注明来源frontmatter / CHANGELOG / 签名标识四、风险描述的强写法3 组改写示例 ⚠️模型可能出错这类模糊风险没有治理价值。可信的卡片要求每条风险都可行动官方给出了对照弱写法 ❌强写法 ✅技能可能会犯错。技能可能生成错误的修复步骤用户必须在执行前审查所有建议的代码变更。技能会调用 API。技能仅把包名发送到漏洞查询服务不传输源码或任何密钥。技能会写文件。技能可能覆盖输出目录中的生成报告它不得写入该目录之外的任何位置。规律很明显强写法 具体行为 明确边界 用户该做的动作。五、凭证声明别把没写当成没有 ️依赖章节中最容易踩坑的是凭证声明。skills/skill-card-generator/references/style-guide.md 定义了四种取值语义各不相同yes— SKILL.md 明确记载需要认证含 SSO/OAuth、文件型凭证、内网访问等隐性凭证no— 文档明确声明无需凭证optional— 文档明确记载存在免凭证的替代路径不能靠没看到 auth 章节推断not specified— 诚实的默认值记录凭证未被文档化而不是断言一定没有。同时声明凭证类型API key / OAuth Token / Cloud Credentials / Service Account / None并且严禁在卡片中出现任何密钥值、赋值或环境变量名——只写类型标签。六、用 Skill Card Generator 自动生成初稿 手写 10 个章节效率低且容易漏字段NVIDIA 提供了skill-card-generator技能把流程压缩为四步发现信号— 运行 scripts/discover_assets.py从目标技能的SKILL.md、frontmatter、LICENSE、CHANGELOG 等提取结构化信号构建上下文— 按 references/style-guide.md 逐字段填 JSON不确定的值标注 INFERRED 而不是留空渲染卡片— 用 references/skill-card.md.j2 模板确定性地渲染出 Markdown保证格式统一人工审核 校验— 推断出的负责人、许可证会以红色 VERIFY 标记呈现审查者确认或修正后移除标记再运行 scripts/validate_submission.py只要还有未解决的标记校验就会失败。⚠️ 记住边界生成器产出的是草稿。它验证字段结构不替代人类的法律、安全与负责人审查——机器填表 人类签字才是可信卡片的正确姿势。七、把卡片与发布证据连接起来 孤立的卡片只是陈述指向同一份审查证据的卡片才是凭证。以目录中的真实卡片 skills/cuopt-install/skill-card.md 为例它完整串联了评估证据使用 Claude Code 与 Codex 双代理、7 个评估任务数据集位于 skills/cuopt-install/evals/可验证的增益总体得分从基线 56% 提升到 90%34 分、可发现性从 27% 提升到 96%——这些数据同步收录在同目录的BENCHMARK.md中依赖声明明确标注无需 API Key类型 None参考与版本指向验证示例文档与版本号来源frontmatter。发布时应确保卡片能指向扫描报告或 CI 链接、源码仓库与发布标签、skill.oms.sig签名位置、底层模型卡与已知限制。完整的发布物料清单见 docs/release-checklist.mdx签名验证流程见 docs/signing-agent-skills.mdx。八、验收标准一张可信卡片的通过条件 官方审批规则只有一句话建议贴在评审会门口当审查者无需先打开源码就能理解技能的目的、负责人、输出、风险与发布证据时这张卡片才算完成。对照发布检查清单做最后一遍自查描述是一句话且点名实际行为负责人是具体的人或可问责团队许可证已链接且与 LICENSE 文件一致用例点名了目标用户与工作流部署地域明确每条风险都有对应的具体缓解措施输出类型与格式清晰版本/签名标识与本次发布一致写 Skill Card 不是给发布流程盖章而是把技能的行为边界翻译成人类能问责的语言。按这八个问题逐项落实你的卡片就能成为用户安装前最可靠的那份说明。附本篇引用的关键路径 资料路径Skill Card 编写标准docs/skill-cards.mdx信任管线总览docs/agent-skill-trust-pipeline.mdx发布检查清单docs/release-checklist.mdx技能评估指南docs/evaluating-agent-skills.mdx卡片生成器技能skills/skill-card-generator/真实卡片样例skills/cuopt-install/skill-card.md字段风格指南skills/skill-card-generator/references/style-guide.md【免费下载链接】skillsAgent Skills for NVIDIA products — install into Claude Code, Codex, and other coding agents to run Physical AI, robotics, simulation, CUDA, and RAG workflows end to end.项目地址: https://gitcode.com/gh_mirrors/skills36/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考