lggarrison/agent-skills

仓库初始化

每次新建仓库都需要相同的基础配置：许可证、安全问题的报告方式、README、使PR和Issue更有用的模板，以及运行与贡献者在本地相同的检查的CI。本技能是这一基础配置的清单和执行方式。

仓库规则优先

在添加任何内容之前，先阅读仓库已有的文件：AGENTS.md / CLAUDE.md、CONTRIBUTING.md、现有的 .github/ 文件、包清单及其脚本，以及任何CI配置。如果它们设定了约定（默认分支、许可证、工具、文件位置），请遵循。切勿为了匹配此处的模板而覆盖现有文件。应扩展它，或保留它并指出差距。

工作流程

1. 明确需求

• 引导（Bootstrap）： 新建或几乎为空的仓库。完成整个清单。
• 填补空白（Fill gaps）： 现有仓库缺少部分内容。仅添加缺失的部分。
• 审计（Audit）： 报告缺失或薄弱的部分，不修改任何内容。

2. 盘点

列出哪些清单文件存在，并读取清单文件（package.json、pyproject.toml、go.mod、Cargo.toml 等）以了解语言、脚本以及项目是否已发布。使用 git remote show origin 或 gh repo view --json defaultBranchRef 查找默认分支。不要询问用户你通过这种方式就能了解到的任何信息。

3. 询问需要判断的事项

这些是用户需要做出的决定。仅询问一次，简短地提出，并在有证据支持时提供建议：

• 许可证，以及版权持有者的姓名。
• 安全联系人： GitHub 私有漏洞报告、电子邮件地址，或两者都提供。
• 行为准则联系人（如果添加）。
• PR 基础分支，如果它不是默认分支。
• 是否已发布： 发布到包注册表，或作为发布工件。
• CI 矩阵： 要支持的操作系统和运行时版本。

4. 编写文件

按顺序完成清单，跳过不适用的部分。

• 获取规范文本，不要凭记忆输入。 从 gh api licenses/<spdx-id> --jq .body（例如 mit 或 apache-2.0）获取许可证文本，然后填写年份和持有者。从官方来源（如 Contributor Covenant）获取行为准则。
• 调整模板。 从 templates/ 开始。替换每个 <placeholder>，并将命令修改为此仓库中存在的命令。一个列出了仓库中没有的脚本的模板比没有模板更糟糕。
• 统一的检查列表。 PR 模板清单、CONTRIBUTING.md、预提交钩子和 CI 应全部命名相同的命令。当其中一个更改时，请更改其他部分。
• 更改设置前先询问。 分支保护、规则集和私有漏洞报告是仓库设置，而不是文件。仅在用户同意时提出并应用它们。

5. 检查

• 模板、钩子或 CI 作业中命名的每个命令都能在本地运行并通过。
• 任何文件中都没有留下 <placeholder>。
• Issue 表单和工作流是有效的 YAML。Issue 表单仅出现在默认分支上，因此在合并后在那里检查它们。
• 链接可解析，包括安全策略 URL。
• 仓库自身的格式和 lint 检查在新文件上通过。

6. 报告

说明你添加了什么、保留了什么及其原因、你建议的仓库设置，以及任何尚未解决的判断事项。

清单

R 表示必需，rec 表示推荐，opt 表示可选。

工具

• R git，以及语言运行时和包管理器。
• rec 运行时版本管理器（如 nvm、fnm、pyenv 等），与固定的版本文件匹配。
• rec gh，已通过 gh auth login 认证，供维护者使用。

法律和社区

• R LICENSE。
• R SECURITY.md：支持的版本、如何私下报告，以及报告者在报告后可以期待什么。
• rec CONTRIBUTING.md：设置、要运行的检查、分支和提交约定，以及 PR 如何被审查。
• rec CODE_OF_CONDUCT.md，带有真实的执行联系人。
• rec CHANGELOG.md，格式遵循 Keep a Changelog。

文档

• R README.md：项目介绍、安装方法、最小使用示例，以及链接到 CONTRIBUTING.md、SECURITY.md 和许可证。
• opt AGENTS.md：编码代理的供应商中立入口点。提供要运行的命令和要遵循的规则，并链接到其他文档而不是重复它们。
• opt RELEASING.md，适用于已发布的项目。参见发布。

编辑器和 Git 卫生

• R .gitignore，针对语言、构建输出和本地环境文件。
• rec .gitattributes，包含 * text=auto eol=lf，以便行结束符不会在不同操作系统之间切换。
• rec .editorconfig，用于字符集、文件结尾换行和缩进。

GitHub 模板和自动化

如果仓库不在 GitHub 上，请使用主机的等效内容。

• rec .github/PULL_REQUEST_TEMPLATE.md。参见模板。
• rec .github/ISSUE_TEMPLATE/ 中的 Issue 表单：bug_report.yml、feature_request.yml，以及一个关闭空白 Issue 并将安全报告指向私有渠道的 config.yml。参见模板。
• rec .github/dependabot.yml，为仓库使用的每个包生态系统以及 github-actions 各添加一个条目。
• R .github/workflows/ci.yml，在每个 PR 和每次推送到默认分支时运行与 PR 模板相同的检查。
• opt .github/release.yml，按标签对生成的发布说明进行分组。
• opt .github/workflows/release.yml，仅适用于已发布的项目。
• rec 默认分支上的分支保护或要求 CI 通过的规则集。这是一个设置，因此先询问。

Node.js 和 TypeScript

对于其他语言请跳过此部分，并使用该生态系统的工具应用相同的理念：固定的运行时版本、格式化工具、linter、测试运行器、单个“检查所有内容”的命令以及 CI 矩阵。

运行时和元数据

• rec .nvmrc，以及 package.json 中的 engines.node，二者保持一致。
• R package.json 中的 repository、homepage、bugs、license 和 author。
• rec "type": "module" 用于原生 ESM。

TypeScript（仅限 TypeScript 项目）

• R typescript 和 tsconfig.json，并设有 npm run build 来编译。
• 不要将 JavaScript 项目转换为 TypeScript。对于新项目，是否使用 TypeScript 由用户决定。

格式和 lint

• rec Prettier（.prettierrc.json、.prettierignore）和 ESLint 扁平配置。
• rec 脚本 lint、lint:fix、format 和 format:check。

单元测试

• R 运行单元测试的 npm test。
• rec Vitest，测试文件与源代码放在一起（src/**/*.test.ts），共享的 fixture 放在 test/ 中。

端到端测试（可选，适用于带有 UI 或浏览器流程的项目）

• rec @playwright/test、playwright.config.ts，以及 e2e/ 中的测试。
• rec npm run test:e2e 脚本。
• rec 将 playwright-report/、test-results/ 和 blob-report/ 添加到 .gitignore。
• rec 一个 CI 作业，使用 npx playwright install --with-deps 安装浏览器，并在测试失败时上传报告。
• opt 对于没有浏览器的 CLI，可以通过单独的 Vitest 配置来运行端到端测试。

Git 钩子（仅限本地开发）

• rec Husky，带有运行 lint-staged 的 pre-commit 钩子。
• rec 一个 prepare 脚本，当设置了 CI 或 NODE_ENV=production 时跳过安装 Husky，以便在 CI 和生产环境中的安装不会失败。
• opt 运行单元测试的 pre-push 钩子。

质量门

• rec 一个脚本，例如 check，按顺序运行 lint、format:check、单元测试、构建和端到端测试。CI 和贡献者都运行它。
• rec 跨支持的操作系统和 Node.js 版本的 CI 矩阵。

发布

适用于发布到包注册表的项目。对于其他所有项目，这些是可选的。

• rec package.json 中的 "files" 白名单（或 .npmignore），使用 npm pack --dry-run 检查。
• rec 运行构建的 prepublishOnly 脚本。
• rec 从 CI 使用 npm Trusted Publishing（OIDC，id-token: write）发布，这样就不需要将长期存在的令牌存储为机密。
• rec RELEASING.md，涵盖版本选择方式（语义化版本）、发布如何标记、阻止错误标签的检查，以及如何回滚。

模板

文件	复制到
templates/PULL_REQUEST_TEMPLATE.md	.github/PULL_REQUEST_TEMPLATE.md
templates/ISSUE_TEMPLATE/bug_report.yml	.github/ISSUE_TEMPLATE/bug_report.yml
templates/ISSUE_TEMPLATE/feature_request.yml	.github/ISSUE_TEMPLATE/feature_request.yml
templates/ISSUE_TEMPLATE/config.yml	.github/ISSUE_TEMPLATE/config.yml

占位符的格式为 <like-this>。例如，将 <runtime-version-command> 替换为 node --version、python --version 或 go version。模板中的其他命令来自 Node.js 项目的示例。请将它们替换为该仓库自己的命令。