用途
author-skills 用于在 Great Docs 文档站点中创建和分发 Agent Skills。Agent Skill 是一种结构化 Markdown 文件（SKILL.md），为 AI 编程智能体提供某个软件包及其 API 和最佳实践的相关上下文。Great Docs 为技能提供三种支持场景，投入程度与控制力各不相同。
三种场景
场景一：自动生成。在 great-docs build 期间，工具读取 pyproject.toml（名称、描述、许可证、Python 版本）、API 参考章节以及 skill.* 配置项，自动生成 skill 文件，内容包含安装说明、API 概览、注意事项、最佳实践和资源链接。可在 docs/great-docs.yml 的 skill 段配置 enabled（默认 true）、well_known、gotchas、best_practices、decision_table、extra_body 等选项。适合希望以最小投入获得基于 API 参考自动生成内容的用户。
场景二：单个手写技能。手动（或借助 LLM）编写 SKILL.md，并在 docs/great-docs.yml 中用 skill.file 指向它。建议将技能放在包根目录的 skills/ 目录下，路径以 ../skills/ 为基准。构建时 Great Docs 会把文件复制为 <docs>/skill.md，放入 .well-known/agent-skills/<name>/SKILL.md，并生成带安装说明和完整内容的 Skills 页面。适合需要对内容进行完整编辑控制的情况。
场景三：多个具名技能。在单个站点分发多个聚焦技能。每个技能在 Skills 页面有独立面板（带切换栏），并在 .well-known/agent-skills/index.json 中有独立条目，支持 npx skills add 发现。配置时用 skill.skills 列出各技能的 name 与 file；第一项成为站点根目录的主 skill.md，所有条目可通过 npx skills add 单独安装。适合项目包含不同侧重的技能（如通用使用、贡献、配置）。
使用方式
手写技能的基本步骤：创建 skills/my-package/references 目录，编写 SKILL.md（含 YAML frontmatter，字段包括 name、description、license、compatibility、metadata 中的 author、version、tags），在 docs/great-docs.yml 添加 skill: file: ../skills/my-package/SKILL.md，然后运行 great-docs build 并检查 Skills 页面。正文建议按安装、何时使用什么（决策表）、API 概览、注意事项、最佳实践、资源等结构组织。过于详细的内容可放入 references/ 子目录，这些文件会被复制到 .well-known/agent-skills/<name>/references/。
写作建议
面向 LLM 读者而非人类读者；对模型可能混淆的区别要明确说明；多用具体示例；决策表每行应把任务映射到具体函数或方法；避免表情符号、长破折号和无引导语直接列清单；SKILL.md 保持在 2000 行以内，详细参考材料移入伴随文件。
发现与分发
Great Docs 在两个 well-known 路径发布技能：<site>/.well-known/agent-skills/<name>/SKILL.md 与 <site>/.well-known/agent-skills/index.json。index.json 列出所有技能的名称、描述和相对路径。根级 <site>/skill.md 始终包含主技能。可用 great-docs check-skill 检查已发布技能、great-docs list-skills 列出清单技能，部署后用 npx skills add <site-url> 测试安装。
限制与注意事项
skill.skills 会覆盖 skill.file，两者同时设置时后者被忽略；每个技能 name 必须唯一，重复会导致后者在 .well-known/ 中覆盖前者；只有 references/ 子目录下的文件会被复制；技能名应使用连字符而非下划线，并与目录名一致；skill.skills 中第一项会成为站点根目录的主 skill.md 和 Skills 页面默认面板；设置 skill.enabled: false 可完全禁用自动生成和手写技能处理。关于收费、价格、平台支持等信息暂未提供。