markdown-frontmatter
Use when adding, fixing, or validating YAML frontmatter on managed Markdown governed by the project-standards Markdown Frontmatter Standard; covers structure, field values, id generation, and validation.
- License 许可
- MIT
- 最近更新
- 2026-10-07
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- markdown-frontmatter
- license
- MIT
- metadata
- { "author": "Chris Purcell", "version": "1.4" }
- description
- Use when adding, fixing, or validating YAML frontmatter on managed Markdown governed by the project-standards Markdown Frontmatter Standard; covers structure, field values, id generation, and validation.
- compatibility
- Claude Code and Codex CLI
02 资源文件 2
- 参考文档agents/openai.yaml158 B
- 脚本scripts/new-doc-id6.7 KB
03 SKILL.md 正文
Markdown Frontmatter
Overview
Author and fix YAML frontmatter for managed Markdown documents under the project-standards Markdown Frontmatter Standard.
This skill ships with the standard package and is installed repo-local at .agents/skills/markdown-frontmatter when a repository adopts the standard. That path is deliberate: both Claude Code and Codex CLI can discover it without a global skill owner.
Core principle: the schema is authoritative, not this file. The machine contract is markdown-frontmatter.schema.json in project-standards, enforced by project-standards validate. This skill is the operating layer for the rules agents get wrong most often. On any conflict, the schema and current standard pages win.
When to use
- Creating or editing a managed Markdown file (typically
README.md,docs/**/*.md). - A
project-standards validate,validate-frontmatter, orformat-frontmatter --checkrun failed and you need to fix the block. - Deciding which
doc_type/status/ other controlled value to set.
When NOT to use: files that must NEVER carry frontmatter. Agent-instruction and agent-skill files are harness config, not managed documents: CLAUDE.md, AGENTS.md, and anything under .claude/, .agents/, .codex/. That includes this installed skill at .agents/skills/markdown-frontmatter. Exclude those paths through the package's exclude option in .standards/config.toml instead of adding metadata. A repo may also exclude its root README.md if it prefers no metadata table on its landing page.
Required fields (the eleven)
Every managed document opens with a --- fenced YAML block carrying at least these, in this order:
---
schema_version: '1.1'
id: 'note-xxxxxx-human-title'
title: 'Human Title'
description: 'One-sentence description of the document.'
doc_type: 'note'
status: 'draft'
created: 'YYYY-MM-DD'
updated: 'YYYY-MM-DD'
tags: []
aliases: []
related: []
---
For most docs, add the standard-profile optionals after updated in canonical order: reviewed (date|null), owner (stable person/team/role), consumer (enum), then after related: source (array), confidence (enum), visibility (enum), license (string|null). Relationship fields are optional, used only when needed: supersedes, superseded_by, depends_on, applies_to.
Formatting rules that actually fail validation
These are the machine-checked rules an agent skips by habit:
-
Quote every string, including dates.
created: '2026-06-07', nevercreated: 2026-06-07. -
Identifier-like numbers are strings.
schema_version: '1.1', not1.1. -
Non-empty lists use block style (
- 'item'per line); empty lists use[]. No duplicate items. -
No unknown top-level fields. A stray
version:ortype:is rejected. Project- or tool-specific keys go under thepublish,project, orx_projectextension objects only. -
Canonical key order when keys are present:
schema_version, id, title, description, doc_type, status, created, updated, reviewed, owner, consumer, tags, aliases, related, supersedes, superseded_by, depends_on, applies_to, source, confidence, visibility, license, publish, project, x_project
Controlled values
These fields accept only these values (the schema is the source of truth):
| Field | Allowed values |
|---|---|
doc_type |
index, note, concept, reference, runbook, spec, plan, adr, decision, research, template, log, prompt, schema |
status |
draft, active, review, deprecated, archived, superseded, stub |
confidence |
high, medium, low, unknown |
visibility |
private, internal, public |
consumer |
user, agent, mix, unknown |
README.mdandindex.md→doc_type: 'index'. Files underdocs/research/→doc_type: 'research'.stubis a status, never adoc_type. Usedoc_type, nevertype.- Canonical global tags include
frontmatter,metadata,standard,validation,infrastructure,it, andnetwork; repos may add documented local tags when the global set is insufficient.
The id field — standard-enforced format
This is a standard rule, not a local addition.
markdown-frontmatter@1.8enforces the id format below viavalidate-id(run byproject-standards validateand the V5 CI workflow). An id whose leading segment is not a validdoc_typefails validation withprefix '<x>' is not a valid doc_type. Earlier repo-name-prefixed ids no longer pass.
{doc_type}-{base36-6}-{document-name}
The doc_type (one of the controlled values above), then a random 6-character base36 token, then a readable document slug, all lower kebab-case (e.g. runbook-0f943i-restart-netbox-after-config-change). The token keeps the id globally unique; the slug is frozen at creation and does not change when the title is edited.
Generate the id with the script. Never invent the token yourself. An LLM asked for a "random" base36 token produces low-entropy, collision-prone strings and reuses tokens already in context, defeating the uniqueness goal. scripts/ is this skill's own directory (invoke by absolute path if your cwd is elsewhere):
scripts/new-doc-id <document-name> # bare id, doc_type 'note'
scripts/new-doc-id --doc-type runbook <document-name> # bare id, 'runbook' prefix
scripts/new-doc-id --scaffold --doc-type runbook <name> # full canonical frontmatter block
The --doc-type value becomes both the id prefix and (in --scaffold) the doc_type field, so the two always agree; it defaults to note. --doc-type and --status must be standard-controlled values. --scaffold emits the eleven required fields in canonical order with today's date correctly quoted. Replace the REPLACE: description placeholder before committing.
ADRs are the exception: follow the standard's ADR id form (adr-{NNNN}-{repo-name}-{title}, e.g. adr-0001-homelab-use-postgresql-for-persistent-storage), not the doc_type-prefixed format. Do not use the script for ADR ids.
Worked example (compliant standard profile)
---
schema_version: '1.1'
id: 'runbook-0f943i-restart-netbox-after-config-change'
title: 'Restart netbox after config change'
description: 'Procedure to safely reload netbox after editing its configuration.'
doc_type: 'runbook'
status: 'active'
created: '2026-03-10'
updated: '2026-06-07'
reviewed: '2026-06-07'
owner: 'platform-team'
consumer: 'user'
tags:
- 'infrastructure'
- 'network'
- 'operations'
- 'runbook'
aliases:
- 'netbox-restart'
related:
- 'docs/architecture.md'
source: []
confidence: 'high'
visibility: 'internal'
license: null
---
# Restart netbox after config change
...document body...
Validate
Compliance = project-standards validate exits 0. Run it from the repository root:
project-standards validate
That command runs schema validation, ID-format validation, and reference validation. Exit codes: 0 all matched files valid (or none matched); 1 one or more documents failed; 2 config/schema error.
Use the formatter check for canonical quote style, key order, and list layout:
format-frontmatter --check
To check or repair a single file's id: validate-id <file> (add --fix to rewrite an invalid id through the platform executor).
Common mistakes
| Mistake | Fix |
|---|---|
type: instead of doc_type: |
Rename; type is not a field. |
Unquoted date created: 2026-06-07 |
Quote it: '2026-06-07'. |
doc_type: 'readme' for a README |
README/index → doc_type: 'index'. |
Extra top-level key (version:, category:) |
Move under project:/x_project:, or drop it. |
Frontmatter added to CLAUDE.md / .claude/** / .agents/** |
Remove it; add the path to the package exclude option. |
Omitting required arrays (tags/aliases/related) |
Always present; empty = []. |
doc_type: 'stub' |
stub is a status, not a doc_type. |
Authoritative references
- Standard README — overview and adoption surface.
- Structure Requirements — hard fields, key order, scalar/list rules, IDs, and validation.
- Field Values — lifecycle, ownership, canonical tags, aliases, relationships, sources, and extensions.
- Adoption guide — unified config, CI workflow, repo-local skill install, and compliance procedure.
standards/markdown-frontmatter/versions/1.8/schemas/markdown-frontmatter.schema.json(in project-standards) — the selected package contract; wins on any conflict.
04 同仓库更多 Skills
project-toolbox
Use when running a periodic repository housekeeping sweep or checking whether the repository's actual state still matches what its standards, configuration, and documentation claim; routes to the packaged Project Toolbox workflow documents.
project-toolbox
Use when running a periodic repository housekeeping sweep or checking whether the repository's actual state still matches what its standards, configuration, and documentation claim; routes to the packaged Project Toolbox workflow documents.
markdown-frontmatter
Use when adding, fixing, or validating YAML frontmatter on managed Markdown governed by the project-standards Markdown Frontmatter Standard; covers structure, field values, id generation, and validation.
markdown-frontmatter
Use when adding, fixing, or validating YAML frontmatter on managed Markdown governed by the project-standards Markdown Frontmatter Standard; covers structure, field values, id generation, and validation.
markdown-frontmatter
Use when adding, fixing, or validating YAML frontmatter on managed Markdown governed by the project-standards Markdown Frontmatter Standard; covers structure, field values, id generation, and validation.
markdown-frontmatter
Use when adding, fixing, or validating YAML frontmatter on managed Markdown governed by the project-standards Markdown Frontmatter Standard; covers structure, field values, id generation, and validation.