Doc

Project docs — create & query

Every doc under docs/ carries its status in YAML front matter at the very top of the file. That front matter is the single source of truth — there is no central index/JSON to keep in sync. "What's done?" is answered by scanning the front matter live (see Query). This skill writes that front matter when creating a doc, and reads it when querying.

docs/README.md is the human-facing wiki for the folder: it explains the organization and holds a generated index table between <!-- BEGIN docs-index --> / <!-- END docs-index --> markers. That table is a derived view, not a source of truth — regenerate it from front matter (see Maintain the wiki index); never hand-edit the rows.

Front matter schema

---
title: <free text — the human title>
status: draft        # see vocabulary below
type: design         # design | rfc | marketing
created: 2026-06-28  # YYYY-MM-DD, only the day the doc was first written
updated: 2026-06-28  # YYYY-MM-DD, bump on every meaningful edit
related:             # optional — sibling filenames (YYYYMMDD- prefix under design/)
  - 20260719-vibe-island-status.md
---

• status vocabulary (a doc moves down this list over its life):
  • draft — being written, nothing committed to.
  • in-review — content complete, awaiting sign-off.
  • approved — signed off, not yet built.
  • active — currently being executed / lived against (e.g. a strategy memo).
  • done — fully delivered; kept for reference.
  • archived — superseded or abandoned; ignore for planning.
• type is just a label on the doc; it does not dictate a subdirectory. The set is small on purpose; add a new type only when a doc genuinely doesn't fit.
• Keys are English (tooling/Obsidian compatibility); values may be Chinese where natural (e.g. a Chinese title). Quote any value containing : # [ ].

Create a doc

All docs live somewhere under docs/. The skill does not impose a per-type folder layout — place the file under docs/ (or whichever existing docs/ subfolder the user points at), and let type in the front matter, not the path, carry the category.

1. Ask the user for the title and type if not already clear from the request. Default status: draft. Set both created and updated to today.
2. Pick a kebab-case filename derived from the title (ASCII slug; for a Chinese title, ask for or invent a short English slug — keep the Chinese in title). Put it under docs/ unless the user names a subfolder.
3. Write the file: front matter block first, then a single # <H1> title, then a one-line > blockquote stating the doc's goal. Do not pad with boilerplate sections — let the content grow naturally.
4. Regenerate the wiki index (see below) so docs/README.md reflects the new doc.
5. Tell the user the path you created.

Also regenerate the index whenever a doc's status/title/type changes, not only on create — the table is otherwise stale.

Update a doc

Use this skill for any edit to an existing doc, not just creation — editing its body, advancing its status, renaming it, or changing its type. The point is to keep the front matter honest and the wiki in sync after every change.

1. Make the requested edit to the doc body and/or front matter.
2. Bump updated to today on any meaningful change (the whole point of the field). Leave created alone.
3. If the user is advancing the doc's lifecycle, move status along the line draft → in-review → approved → active → done → archived — don't skip to a value that doesn't match reality.
4. If you changed status/title/type, regenerate the wiki index (see Maintain the wiki index) so docs/README.md matches.
5. Report what changed (path, old → new status if it moved).

Note: markdownlint's MD025 may warn "multiple top-level headings" because it treats the front matter title: as an H1. It's a false positive for front-matter docs and renders fine everywhere; ignore it (or the repo can set MD025: { front_matter_title: "" } in .markdownlint.json).