SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场agent-rules

agent-rules

编程与开发

查看项目

更新于 10-15 01:13

技能介绍

用途

agent-rules 是一个用于生成与维护 AGENTS.md 文件的技能，遵循 agents.md 约定。AGENTS.md 是面向 AI 代理的文档，而不是给人类阅读的文档。

何时使用

  • 为新项目或现有项目创建或更新 AGENTS.md
  • 搭建新仓库：在初始提交中就带上 AGENTS.md；事后补做需要完整重新验证
  • 跨仓库统一代理文档规范
  • 在代码变更后检查 AGENTS.md 是否过时
  • 让 AI 代理熟悉不熟悉的代码库

脚本

调用每个脚本时都应使用完整路径：bash ${CLAUDE_SKILL_DIR}/scripts/<name> PATH。相对于工作目录调用不在 frontmatter 规则覆盖范围内，且每次调用都会触发权限提示。

脚本及用途：

  • generate-agents.sh PATH：生成 AGENTS.md 文件
  • validate-structure.sh PATH：校验结构合规性
  • check-freshness.sh PATH：检查文件是否过时
  • verify-content.sh PATH：验证文档中记录的文件与命令是否与代码库一致
  • verify-commands.sh PATH：验证文档中记录的命令是否可执行
  • score-agents.sh PATH：给 AGENTS.md 质量评分，最差优先
  • detect-project.sh PATH：检测语言、版本、构建工具
  • detect-scopes.sh PATH：识别需要范围限定文件的目录
  • extract-commands.sh PATH：从构建配置中提取命令
  • extract-ci-rules.sh PATH：提取 CI 质量门禁与版本矩阵
  • extract-architecture-rules.sh PATH：提取模块边界
  • extract-adrs.sh PATH：提取架构决策记录
  • extract-github-rulesets.sh PATH：提取 GitHub 规则集与合并规则

完整选项见 references/scripts-guide.md。

工作流

  1. 检测：detect-project.sh + detect-scopes.sh，识别技术栈与子系统
  2. 提取：extract-commands.sh、extract-ci-rules.sh，收集事实
  3. 生成：generate-agents.sh --style=thin（默认）或 --verbose
  4. 验证：verify-content.sh + verify-commands.sh，完成前必须执行

行数上限：在提交任何根目录 AGENTS.md 编辑之前，wc -l AGENTS.md 必须低于 150 行（harness AH-02）；在存在 verify-harness.sh 的仓库中运行它，否则 CI 的 harness 检查会失败。

--update 会保留 <!-- GENERATED --> 标记之外的人工整理内容。

核心原则

  • 结构化优于散文：表格比段落解析更快
  • 绝不编造：只记录存在的内容；验证每条命令和路径
  • 指针原则：指向文件，不要复制内容
  • 自动软链接：默认创建 CLAUDE.md/GEMINI.md（见 ai-tool-compatibility.md）

参考文件

  • verification-guide.md：验证步骤、防膨胀、保留检查
  • fleet-sync-sweep.md：全舰队 AGENTS.md 批量更新
  • scripts-guide.md：脚本选项、验证清单
  • quality-rubric.md：评分标准
  • ai-tool-compatibility.md：16 个代理兼容性矩阵
  • output-structure.md：根级与范围限定章节
  • git-hooks-setup.md：钩子框架设置
  • examples/：完整示例
  • ai-contribution-guidelines.md：“3 Cs” AI 贡献框架
  • directory-coverage.md：范围限定文件覆盖理由
  • feedback-memory-schema.md：已批准学习文件格式

模板

根级：assets/root-thin.md（默认）或 root-verbose.md。范围限定：assets/scoped/，每个技术栈一个（Go/PHP/Python/TYPO3/Symfony/Oro/CLI/TS/skill-repo）。

支持的项目

Go、PHP（Composer/Laravel/Symfony/TYPO3/Oro）、TypeScript（React/Next/Vue/Node）、Python（pip/poetry/ruff/mypy）、skill 仓库、混合项目。

另见

  • agent-harness-skill：代理就绪度 harness（CI 强制执行）
  • skill-repo-skill：skill 仓库结构（plugin.json、许可、发布）