docs-vault

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

docs-vault

文档库（docs-vault）

Build a

docs/

Obsidian vault that's both an Obsidian vault (graph view, backlinks, color-coded tags) and a flat GitHub-readable index. Pair it with a

DESIGN.md

that follows the google-labs-code/design.md spec so the design system becomes machine-readable.

TRIGGER when: bootstrapping documentation on a Tailwind-based web project (Next.js / Remix / TanStack Start / Vite + React), introducing a flat top-level domain-doc pattern over an existing tangle of docs, or making the design system machine-readable for agents.

Stack assumed. TypeScript + Tailwind (v3 or v4). The DESIGN.md token derivation uses
tailwind.config.{ts,js}
(v3) or the
@theme
block in
app.css
(v4). Patterns transfer to non-Tailwind projects but the derivation step changes. Framework can be Next.js, Remix, Vite, TanStack Start, etc., the structure here is framework-agnostic.

Notation.
<project>
,
docs/
,
tailwind.config.{ts,js}
,
app.css
,
<NNNN>
are placeholders. Resolve to the project's actual project name, root, Tailwind config location, and ADR numbering scheme. Frontmatter examples (
aliases
,
tags
) follow Obsidian conventions, adjust to whatever tag taxonomy your team prefers.

Precedence. Project rules (CLAUDE.md / AGENTS.md / contributing guide) win. This skill produces those files for projects that don't have them; if they already exist, extend rather than replace.

Scope. Skill is about how to write the docs and which docs. The content of any given doc is the project's own; this skill provides the structure, the read order, the link conventions, and the DESIGN.md template.

构建一个

docs/

目录下的Obsidian库，它既是一个Obsidian库（支持图谱视图、反向链接、彩色标签），又是一个适合GitHub阅读的扁平化索引。同时搭配一份遵循google-labs-code/design.md规范的

DESIGN.md

，让设计系统具备机器可读性。

触发场景：在基于Tailwind的Web项目（Next.js / Remix / TanStack Start / Vite + React）中初始化文档、将现有杂乱的文档重构为扁平化顶级领域文档模式，或是让设计系统对Agent具备机器可读性。

预设技术栈：TypeScript + Tailwind（v3或v4版本）。DESIGN.md中的令牌推导使用
tailwind.config.{ts,js}
（v3版本）或
app.css
中的
@theme
块（v4版本）。该模式可迁移至非Tailwind项目，但令牌推导步骤需调整。框架可以是Next.js、Remix、Vite、TanStack Start等，本文档结构与框架无关。

占位符说明：
<project>
、
docs/
、
tailwind.config.{ts,js}
、
app.css
、
<NNNN>
均为占位符，需替换为项目实际的名称、根目录、Tailwind配置文件路径以及ADR编号规则。Frontmatter示例（
aliases
、
tags
）遵循Obsidian约定，可根据团队偏好的标签分类进行调整。

优先级规则：项目自有规则（CLAUDE.md / AGENTS.md / 贡献指南）优先级最高。如果项目尚未拥有这些文件，本技能会生成它们；若已存在，则进行扩展而非替换。

范围说明：本技能关注的是「如何撰写文档」以及「需要哪些文档」。具体文档的内容由项目自身决定；本技能仅提供文档结构、阅读顺序、链接约定以及DESIGN.md模板。

Outputs

输出成果

When this skill finishes, the repo has:

CLAUDE.md                       single pointer (3 lines, points at AGENTS.md)
AGENTS.md                       primary entry for any AI agent
docs/
├── .obsidian/                  vault config (committed)
│   ├── app.json
│   ├── core-plugins.json
│   ├── community-plugins.json
│   ├── graph.json              color groups by tag
│   ├── appearance.json
│   └── bookmarks.json
├── Home.md                     Obsidian MOC (alias: Vault Home)
├── README.md                   GitHub folder index (mermaid map)
│
├── PRODUCT.md                  ┐
├── RUNTIME.md                  │
├── ARCHITECTURE.md             │  Flat top-level domain docs.
├── DATA.md                     │  Each is a short summary (~50-150 lines)
├── AUTH.md                     │  that links into the deeper folder content.
├── ENGINEERING.md              │
├── TESTING.md                  │
├── DESIGN.md                   ┘  ← spec-compliant (google-labs-code/design.md)
│
├── architecture/               deeper specs per domain
├── conventions/                rules per layer (TS, Tailwind, fetchers, ...)
├── workflows/                  step recipes (new-domain, diagnose-bug, ...)
├── quality/                    perf, a11y, SEO, sec, design polish
├── decisions/                  ADRs (lazy)
└── upgrades/                   gap analysis vs skill defaults

完成本技能后，仓库将包含以下内容：

CLAUDE.md                       单指向文件（3行内容，指向AGENTS.md）
AGENTS.md                       AI Agent的主入口文档
docs/
├── .obsidian/                  库配置文件（需提交至仓库）
│   ├── app.json
│   ├── core-plugins.json
│   ├── community-plugins.json
│   ├── graph.json              按标签分组的颜色配置
│   ├── appearance.json
│   └── bookmarks.json
├── Home.md                     Obsidian的MOC文件（别名：Vault Home）
├── README.md                   GitHub文件夹索引（包含Mermaid图谱）
│
├── PRODUCT.md                  ┐
├── RUNTIME.md                  │
├── ARCHITECTURE.md             │  扁平化顶级领域文档
├── DATA.md                     │  每份文档为简短概述（约50-150行）
├── AUTH.md                     │  链接至更深层的文件夹内容
├── ENGINEERING.md              │
├── TESTING.md                  │
├── DESIGN.md                   ┘  ← 符合google-labs-code/design.md规范
│
├── architecture/               各领域的深度规范文档
├── conventions/                各层级规则（TS、Tailwind、数据获取器等）
├── workflows/                  步骤指南（新增领域、排查Bug等）
├── quality/                    性能、无障碍、SEO、安全、设计优化相关内容
├── decisions/                  架构决策记录（ADR）
└── upgrades/                   与技能默认标准的差距分析

Workflow

工作流程

1. Sweep the codebase (read, don't write yet)

1. 扫描代码库（仅读取，暂不写入）

Before writing a single doc, read enough to map the project:

Routes, list the pages/routes; identify public vs authed surfaces.

Stack,

package.json

(framework + key deps),

tsconfig.json

tailwind.config.{ts,js}

@theme

block,

prisma/schema.prisma

if any DB.

Entry points,
```
_app.tsx
```
/
```
app/layout.tsx
```
/
```
main.tsx
```
(providers, global CSS).
Components, top-level
```
src/components/
```
layout (atoms/molecules/organisms or flat).

Data layer,

src/server/

src/queries/

src/hooks/

src/schemas/

src/utils/fetcher.ts

(or equivalents).

CI / tooling,
```
.github/workflows/
```
,
```
.husky/
```
, eslint/prettier configs.
Existing docs,
```
README.md
```
, anything in
```
docs/
```
. Don't overwrite. If they exist, extend.

Use Glob + Grep + Read in parallel. Don't open every file, open enough to fill out PRODUCT/RUNTIME/ARCHITECTURE.

在撰写任何文档之前，需充分读取代码库以梳理项目情况：

路由：列出页面/路由；区分公共页面与需授权页面。
技术栈：查看
```
package.json
```
（框架及核心依赖）、
```
tsconfig.json
```
、
```
tailwind.config.{ts,js}
```
或
```
@theme
```
块、若有数据库则查看
```
prisma/schema.prisma
```
。
入口文件：
```
_app.tsx
```
/
```
app/layout.tsx
```
/
```
main.tsx
```
（提供者、全局CSS）。
组件：顶级
```
src/components/
```
的结构（原子/分子/有机体模式或扁平化结构）。

数据层：

src/server/

、

src/queries/

、

src/hooks/

、

src/schemas/

、

src/utils/fetcher.ts

（或等效文件）。

CI/工具链：
```
.github/workflows/
```
、
```
.husky/
```
、eslint/prettier配置文件。
现有文档：
```
README.md
```
、
```
docs/
```
目录下的所有内容。请勿覆盖，若已存在则进行扩展。

可并行使用Glob + Grep + Read工具。无需打开所有文件，只需读取足够内容以完善PRODUCT/RUNTIME/ARCHITECTURE文档。

2. Create vault config

2. 创建库配置

Drop

.obsidian/

into

docs/

so opening the folder in Obsidian works immediately. Templates: see VAULT-STRUCTURE.md §Vault config.

Required:

app.json

(sets

useMarkdownLinks: false

so wikilinks are the default),

core-plugins.json

(graph/backlinks/tag-pane on),

graph.json

(color groups by tag).

将

.obsidian/

目录放入

docs/

，确保打开该文件夹即可直接使用Obsidian。模板可参考VAULT-STRUCTURE.md中的「Vault配置」章节。

必填配置：

app.json

（设置

useMarkdownLinks: false

，使维基链接成为默认链接方式）、

core-plugins.json

（开启图谱/反向链接/标签面板）、

graph.json

（按标签分组的颜色配置）。

3. Write the eight top-level domain docs (flat)

3. 撰写8份扁平化顶级领域文档

Order, and what each must cover:

File	Covers	Lines target
`PRODUCT.md`	Audiences (roles), surfaces (routes), domain glossary, revenue model, open questions	60-120
`RUNTIME.md`	Stack, services, env vars, local setup, all `npm` / `pnpm` / `bun` commands, deploy target	80-150
`ARCHITECTURE.md`	Code layout tree, canonical data flow, state boundaries (server cache vs UI state)	50-100
`DATA.md`	DB choice, ORM, validation lib, query cache, layers, naming conventions	70-150
`AUTH.md`	Auth lib, session shape, role gating, server vs client read patterns	40-80
`ENGINEERING.md`	Daily commands, lint/format rules, TS config, Husky, Git/PR style, CI	60-110
`TESTING.md`	Test runner, co-location, behavior-over-impl, mocking guidance, coverage	50-90
`DESIGN.md`	Spec-compliant. See DESIGN-MD-TEMPLATE.md.	200-400

Frontmatter on every file:

yaml

---
aliases: [Display Name, Alternative Name]
tags: [moc, architecture]   # see tag list below
---

Each top-level file is a summary that links into deeper folder content. Don't duplicate, link. The

architecture/data-layer.md

deep doc may be 200 lines;

DATA.md

is 100 lines and points at it.

Read order goes in
Home.md
and
AGENTS.md
: PRODUCT → RUNTIME → ARCHITECTURE → DATA → AUTH → ENGINEERING → TESTING → DESIGN.

撰写顺序及每份文档需覆盖的内容：

文件	覆盖范围	目标行数
`PRODUCT.md`	受众（角色）、页面（路由）、领域术语表、盈利模式、待解决问题	60-120
`RUNTIME.md`	技术栈、服务、环境变量、本地搭建步骤、所有 `npm` / `pnpm` / `bun` 命令、部署目标	80-150
`ARCHITECTURE.md`	代码结构树、标准数据流、状态边界（服务器缓存与UI状态）	50-100
`DATA.md`	数据库选择、ORM、验证库、查询缓存、层级、命名约定	70-150
`AUTH.md`	认证库、会话结构、角色权限、服务器与客户端读取模式	40-80
`ENGINEERING.md`	日常命令、 lint/格式化规则、TS配置、Husky、Git/PR规范、CI流程	60-110
`TESTING.md`	测试运行器、代码共置、行为优先于实现、模拟指导、覆盖率	50-90
`DESIGN.md`	符合规范，参考DESIGN-MD-TEMPLATE.md	200-400

每份文件的Frontmatter：

yaml

---
aliases: [显示名称, 备选名称]
tags: [moc, architecture]   # 参考下方标签列表
---

每份顶级文档均为概述文档，需链接至更深层的文件夹内容。请勿重复内容，仅需链接。例如

architecture/data-layer.md

深度文档可能有200行，而

DATA.md

只需100行并指向该深度文档。

阅读顺序需在
Home.md
和
AGENTS.md
中明确： PRODUCT → RUNTIME → ARCHITECTURE → DATA → AUTH → ENGINEERING → TESTING → DESIGN。

4. Write folder docs (deeper specs)

4. 撰写文件夹级深度规范文档

Folders + tag mapping:

Folder	Tag	Up-link target(s)
`architecture/`	`#architecture`	`[[ARCHITECTURE]]` (+ `[[DATA]]` , `[[AUTH]]` , `[[RUNTIME]]` per topic)
`conventions/`	`#convention`	`[[ENGINEERING]]` , `[[DESIGN]]` , `[[DATA]]` , `[[TESTING]]` per topic
`workflows/`	`#workflow`	`[[ENGINEERING]]` + the topic top-level ( `[[DATA]]` , `[[DESIGN]]` , `[[TESTING]]` )
`quality/`	`#quality`	`[[DESIGN]]` , `[[RUNTIME]]` , `[[ENGINEERING]]` per topic
`decisions/`	`#adr`	`[[ENGINEERING]]` · `[[ARCHITECTURE]]`
`upgrades/`	`#upgrade`	Multi (the doc lists the relevant tiers)

Per-file scaffolds (overview, conventions, workflows, quality, decisions, upgrades): see VAULT-STRUCTURE.md.

文件夹与标签映射：

文件夹	标签	向上链接目标
`architecture/`	`#architecture`	`[[ARCHITECTURE]]` （根据主题还可链接 `[[DATA]]` 、 `[[AUTH]]` 、 `[[RUNTIME]]` ）
`conventions/`	`#convention`	`[[ENGINEERING]]` 、 `[[DESIGN]]` 、 `[[DATA]]` 、 `[[TESTING]]` （根据主题）
`workflows/`	`#workflow`	`[[ENGINEERING]]` + 对应主题的顶级文档（ `[[DATA]]` 、 `[[DESIGN]]` 、 `[[TESTING]]` ）
`quality/`	`#quality`	`[[DESIGN]]` 、 `[[RUNTIME]]` 、 `[[ENGINEERING]]` （根据主题）
`decisions/`	`#adr`	`[[ENGINEERING]]` · `[[ARCHITECTURE]]`
`upgrades/`	`#upgrade`	多目标（文档中列出相关层级）

单文件模板（概述、约定、工作流程、质量、决策、升级）：参考VAULT-STRUCTURE.md。

5. Wire bidirectional links

5. 设置双向链接

For Obsidian's graph + backlinks panel to work well:

Wikilinks
[[file]]
for in-vault navigation. Obsidian resolves by basename; aliases let you target by display name.
External markdown links for files outside the vault (
```
../AGENTS.md
```
,
```
../package.json
```
).
Every folder doc has a
↑ up-link
in its See also section pointing to its parent top-level file:

markdown

undefined

为确保Obsidian的图谱和反向链接面板正常工作：

使用维基链接
[[file]]
进行库内导航。Obsidian通过文件名解析链接；别名可让你按显示名称定位文件。
使用外部Markdown链接 指向库外文件（如
```
../AGENTS.md
```
、
```
../package.json
```
）。
每份文件夹级文档的「另请参阅」部分需包含
↑ 向上链接
，指向其对应的顶级父文档：

markdown

undefined

另请参阅

↑ [[DATA]] · [[ENGINEERING]]
(peer wikilinks)
↩ [[overview]] (or [[Home]])


- **Every top-level domain doc has a See also** linking to its deep docs and to peer top-levels.

↑ [[DATA]] · [[ENGINEERING]]
（同级维基链接）
↩ [[overview]] （或[[Home]]）


- **每份顶级领域文档的「另请参阅」部分需链接至其深度文档及同级顶级文档**。

6. Write the spec-compliant

DESIGN.md

6. 撰写符合规范的

DESIGN.md

Follow DESIGN-MD-TEMPLATE.md. Hard requirements:

YAML frontmatter with the canonical token schema (
```
colors
```
,
```
typography
```
,
```
rounded
```
,
```
spacing
```
,
```
components
```
).
Token values derived from
tailwind.config.{ts,js}
or
```
@theme
```
(v4), not invented. The template explains the derivation step-by-step.
Sections in canonical order: Overview → Colors → Typography → Layout → Elevation & Depth → Shapes → Components → Do's and Don'ts.
primary
must pass WCAG AA contrast against
on-primary
(4.5:1). If the brand color is too light/dark, introduce a
```
primary
```
/
```
primary-container
```
split (Material-style).
Component definitions reference tokens via
```
{colors.primary}
```
,
```
{rounded.lg}
```
,
```
{typography.label-md}
```
. No hex values inside the
```
components:
```
block except for
```
transparent
```
and
```
rgba(...)
```
.

Lint clean,

npx @google/design.md lint docs/DESIGN.md

reports

0 errors, 0 warnings

Obsidian frontmatter (
aliases
,
tags
) lives alongside spec keys, the YAML parser accepts unknown keys.

遵循DESIGN-MD-TEMPLATE.md。硬性要求：

YAML Frontmatter 需包含标准令牌 schema（
```
colors
```
、
```
typography
```
、
```
rounded
```
、
```
spacing
```
、
```
components
```
）。
令牌值需源自
tailwind.config.{ts,js}
或
@theme
（v4版本），不得自行编造。模板中详细说明了推导步骤。
章节需按标准顺序排列：概述 → 颜色 → 排版 → 布局 → 层级与深度 → 形状 → 组件 → 注意事项。
primary
颜色与
on-primary
颜色的对比度需符合WCAG AA标准（4.5:1）。若品牌色过亮或过暗，可采用Material风格的
```
primary
```
/
```
primary-container
```
拆分方案。
组件定义需通过
{colors.primary}
、
{rounded.lg}
、
{typography.label-md}
引用令牌。
```
components:
```
块内除
```
transparent
```
和
```
rgba(...)
```
外，不得使用十六进制颜色值。

通过Lint检查：执行

npx @google/design.md lint docs/DESIGN.md

需返回

0 errors, 0 warnings

。

Obsidian Frontmatter（
aliases
、
tags
）需与规范字段共存，YAML解析器支持未知字段。

7. Refresh entry files

7. 更新入口文件

After the vault exists, update / create:

CLAUDE.md
at repo root, 3-line pointer to
```
AGENTS.md
```
and
```
docs/README.md
```
.
AGENTS.md
at repo root, entry for any agent. Read-order table + non-negotiables + skill discipline (point at
```
skills-lock.json
```
if applicable; do NOT maintain a separate skills index in the vault, it creates SKILL graph noise).
docs/README.md
, GitHub-facing folder index with a mermaid graph and the folder map.
docs/Home.md
, Obsidian MOC (alias
```
Vault Home
```
). Top section lists all 8 top-level docs with a one-line description each.
docs/.obsidian/bookmarks.json
, pin Home + 3-4 most-touched files (PRODUCT, ARCHITECTURE, DESIGN, "Immediate upgrades" if you wrote one).

库创建完成后，更新/创建以下文件：

仓库根目录的
CLAUDE.md
：3行内容，指向
```
AGENTS.md
```
和
```
docs/README.md
```
。
仓库根目录的
AGENTS.md
：AI Agent的入口文档。包含阅读顺序表格、不可协商规则、技能规范（若适用则指向
```
skills-lock.json
```
；请勿在库内维护单独的技能索引，否则会产生SKILL图谱噪音）。
docs/README.md
：面向GitHub的文件夹索引，包含Mermaid图谱和文件夹结构。
docs/Home.md
：Obsidian的MOC文件（别名
```
Vault Home
```
）。顶部列出所有8份顶级文档及各自的一行描述。
docs/.obsidian/bookmarks.json
：固定Home + 3-4个最常用文件（PRODUCT、ARCHITECTURE、DESIGN、若撰写了「即时升级」文档则包含该文档）。

Tag set (drives Obsidian graph color groups)

标签集（驱动Obsidian图谱颜色分组）

#moc          , index / map-of-content files (Home, README, top-level domain docs)
#architecture , architecture/* + ARCHITECTURE.md
#convention   , conventions/* + ENGINEERING.md
#workflow     , workflows/*
#quality      , quality/* + DESIGN.md (also #moc)
#adr          , decisions/*
#upgrade      , upgrades/*

graph.json

(provided in VAULT-STRUCTURE.md) maps each tag to a color group.

#moc          , 索引/内容地图文件（Home、README、顶级领域文档）
#architecture , architecture/* + ARCHITECTURE.md
#convention   , conventions/* + ENGINEERING.md
#workflow     , workflows/*
#quality      , quality/* + DESIGN.md（同时标记#moc）
#adr          , decisions/*
#upgrade      , upgrades/*

graph.json

（参考VAULT-STRUCTURE.md）将每个标签映射至对应的颜色组。

Hard rules

硬性规则

Never put SKILL.md backlinks (
```
🌐 Live skill: [name](.../SKILL.md)
```
) in vault docs, every link to a
```
SKILL.md
```
becomes a "SKILL" node in the graph view, clustering visual noise. Reference skills as plain code-fenced text (
```
`zod-prisma-tanstack`
```
) and point readers at
```
skills-lock.json
```
once at the top level.
Never maintain a parallel skills index inside the vault.
```
skills-lock.json
```
is the inventory. The relevant skill name is mentioned inline in the doc that distills it.
Never invent token values for
```
DESIGN.md
```
, derive from
```
tailwind.config.{ts,js}
```
/
```
@theme
```
and call out drift in prose.
Never skip the
```
↑ up-link
```
in folder docs, the graph becomes one-directional and the backlinks panel becomes the only path back up.
Never use
```
transition: all
```
,
```
text-
```
ad-hoc sizes, or hardcoded brand hexes outside
```
tailwind.config
```
, flag in the DESIGN.md "Do's and Don'ts" so agents reading the file produce code that matches.
Never read
```
.env
```
/
```
.env.local
```
while writing docs. Read
```
.env.example
```
and ask the user for live values.

禁止在库文档中添加SKILL.md反向链接（如
```
🌐 Live skill: [name](.../SKILL.md)
```
），每个指向
```
SKILL.md
```
的链接都会在图谱视图中生成一个「SKILL」节点，造成视觉噪音。仅需使用代码块形式引用技能（
```
`zod-prisma-tanstack`
```
），并在顶级文档中一次指向
```
skills-lock.json
```
即可。
禁止在库内维护并行的技能索引。
```
skills-lock.json
```
为技能清单。相关技能名称需在提炼该技能的文档中内联提及。
禁止为
```
DESIGN.md
```
编造令牌值，需从
```
tailwind.config.{ts,js}
```
/
```
@theme
```
推导，并在正文中标注偏差。
禁止省略文件夹级文档中的
```
↑ 向上链接
```
，否则图谱会变成单向，反向链接面板将成为唯一的返回路径。
禁止使用
```
transition: all
```
、临时
```
text-
```
尺寸或硬编码品牌十六进制颜色值（
```
tailwind.config
```
除外），需在DESIGN.md的「注意事项」中标记，确保阅读该文档的Agent生成的代码符合规范。
禁止在撰写文档时读取
```
.env
```
/
```
.env.local
```
文件。请读取
```
.env.example
```
并向用户询问实际值。

Anti-patterns

反模式

❌ A single 1000-line
```
docs/INDEX.md
```
with everything inline. Split into the 8 top-level domain files; each links into its folder.
❌ Top-level docs that duplicate folder content. Top-level summarizes; folder doc is the deep spec.
❌ Folder docs that don't link up to their top-level parent (graph becomes one-directional).
❌ DESIGN.md that defines tokens but no components, every color token should be referenced by at least one component (the linter flags orphans).
❌ DESIGN.md
```
primary
```
with white text but contrast < 4.5:1, split into
```
primary
```
(action) and
```
primary-container
```
(soft surface) so the brand color survives both contexts.
❌ Wikilinks pointing to ambiguous basenames (e.g. multiple
```
README.md
```
files). Use frontmatter aliases (
```
Vault Home
```
,
```
Skills Index
```
) and reference by alias.
❌ Markdown links to
```
.agents/skills/<name>/SKILL.md
```
from inside the vault. Plain code-fenced reference only.
❌ Inventing typography levels not present in the project. If the project hasn't codified a typography scale, define one in DESIGN.md based on the dominant atoms and call it out as "newly codified" in prose.

❌ 将所有内容内联到单个1000行的
```
docs/INDEX.md
```
中。需拆分为8份顶级领域文档，每份链接至对应的文件夹内容。
❌ 顶级文档重复文件夹内容。顶级文档应为概述，文件夹文档为深度规范。
❌ 文件夹文档未链接至对应的顶级父文档（图谱变为单向）。
❌ DESIGN.md仅定义令牌但未定义组件，每个颜色令牌至少需被一个组件引用（Lint工具会标记孤立令牌）。
❌ DESIGN.md中
```
primary
```
颜色搭配白色文本但对比度<4.5:1，需拆分为
```
primary
```
（操作按钮）和
```
primary-container
```
（柔和背景），使品牌色可在两种场景下使用。
❌ 维基链接指向模糊的文件名（如多个
```
README.md
```
文件）。需使用Frontmatter别名（如
```
Vault Home
```
、
```
Skills Index
```
）并通过别名引用。
❌ 在库内使用Markdown链接指向
```
.agents/skills/<name>/SKILL.md
```
。仅允许使用代码块形式引用。
❌ 定义项目中不存在的排版层级。若项目未规范排版比例，需基于主要原子组件在DESIGN.md中定义，并在正文中标注为「新规范」。

Checklist (before declaring done)

检查清单（完成前确认）

docs/.obsidian/

committed with at least

app.json

core-plugins.json

graph.json

bookmarks.json

```
docs/Home.md
```
exists with
```
aliases: [Vault Home]
```
and lists all 8 top-level docs
```
docs/README.md
```
exists with a mermaid graph + folder map (GitHub-renderable)
All 8 top-level docs exist with frontmatter (
```
aliases
```
,
```
tags
```
)
Every folder doc has a
```
↑ up-link
```
in its See also section
No
```
🌐 Live skill: [...](.../SKILL.md)
```
links anywhere in the vault

npx @google/design.md lint docs/DESIGN.md

→

0 errors, 0 warnings

```
CLAUDE.md
```
and
```
AGENTS.md
```
exist at repo root and point at the vault
Read order is documented in both
```
Home.md
```
and
```
AGENTS.md
```
Tags applied consistently per the tag set table

docs/.obsidian/

已提交至仓库，至少包含

app.json

、

core-plugins.json

、

graph.json

、

bookmarks.json

```
docs/Home.md
```
已存在，包含
```
aliases: [Vault Home]
```
并列出所有8份顶级文档
```
docs/README.md
```
已存在，包含Mermaid图谱 + 文件夹结构（可在GitHub渲染）
所有8份顶级文档已存在，且包含Frontmatter（
```
aliases
```
、
```
tags
```
）
每份文件夹级文档的「另请参阅」部分包含
```
↑ 向上链接
```
库内无任何
```
🌐 Live skill: [...](.../SKILL.md)
```
链接

npx @google/design.md lint docs/DESIGN.md

0 errors, 0 warnings

仓库根目录存在
```
CLAUDE.md
```
和
```
AGENTS.md
```
，且指向该库
阅读顺序已在
```
Home.md
```
和
```
AGENTS.md
```
中记录
标签已根据标签集表格统一应用

Reference files

参考文件

VAULT-STRUCTURE.md, full file inventory + per-file scaffolds (
```
.obsidian/*.json
```
, top-level templates, folder doc templates)
DESIGN-MD-TEMPLATE.md, Tailwind-focused DESIGN.md template + step-by-step token derivation from
```
tailwind.config.{ts,js}
```
/
```
@theme
```

VAULT-STRUCTURE.md：完整文件清单 + 单文件模板（
```
.obsidian/*.json
```
、顶级文档模板、文件夹文档模板）
DESIGN-MD-TEMPLATE.md：基于Tailwind的DESIGN.md模板 + 从
```
tailwind.config.{ts,js}
```
/
```
@theme
```
推导令牌的分步指南

docs-vault

Original

Translation

docs-vault

文档库（docs-vault）

Outputs

输出成果

Workflow

工作流程

1. Sweep the codebase (read, don't write yet)

1. 扫描代码库（仅读取，暂不写入）

2. Create vault config

2. 创建库配置

3. Write the eight top-level domain docs (flat)

3. 撰写8份扁平化顶级领域文档

4. Write folder docs (deeper specs)

4. 撰写文件夹级深度规范文档

5. Wire bidirectional links

5. 设置双向链接

See also

另请参阅

6. Write the spec-compliant
`DESIGN.md`

6. 撰写符合规范的
`DESIGN.md`

7. Refresh entry files

7. 更新入口文件

Tag set (drives Obsidian graph color groups)

标签集（驱动Obsidian图谱颜色分组）

Hard rules

硬性规则

Anti-patterns

反模式

Checklist (before declaring done)

检查清单（完成前确认）

Reference files

参考文件

docs-vault

Original

Translation

docs-vault

文档库（docs-vault）

Outputs

输出成果

Workflow

工作流程

1. Sweep the codebase (read, don't write yet)

1. 扫描代码库（仅读取，暂不写入）

2. Create vault config

2. 创建库配置

3. Write the eight top-level domain docs (flat)

3. 撰写8份扁平化顶级领域文档

4. Write folder docs (deeper specs)

4. 撰写文件夹级深度规范文档

5. Wire bidirectional links

5. 设置双向链接

See also

另请参阅

6. Write the spec-compliant DESIGN.md

6. 撰写符合规范的DESIGN.md

7. Refresh entry files

7. 更新入口文件

Tag set (drives Obsidian graph color groups)

标签集（驱动Obsidian图谱颜色分组）

Hard rules

硬性规则

Anti-patterns

反模式

Checklist (before declaring done)

检查清单（完成前确认）

Reference files

参考文件

6. Write the spec-compliant
`DESIGN.md`

6. 撰写符合规范的
`DESIGN.md`