# Hf Context Mesh > Use when a host project (vendoring HF) wants per-directory hierarchical context (project root / mid-directory / leaf-directory) auto-generated for any AI agent reading the codebase. Generates `AGENTS.md` (OpenCode), `.​cursor/rules/*.mdc` (Cursor), or `CLAUDE.md` (Claude Code) skeletons; architect fills in conventions. Not for HF's own `docs/principles/` (untouched); not for spec / design / tasks artifacts (use upstream skills). - Skill: `tomevault-io/hf-context-mesh` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/hf-context-mesh` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/hf-context-mesh/raw - Safety review: pending (external: skill-scanner PASS, skillspector WARNING) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/hf-context-mesh --- # HF Context Mesh 宿主项目按目录层级生成 hierarchical AI agent 上下文文件的脚手架生成器。对应 OMO `/init-deep` 的等价能力，但跨三客户端： - **OpenCode** → `AGENTS.md`（被 `directoryAgentsInjector` hook 自动注入） - **Cursor** → `.​cursor/rules/.mdc`（用 `globs: /**` 做目录级触发） - **Claude Code** → `CLAUDE.md`（同目录约定文件名） 按 ADR-008 D1 / ADR-010 D3 维持三客户端可移植性：本 skill 在三客户端各自给出独立模板，互不依赖。 **HF 自身的 `docs/principles/` 永不被本 skill 触碰**（宪法层不变，按 `docs/principles/soul.md` 第 5 条）。 ## When to Use 适用： - 宿主项目（vendor HF 进自己仓库的项目）想一键生成层次化 AI agent 上下文骨架 - 项目目录树发生显著变化（新增 src/ 子模块 / 新增 docs/ 大段），需重新生成上下文骨架 - 架构师选择了客户端（OpenCode / Cursor / Claude Code / all 3），希望本 skill 生成对应模板 不适用： - HF 仓库自身的 `docs/principles/` 不动（用 ADR / soul-doc 路径而非本 skill） - 单 artifact 写作（spec / design / tasks）→ 上游 hf-* skill - 上下文已存在且无目录树变化 → 不需要重新生成 ## Hard Gates - **不替架构师写约定**：本 skill 只生成骨架（headings + 占位），具体 Conventions / Patterns / Anti-Patterns 由架构师填；按 `docs/principles/soul.md` 第 5 条 - 不修改 HF 自身 `docs/principles/`（宪法层不变） - 不修改宿主项目已有的 AGENTS.md / .mdc / CLAUDE.md（除非架构师 explicit `--force`）；冲突时先 dry-run 列出会动哪些文件 - 客户端选择必须由架构师拍板（Workflow 步骤 2）；不假设默认客户端 ## Object Contract - **Primary Object**: 宿主项目目录树下的 N 个 `AGENTS.md` / `.mdc` / `CLAUDE.md` 骨架文件 - **Frontend Input Object**: 宿主项目根路径 + 架构师选定的客户端（OpenCode / Cursor / Claude Code / all 3） - **Backend Output Object**: 1. 骨架文件落到目标目录（按客户端命名约定） 2. 文件内容是 headings + 占位段，不含具体 convention 内容 - **Object Boundaries**: - 不动 HF `docs/principles/` - 不写架构师的约定内容 - 不动宿主项目源代码 - **Object Invariants**: - 同一目录可同时存在 OpenCode / Cursor / Claude Code 三客户端文件（互不冲突） - root / mid / leaf 三层模板结构对齐（不同客户端对应同层使用同结构骨架，仅文件名 / frontmatter 不同） ## Methodology | 方法 | 落地步骤 | |---|---| | **Per-Client Template Set** | references/agents-md-template.md 内 3 套独立模板 | | **3-Layer Hierarchy (root / mid / leaf)** | Workflow 步骤 1：识别 3 类目录 | | **Skeleton-Only Generation** | Hard Gates "不替架构师写约定" | | **Architect-Driven Client Choice** | Workflow 步骤 2：询问客户端 | 详细模板：`references/agents-md-template.md`。 ## Workflow 1. **扫描宿主项目目录树** - Object: 目录列表 + 每个目录的层级分类 - Method: walk + 按规则分类（root = 项目根；mid = 含 ≥ 2 子目录或含 README.md 的中间目录；leaf = 仅含源文件无子目录） - Input: 宿主项目根路径（CLI arg / config） - Output: 目录清单 + 层级标注 - Stop / continue: 目录数 ≤ 50 → 继续；> 50 → 提示架构师选 prefix 缩范围 2. **询问架构师选定客户端** - Object: 目标客户端集合（subset of {OpenCode, Cursor, Claude Code}） - Method: 直接 prompt 架构师；不假设默认 - Input: 步骤 1 目录清单 - Output: 客户端集合 - Stop / continue: ≥ 1 客户端 → 继续；0 → 退出 3. **生成骨架文件** - Object: 每个目录 × 每个客户端 = 骨架文件 - Method: 按 `references/agents-md-template.md` 的对应客户端 + 对应层级模板填充 - Input: 步骤 1 + 步骤 2 输出 - Output: 文件落到目标目录 - Stop / continue: 文件冲突且无 `--force` → dry-run 列出冲突后退出；否则继续 4. **架构师填充 Conventions / Patterns / Anti-Patterns** - Object: 骨架占位段 - Method: 架构师手动填写（不由本 skill 代笔） - Input: 步骤 3 骨架 - Output: 完整 AGENTS.md / .mdc / CLAUDE.md 内容 - Stop / continue: Hard Gates "不替架构师写约定"——本 skill 不主动建议内容，仅在架构师询问时给"参考其它项目的常见 pattern"链接（external） ## Output Contract | 客户端 | 文件名 | 落点 | |---|---|---| | OpenCode | `AGENTS.md` | 每个识别的目录下 | | Cursor | `.​cursor/rules/.mdc` | 项目根 `.​cursor/rules/` 下，按目录 slug 命名（globs 字段指向对应目录） | | Claude Code | `CLAUDE.md` | 每个识别的目录下 | 不写 progress.md（本 skill 不在 SDD workflow 主链）；不写 review record（不是 review 节点）。 ## Red Flags - 本 skill 主动写架构师的 Conventions（违反 Hard Gates） - 触动 HF `docs/principles/` - 默认假设客户端而不询问 - 覆盖宿主项目已有的 AGENTS.md / .mdc / CLAUDE.md（应先 dry-run + 架构师 confirm `--force`） ## Common Mistakes | 错误 | 问题 | 修复 | |---|---|---| | 把 leaf 模板用到 root | root 期望项目级总览，leaf 不够 | 按目录层级严格选模板 | | 给 Cursor `.mdc` 写错 globs | rule 不会按目录触发 | globs 字段必须 `/**` | | 同时为 3 客户端生成但只填 1 份 conventions | 3 客户端用户体验不一致 | 架构师为每客户端独立填或在每个文件里 reference 同一份共享文档 | ## Common Rationalizations | 借口 | 反驳 / Hard rule | |---|---| | "架构师会嫌麻烦，我帮 ta 填几条 convention 当例子。" | Hard Gates: 不替架构师写约定；填例子 = 替 ta 决定标准，违反 soul.md 第 5 条 | | "默认客户端按宿主目录有没有 .​opencode/ 自动判断。" | Hard Gates: 客户端必须架构师拍板；目录自动识别 = 替 ta 做选择 | | "已有的 AGENTS.md 内容看起来过时，顺手覆盖。" | Hard Gates: 不覆盖已有文件除非 `--force`；先 dry-run 列出冲突让架构师决定 | | "HF 自己的 docs/principles 也是按目录的，顺便给它生成。" | Hard Gates: 永不触动 HF 自身 docs/principles/，按 soul.md 宪法层不变 | ## Reference Guide | 文件 | 用途 | |---|---| | `references/agents-md-template.md` | OpenCode / Cursor / Claude Code 三客户端各自的 root / mid / leaf 三层模板 | ## Verification - [ ] 目录树扫描完成 - [ ] 架构师已选定客户端 - [ ] 骨架文件落到对应位置（OpenCode AGENTS.md / Cursor .mdc / Claude Code CLAUDE.md） - [ ] 未填充 Conventions / Patterns / Anti-Patterns（架构师责任） - [ ] 未触动 HF docs/principles/ - [ ] 已有文件冲突时已 dry-run 列出（除非 `--force`） --- > Source: [hujianbest/garage-agent](https://github.com/hujianbest/garage-agent) — distributed by [TomeVault](https://tomevault.io).