documentation
Skill2 starsChanged 4 days agoMITView on GitHub
Rules and logic for creating, managing, and closing project documentation (tasks, journals, ADRs), conformant with the Open Knowledge Format (OKF v0.2). Activate this skill when creating new tasks, distilling chat sessions into journals, closing tasks, or maintaining index.md/log.md files.
118 other projects use a version of this.
Adopted by
Most recently taken up by
- arxdsilva/ai-loopstheir own version, first seen Nov 16, 2026
- AshrafDurjoy/genai-shared-patternstheir own version, first seen Nov 16, 2026
- th3r-dev/th3-skillstheir own version, first seen Nov 16, 2026
- cooneycw/claude-power-packtheir own version, first seen Nov 15, 2026
- lengrufeng2008/dsh-skill-librarytheir own version, first seen Nov 15, 2026
- scolladon/crafttheir own version, first seen Nov 15, 2026
Used with
Projects with it also use create-media-pack, project-preferences and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
DepressionCenterSkillcreate-media-pack
Create a coordinated project branding and media pack with three accessible design options, approved vector artwork, image exports, a branding guide, and README integration. Use when asked for a repository media pack, brand kit, or complete project visual identity.
Also in 5 projects that use this
DepressionCenterSkillproject-preferences
Apply repository-specific preferences when planning, implementing, or reviewing changes in this project.
Also in 6 projects that use this
thistleknotSkillresponse-style
Response and prose protocol. Use when drafting user-facing prose, expanding a user's ideas, or tuning tone and format to preserve voice, avoid AI cliches, and maintain coherent answers.
Also in 7 projects that use this
BrowserWorksSkillaccessibility-frontend-review
Performs an accessibility code review of a local diff or Phabricator revision in the style of the Firefox accessibility team. Use this skill whenever the user asks to review a Phabricator patch or revision for accessibility issues, mentions a D-number (like D284142) in the context of accessibility review, asks "does this patch have any a11y issues", or wants to check a diff against accessibility guidelines. Also use it when the user says things like "can you review this for a11y", "check this patch", or "give me an accessibility review of D[number]". Invoke proactively when the user pastes a phabricator.services.mozilla.com URL or shares a revision ID alongside any accessibility concern. Invoke when questions about the following topics are raised: aria properties, aria roles, high contrast mode, forced colors, prefers contrast, focus order, screen readers, assistive technology.
Also in 4 projects that use this
BrowserWorksSkillandroid-new-module
Guide for creating new Android gradle modules in the android-components project.
Also in 4 projects that use this
- +7 more from BrowserWorks
Other versions118 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 118
- anthropics/knowledge-work-plugins★ 36ksame name
- comet-ml/opik★ 23ksame name
- mozilla-firefox/firefox★ 14ksame name
- microsoft/fast★ 9.7ksame name
- mufeedvh/code2prompt★ 7.8ksame name
- BrowserWorks/waterfox★ 6.4ksame name
- samchon/typia★ 6ksame name
- github/gh-aw★ 5.6ksame name
- epicenter-md/epicenter★ 4.8ksame name
- EpicenterHQ/epicenter★ 4.8ksame name
108 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository2 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- documentationSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
19 rules. 0 are common, 5 are distinctive, and 14 are very specific to this project.
0
Common
Most of the 106 edited versions we read keep these.
5
Distinctive
This author's own choices. Worth a look.
14
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
When creating a new task (TASK).
- Distinctive: line 14
When distilling the essence of a chat session (JOURNAL).
- Distinctive: line 15
When closing a task (TASK-CLOSE).
- Very specific: line 16
When creating or updating a document in the _docs/ folder.
- Very specific: line 17
When updating the project overview (PROJECT-OVERVIEW), the decisions log (DECISIONS-LOG), or the bundle's index.md / log.md files.
- Very specific: line 18
When creating or syncing a module document (MODULE) via /module-sync — see §11.
- Very specific: line 19
When refreshing the task board via /board-sync — see §12.
- Distinctive: line 24
Every document (TASK, JOURNAL) filename contains a slug.
- Distinctive: line 35
Do not fill in numbering gaps.
- Very specific: line 39
If multiple Journals are created in a single day, mark the difference in the slug (e.g., -2, -continuation).
- Very specific: line 43
Every concept's frontmatter starts with the OKF-required type field — the concept's category, used by OKF-generic consumers for …
- Very specific: line 62
Every reference between concepts MUST use a standard markdown link, bundle-relative to _docs/ (leading /) — NOT the [[wikilink]] syntax:
- Very specific: line 116
Sources (OKF v0.2): If the journal references external material (docs, articles, code outside the repo), add a sources frontmatter entry …
- Very specific: line 127
If an ADR-level decision was made, update DECISIONS-LOG.md (per-entry Status: becomes accepted | deprecated | superseded).
- Very specific: line 129
Update _docs/tasks/index.md and append the corresponding log.md entry.
- Very specific: line 130
Run /board-sync so _docs/BOARD.md reflects the closed task — see §12.
- Very specific: line 131
Ensure log-like entries (log.md, journal history) are not rewritten retroactively.
- Very specific: line 145
Invariant conflicts block: If a proposed change appears to violate a documented invariant, the sync cannot complete without an explicit …
- Very specific: line 147
stale_after(default 90 days): if no full human verification has occurred within this window, the module should be treated as …
“Common” is measured: kept by at least 6 in 10 of the 106 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Documentation Workflow Skill
This skill contains the common logic and ruleset required for the project's documentation processes.
OKF conformance. The _docs/ folder is treated as an OKF v0.2-conformant knowledge bundle: every TASK / JOURNAL / ADR is a concept (one markdown file = one YAML-frontmatter + body document), cross-linked with standard markdown links, discoverable through index.md, and historized through log.md. This does not replace the existing workflow fields (status, priority, etc.) — OKF fields are added alongside them, never in place of them.
When to use this skill?
- When creating a new task (TASK).
- When distilling the essence of a chat session (JOURNAL).
- When closing a task (TASK-CLOSE).
- When creating or updating a document in the
_docs/folder. - When updating the project overview (PROJECT-OVERVIEW), the decisions log (DECISIONS-LOG), or the bundle's
index.md/log.mdfiles. - When creating or syncing a module document (MODULE) via
/module-sync— see §11. - When refreshing the task board via
/board-sync— see §12.
How to use?
1. Filename and Slug generation
Every document (TASK, JOURNAL) filename contains a slug.
- Format: 2-5 words, separated by hyphens.
- Characters: Lowercase only, without accents (e.g., á -> a, ő -> o).
- Example:
database-migration,user-auth-fix. - Full filename pattern:
TASK-NNN_slug.md/JOURNAL-YYYY-MM-DD-slug.md. Always resolve the actual filename by listing the target directory before linking to it — never guess it from the ID alone.
2. TASK numbering logic
TASK identifiers are in the format TASK-NNN.
- List the
_docs/tasks/folder. - Find the highest sequence number (NNN).
- The next number:
highest + 1(if empty:TASK-001). - Do not fill in numbering gaps.
3. JOURNAL numbering
Journals are date-based: JOURNAL-YYYY-MM-DD-slug.md.
If multiple Journals are created in a single day, mark the difference in the slug (e.g., -2, -continuation).
4. YAML Frontmatter schemas (OKF v0.2-conformant)
Every concept's frontmatter starts with the OKF-required type field — the concept's category, used by OKF-generic consumers for routing/filtering. This is distinct from the project's own status field (workflow state) and from JOURNAL's journal_type (session kind).
| Concept | type Value | Identifier Pattern | Standard Path |
| Task | Task | TASK-NNN | _docs/tasks/TASK-NNN_slug.md |
| Journal | Journal | JOURNAL-YYYY-MM-DD-slug | _docs/journal/JOURNAL-YYYY-MM-DD-slug.md |
| Module | Module | MODULE-slug | _docs/modules/MODULE-slug.md |
| Brief | Brief | BRIEF-TASK-NNN | _docs/tasks/briefs/TASK-NNN_brief.md |
| Plan | Plan | PLAN-TASK-NNN | _docs/tasks/plans/TASK-NNN_plan.md |
📖 Full schema specifications: When creating or editing frontmatter for any concept, consult references/schemas.md for the exact schema, required fields, allowed enum values, and metadata properties.
⚠️ Breaking rename note: the legacy
type: "planning"field (session kind) in journals is nowjournal_type.typeis strictly reserved for the OKF concept category (Journal). See §10 for migrating pre-existing journals.
The body's "Approach / Plan" section is a checkbox list (- [ ] step), not a numbered list — this doubles as the task's subtask tracker. /board-sync reads it verbatim to render subtask progress on _docs/BOARD.md, see §12. Check items off as work progresses; don't narrate progress elsewhere instead of checking the box.
5. Cross-linking (OKF-conformant — replaces Obsidian wikilinks)
Every reference between concepts MUST use a standard markdown link, bundle-relative to _docs/ (leading /) — NOT the [[wikilink]] syntax:
- ✅
[TASK-014](/tasks/TASK-014_add-auth.md) - ✅
[Brief](/tasks/briefs/TASK-014_brief.md) - ✅
[Plan](/tasks/plans/TASK-014_plan.md) - ✅
[ADR-003](/DECISIONS-LOG.md#adr-003) - ❌
[[TASK-014]]— Obsidian-only syntax; invisible to any generic OKF consumer (including the OKF reference visualizer), so it breaks the cross-link graph outside Obsidian.
Obsidian renders standard markdown links and still tracks them for backlinks, so this loses nothing on the Obsidian side while gaining OKF conformance elsewhere.
6. index.md maintenance (OKF reserved filename, §6 of the spec)
A directory index.md carries no frontmatter — its body is a flat link list grouped under headings. Update the relevant directory's index.md whenever a concept is added, closed, or renamed:
- New/closed TASK → update
_docs/tasks/index.md - New BRIEF → update
_docs/tasks/briefs/index.md - New PLAN → update
_docs/tasks/plans/index.md - New JOURNAL → update
_docs/journal/index.md - New/deprecated MODULE → update
_docs/modules/index.md(manually —/module-syncdoes not auto-maintain this, see §11)
The bundle root _docs/index.md is the one exception on both counts: it is generated by /project-sync (not by the task/journal commands), and it may carry a single okf_version frontmatter key. It is a file-level map — it lists tasks/, journal/, arch/, spec/, modules/ with their index.md files and the actual files inside arch//spec/, plus the root documents — because agent.md imports it with @_docs/index.md as its only route into the bundle. If you add a file that this map should mention, don't hand-edit the root index: say so and suggest /project-sync.
_docs/BOARD.md is NOT an index — it is a full-rebuild live view maintained exclusively by /board-sync, see §12.
Format (see _docs/_templates/INDEX-template.md):
# Tasks
* [TASK-014 — Add auth](TASK-014_add-auth.md) - in-progress, high priority
* [TASK-013 — Fix migration](TASK-013_fix-migration.md) - done7. log.md maintenance (OKF reserved filename, §7 of the spec)
_docs/log.md is the OKF-reserved chronological history file, separate from DECISIONS-LOG.md (which stays the detailed ADR archive). Append one line per meaningful change, newest date-group first, on every /task-new, /task-close, /journal-distill, and /arch-sync (see _docs/_templates/LOG-template.md):
## 2026-08-06
* **Creation**: Opened [TASK-014](tasks/TASK-014_add-auth.md).
* **Update**: Closed [TASK-013](tasks/TASK-013_fix-migration.md).
/agent-sync,/project-sync,/module-syncand/board-syncdo NOT append tolog.md— module documents are durable references, not dated events (a module update is recorded in the module file's own "Change log" section, see §11); a board refresh has no history at all to record, it is only ever a snapshot of "now" (see §12).
8. Distillation rules (Journal)
During /journal-distill, the following must be extracted:
- Context: Why did the conversation start? (Status description, not "the user asked").
- Options: Investigated alternatives in a table (advantage, disadvantage, decision).
- Decisions: What was finalized? ([Subject]: Rationale).
- Open Questions: What remains unanswered? (In question form).
- Next Steps: Specific actions.
- Sources (OKF v0.2): If the journal references external material (docs, articles, code outside the repo), add a
sourcesfrontmatter entry instead of a loose link, and cite it in the body with[^source-id]:
sources:
- { id: okf-spec, resource: "https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md", title: "OKF v0.2 Spec", last_modified: 2026-07-24 }9. Closing rules (Task Close)
During /task-close:
status->done,completed-> today's date.- Fill in the
Resultsection (in past tense, factually). - Fill in the "Agent summary" block at the end of the file.
- If an ADR-level decision was made, update
DECISIONS-LOG.md(per-entryStatus:becomesaccepted|deprecated|superseded). - On human approval of the close, append to
verified:{ by: "human:<username>", at: "<ISO8601>" }. An agent must never self-verify its own task — this field exists specifically to make the project's "merges are always human-approved" rule queryable, not just documented. - Update
_docs/tasks/index.mdand append the correspondinglog.mdentry. - Run
/board-syncso_docs/BOARD.mdreflects the closed task — see §12. - Ensure log-like entries (
log.md, journal history) are not rewritten retroactively. /task-closenever triggers/module-sync— module documents are only touched by explicit, manual invocation (see §11).
10. Migrating existing documents (optional, non-blocking)
Files written before this OKF pass (missing type, generated, etc.) remain fully valid — OKF conformance (§9 of the spec) requires only a non-empty type field, and consumers MUST tolerate missing optional fields. Backfill type / journal_type opportunistically when a file is next edited by an agent; do not batch-rewrite the whole corpus in one pass.
11. Module documents (MODULE) and /module-sync
_docs/modules/*.md files are a durable, code-organization layer distinct from TASK/JOURNAL: one file per logical module (e.g. Billing, Notifications), describing what it's responsible for, where it lives in the code, its cross-module dependencies, and — most importantly for an agent — its invariants (implicit rules the code doesn't enforce with an explicit error, but whose violation breaks something elsewhere).
Key rules:
- Manual only. Module files are created and updated exclusively through the explicit
/module-sync <module-name> [TASK-NNN]command (see.agents/workflows/module-sync.md). No other workflow — including/task-close— creates, updates, or references a module file automatically. - Delta, not regeneration.
/module-syncproposes section-level changes for human approval; it never rewrites a module file wholesale. The "Responsibility" and "Key decisions" sections are never agent-generated — human/ADR-sourced only. - Invariant conflicts block. If a proposed change appears to violate a documented invariant, the sync cannot complete without an explicit human decision (update the invariant, or fix the code) — this is a hard stop, the same severity class as the
verifiedgate in §9. verifiedis file-level, not delta-level. Approving a proposed delta does not mark the fileverified— only a full, deliberate review of the entire module file does, appended in the same{ by, at }shape asTASK.verified.stale_after(default 90 days): if no full human verification has occurred within this window, the module should be treated asneeds-review— checked at sync time, not enforced by a background job._docs/modules/index.mdis maintained by hand, not by/module-sync— see §6.
12. Task board (BOARD.md) and /board-sync
_docs/BOARD.md is a plaintext markdown kanban view of all TASK files — columns are the fixed task.status values (Planning → In Progress → Review → Done → Postponed), each card shows priority/complexity and the "Approach / Plan" checklist as a subtask-progress indicator.
Key rules:
- Fully generated, never hand-edited.
_docs/BOARD.mdis entirely rebuilt on every/board-syncrun, from live data in_docs/tasks/*.md— it carries no data of its own, and any manual edit to it is lost on the next sync. - No approval gate. Unlike
/module-sync,/board-syncperforms pure read+render with no interpretation or judgment — it never blocks, never asks for confirmation, and is safe to run automatically. - Automatic trigger.
/task-newand/task-closeboth run/board-syncas a closing step (see §9 step 7). It is also callable manually at any time — e.g. after only checking a subtask box without otherwise touching status. - Subtask source. The "Approach / Plan" checkbox list (§4) is read verbatim — same text, same checked state — never summarized.
- Stale flag. A task with
status: in-progresswhoseupdatedis more than 14 days old gets a⚠ stalemarker on its card — informational only, never blocking. - No history.
BOARD.mdreflects only the current moment; it is not appended tolog.md(see §7) and carries no changelog of its own.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

