# Obinit > 初始化或更新软件项目的 Obsidian-backed 通用 agent 工作约定。适用于用户要求为新项目或已有仓库建立通用 agent 指令、创建或连接 Obsidian 项目笔记、创建 allowlist 范围内的 agent/doc 目录，或为 Codex、Claude Code 以及其他 coding agent 统一项目 onboarding 流程。 - Skill: `geekxtop/obinit` (Agent Skill, multi-file: 17 files) - Install (CLI): `npx skillmds@latest add geekxtop/obinit` - Raw SKILL.md: https://api.skillmd.com/api/skills/geekxtop/obinit/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: GeekXtop (https://skillmd.com/u/geekxtop) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/geekxtop/obinit --- # Obinit 把项目接入“仓库规则 + 项目内 memory + Obsidian 项目上下文”。新项目可创建完整规则源；成熟项目只加索引和 memory 协议，不替代已有 `AGENTS.md` / `CLAUDE.md`。 默认遵循用户或项目既有语言偏好。当前模板使用简体中文，fork 可替换 `templates/`、README 和 manifest 文案；路径、命令、包名和英文专有名词保持原样。 ## 运行时假设 - 仓库内写入只依赖文件系统和 `node`；`scripts/inspect-project.mjs` 需要可用的 `node`，不可用时改为手工读取入口文件和 memory 文件判断模式。 - git 可选：`inspect-project.mjs` 在非 git 目录回退到当前目录作为项目根，不报错。 - Obsidian 同步需要桌面端已打开目标 vault 且 `obsidian` CLI 可用；CLI 不可用或无法解析 vault 本地路径时，只完成仓库内文件写入，把未完成的 Obsidian 同步项列为待确认，不退回 CLI mutation。 ## 快速流程 1. 确定项目根目录：优先 git root，否则当前目录。 2. 运行或等价执行 `scripts/inspect-project.mjs` 判断模式： ```bash node /scripts/inspect-project.mjs ``` 3. 读取 `AGENTS.md`、`CLAUDE.md`、`.agents/instructions.md`、`README.md` 和 package metadata；对 `docs/` 只检查 docs 顶层信号和索引。 4. 只在 allowlist 内创建或更新：`AGENTS.md`、`CLAUDE.md`、`.agents/`、`docs/adr/`，以及 `.gitignore` 的 `.agents/scratch/` 条目。 5. 选择模板、合并已有内容、写入项目 memory。 6. 按 `references/obsidian-sync.md` 的 vault 文件写入契约创建或更新 `Agent/Projects/.md`。 7. 读回更新过的项目文件；完成后必须读回 Obsidian 项目笔记。 ## 初始化模式选择 先按 `references/init-modes.md` 处理分支和冲突。 | 模式 | 判定 | 写入 | | --- | --- | --- | | 新项目模式 | 没有非空入口指南，也没有明显项目文档 | 用完整 `.agents/instructions.md`；入口文件可薄指针 | | 成熟项目接入模式 | fork、已有项目、已有非空 `AGENTS.md` / `CLAUDE.md` / README / docs | 用索引型 `.agents/instructions.md`；保留已有指南 | | 重复运行模式 | `.agents/instructions.md`、`.agents/active.md` 或入口提示已存在 | 只补缺失文件、链接和过期表述 | 重复运行模式先按 `references/memory-upgrade.md` 逐节对比模板与现有文件，报告差异并等用户确认，不自动改写。 成熟项目接入模式下，`AGENTS.md` / `CLAUDE.md` 仍是项目/工具指南事实源。索引型 `.agents/instructions.md` 只记录 memory 协议、Obsidian 项目笔记路径、源文件链接和写入边界。 不要把 `AGENTS.md` / `CLAUDE.md` 的长内容完整复制进 `.agents/instructions.md`。 默认不递归读取 `docs/`。只列出 docs 顶层目录和读取已存在的索引文件，例如 `docs/README.md`、`docs/index.md`、`docs/adr/README.md`；设计/计划文档只读取 `.agents/active.md` 指向的具体文件或用户指定的文件，不按工具路径批量读取。 发现规则冲突、入口文件语义冲突或目录用途不一致时，停止写入冲突文件并列出待确认项；无冲突的 allowlist 文件可以继续创建。 ## 入口文件保护 处理 `AGENTS.md`、`CLAUDE.md` 前先读 `references/entry-file-policy.md`。 - 文件不存在或为空：可用 `templates/agent-entry.md` 创建。 - 已有非空入口文件只追加符合语言偏好的入口段。 - 已有等价 `.agents/instructions.md` 指针：不修改。 - 不得用 `templates/agent-entry.md` 整体替换已有非空入口文件。 - 除非用户明确说“覆盖”“重写”或指定替换文件，否则不要压缩、重排或删除已有入口内容。 ## Memory Bank 项目内 memory 规则见 `references/memory-bank.md`。 默认文件： ```text .agents/instructions.md .agents/active.md .agents/progress.md .agents/lessons.md .agents/archive/ .agents/scratch/ docs/adr/ ``` 更新时机： - 任务开始时在 `.agents/handoffs/` 创建自己的交接文件；`.agents/active.md` 是派生视图，由 `$obclose` 重建。 - 完成实质任务或复杂任务暂停时按 `$obclose` 收尾。 - 重要里程碑追加 `.agents/progress.md`。 - 可跨任务复用的坑和规则写入 `.agents/lessons.md`。 - 当状态已由权威状态载体记录时（git commit、tag、PR、CI/CD、release、artifact、ADR、migration、issue/ticket、runbook），`.agents/active.md` / `.agents/progress.md` 只记录下一次 agent 需要接手的未完成事项、不在权威载体中的决策背景、阻塞或人工确认点；不记录短暂中间态，已完成状态在最终回复说明。 - `.agents/archive/` 保存过长 `progress.md` 的历史归档，应提交；它不是临时草稿。 - 长期技术决策写入 `docs/adr/`。 - 项目内既有的设计/计划文档（无论由哪个工具生成）保留原文件，memory 只链接；obinit 不创建、不改写、不按工具路径批量读取它们。 - 临时调查草稿写入 `.agents/scratch/`；运行日志、缓存和生成物不要放进 agent memory。 ## Obsidian 同步 Obsidian 只作为跨会话上下文和公共知识入口，不作为源码、构建、测试、部署或运行时依赖。细节见 `references/obsidian-sync.md`。 - 项目笔记默认路径：`Agent/Projects/.md`。 - 公共知识默认路径：`Agent/Knowledge/`。 - 公共知识发现入口：`Agent/Knowledge/_catalog.md`。它是已沉淀公共知识的事实来源，不存在或不命中时不要凭空假设。 - 文档默认路径：`Agent/Documents/`。 - 文档目录入口：`Agent/Documents/_catalog.md`。它是人类可读文档目录和显式读取入口，只有用户明确指定、任务明确涉及文档主题，或执行 `$obdoc` / `$obcurate` 文档流程时读取。 - 重复运行时也要检查 Obsidian 项目笔记。 - Obsidian 项目笔记存在但内容过期时，按当前模式幂等更新。 - Obsidian 项目笔记的相关知识只记录真实查阅或明确相关的公共知识笔记；不要预填通用示例链接。 - Obsidian 项目笔记是干净索引，只写真实链接、真实状态和真实记录；省略空章节，不写 `暂无` 或“需要时补充”。 - `相关知识`、`决策`、`开放问题`、`常用命令` 只有有真实内容时才写入；初始化模式和 `$obinit` 接入记录写入 `当前状态` 或 `Agent 记录`，不写入决策。 - 完成后必须读回 Obsidian 项目笔记。 任务开始或遇到相关问题时，不凭空假设哪些领域已有公共知识。只有用户明确要求、`Agent/Knowledge/_catalog.md` 的 `terms` / `aliases` 命中任务关键词，或风险较高且关键词明确时，才在 `Agent/Knowledge/` 做有限关键词定向搜索；只有命中相关笔记后才明确读取并使用。读取 Knowledge catalog 命中项时看 `kind` 和 `use_as`：`kind: knowledge` / `use_as: rule`、`checklist` 或 `heuristic` 这类公共经验可以作为规则、检查清单或启发式判断。`Agent/Documents/_catalog.md` 是文档目录；只有用户明确指定、任务明确涉及文档主题，或执行文档整理时才读取。不要全量自动加载公共知识，不扫描整个 vault。 ## 项目相关知识回写 项目相关知识按 `unknown` / `candidate` / `confirmed` 三档渐进回写；判定信号、写入位置和幂等维护规则见 `references/obsidian-sync.md`。只回写链接和简短使用语义，不复制公共知识正文。 ## 模板 优先使用本 skill 的模板： | 模板 | 目标 | | --- | --- | | `templates/instructions.md` | 新项目 `.agents/instructions.md` | | `templates/instructions-index.md` | 成熟项目索引型 `.agents/instructions.md` | | `templates/agent-entry.md` | 空入口文件 | | `templates/active.md` | `.agents/active.md` | | `templates/progress.md` | `.agents/progress.md` | | `templates/lessons.md` | `.agents/lessons.md` | | `templates/agents-readme.md` | `.agents/README.md` | | `templates/adr-readme.md` | `docs/adr/README.md` | | `templates/obsidian-project-note.md` | Obsidian 项目笔记 | 如果目标文件已有非空内容，先读取并合并；只有用户明确要求替换时才整体覆盖。 ## 调用方式 常规使用： ```text $obinit ``` 或： ```text 使用 obinit 初始化当前项目。 ``` 只有偏离默认行为时才补充说明，例如指定项目名、指定 Obsidian vault、跳过 Claude 入口或允许覆盖已有文件。