ai-agent-context 是一个面向源码目录的文档撰写技能,来自 aws-samples/ai-skills。其核心任务是产出目录级的上下文文档对:CLAUDE.md 与 README.md,让进入该目录的人类开发者和 AI 助手都能快速获得必要背景。
用途 该技能用于为指定源码目录补齐上下文说明。它不替代代码注释或对外文档站点,而是聚焦于“进入一个目录时需要立刻知道什么”,尤其是那些不知道就会写错代码、用错服务或浪费时间的信息。
主要能力
- 上下文加载:读取项目根目录的 README.md、AGENTS.md 与 CLAUDE.md(跳过仅指向 @AGENTS.md 的 CLAUDE.md),并读取 .ai-skills.toml 中 context_files 列出的仓库内文件,从中提取目标、约束与关键术语,用于指导 CLAUDE.md 的内容。
- 深度阅读:要求通读目标目录中的每个文件,追踪函数调用、识别外部服务封装、查找环境变量读取点、发现校验约束,而不是只看签名。
- 内容分流:对每条候选事实套用内容测试——若 AI 助手不知道就会犯错或浪费时间,则写入 CLAUDE.md;否则若仍有参考价值,则写入 README.md,两者不重复。
- 事实核查:文件名、路径、环境变量、服务名等必须通过阅读实际代码确认。
- 模板化产出:CLAUDE.md 使用目录路径作为一级标题,正文 3 至 8 行、最多 10 行,每条为一条防错事实,结尾指向 README.md 并说明其覆盖内容;README.md 按内容、领域专属章节、Known Quirks、环境变量、集成点、相关链接等模板组织,只保留有内容的章节。
使用方式 该技能仅通过 /ai-agent-context 斜杠命令调用,不应自动激活;目标目录通过 $ARGUMENTS 传入。
适用场景 适用于任何代码库中需要为某个目录建立人机共用上下文的场合,尤其是封装外部服务、依赖特定 IAM 权限或环境变量、存在隐蔽输入校验或一致性行为的目录;Known Quirks 章节在封装外部服务时价值最高。
限制
- 写入范围限定在本次会话所在的仓库或工作目录内;在 ~/.claude/、其他仓库或工作树、用户主目录 dotfile、/etc 等系统路径创建、修改、移动或删除内容,需用户在请求中明确点名该路径;读取不受限制。
- 临时文件可用 mktemp 或 mktemp -d 在系统临时目录创建而无需用户点名,但结束前(包括提前停止时)必须全部清理;临时目录下使用固定或可预测名称不在此豁免范围。
- 当请求可能指工作目录内或外的文件时,应先询问;不得因读取某文件就推断需要写外部文件;若工作根路径解析到会话工作目录之外(绝对路径或经 .. 逃逸),应停止、打印解析后的绝对路径并请用户确认。
- 该技能不写 docstring,不写发布文档站点页面,也不判断目录是否需要上下文文档,是否启用由用户决定。
校验清单 CLAUDE.md 正文不超过 10 行;仅含防错事实;README.md 可在 2 分钟内扫读完毕且无空章节;所有文件名与目录实际文件一致;导入路径正确;环境变量名与代码实际读取一致;CLAUDE.md 中不含应属 README.md 的内容;CLAUDE.md 指向 README.md 的说明需点明具体内容。
其他细节 资料未提供该技能的收费、价格、支持平台或效果数据,暂未提供。