agentleFS
dynamicartdynamicart/ai-docs/.agents/skills/documentation/SKILL.md

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

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.
  • DepressionCenterSkill

    create-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

  • DepressionCenterSkill

    project-preferences

    Apply repository-specific preferences when planning, implementing, or reviewing changes in this project.

    Also in 6 projects that use this

  • thistleknotSkill

    response-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

  • BrowserWorksSkill

    accessibility-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

  • BrowserWorksSkill

    android-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

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
  1. Distinctive:

    When creating a new task (TASK).

    line 13
  2. Distinctive:

    When distilling the essence of a chat session (JOURNAL).

    line 14
  3. Distinctive:

    When closing a task (TASK-CLOSE).

    line 15
  4. Very specific:

    When creating or updating a document in the _docs/ folder.

    line 16
  5. Very specific:

    When updating the project overview (PROJECT-OVERVIEW), the decisions log (DECISIONS-LOG), or the bundle's index.md / log.md files.

    line 17
  6. Very specific:

    When creating or syncing a module document (MODULE) via /module-sync — see §11.

    line 18
  7. Very specific:

    When refreshing the task board via /board-sync — see §12.

    line 19
  8. Distinctive:

    Every document (TASK, JOURNAL) filename contains a slug.

    line 24
  9. Distinctive:

    Do not fill in numbering gaps.

    line 35
  10. Very specific:

    If multiple Journals are created in a single day, mark the difference in the slug (e.g., -2, -continuation).

    line 39
  11. Very specific:

    Every concept's frontmatter starts with the OKF-required type field — the concept's category, used by OKF-generic consumers for …

    line 43
  12. Very specific:

    Every reference between concepts MUST use a standard markdown link, bundle-relative to _docs/ (leading /) — NOT the [[wikilink]] syntax:

    line 62
  13. Very specific:

    Sources (OKF v0.2): If the journal references external material (docs, articles, code outside the repo), add a sources frontmatter entry …

    line 116
  14. Very specific:

    If an ADR-level decision was made, update DECISIONS-LOG.md (per-entry Status: becomes accepted | deprecated | superseded).

    line 127
  15. Very specific:

    Update _docs/tasks/index.md and append the corresponding log.md entry.

    line 129
  16. Very specific:

    Run /board-sync so _docs/BOARD.md reflects the closed task — see §12.

    line 130
  17. Very specific:

    Ensure log-like entries (log.md, journal history) are not rewritten retroactively.

    line 131
  18. Very specific:

    Invariant conflicts block: If a proposed change appears to violate a documented invariant, the sync cannot complete without an explicit …

    line 145
  19. Very specific:

    stale_after (default 90 days): if no full human verification has occurred within this window, the module should be treated as …

    line 147

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.md files.
  • 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.

  1. List the _docs/tasks/ folder.
  2. Find the highest sequence number (NNN).
  3. The next number: highest + 1 (if empty: TASK-001).
  4. 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).

Concepttype ValueIdentifier PatternStandard Path
TaskTaskTASK-NNN_docs/tasks/TASK-NNN_slug.md
JournalJournalJOURNAL-YYYY-MM-DD-slug_docs/journal/JOURNAL-YYYY-MM-DD-slug.md
ModuleModuleMODULE-slug_docs/modules/MODULE-slug.md
BriefBriefBRIEF-TASK-NNN_docs/tasks/briefs/TASK-NNN_brief.md
PlanPlanPLAN-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 now journal_type. type is 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-sync does 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) - done

7. 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-sync and /board-sync do NOT append to log.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 sources frontmatter 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:

  1. status -> done, completed -> today's date.
  2. Fill in the Result section (in past tense, factually).
  3. Fill in the "Agent summary" block at the end of the file.
  4. If an ADR-level decision was made, update DECISIONS-LOG.md (per-entry Status: becomes accepted | deprecated | superseded).
  5. 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.
  6. Update _docs/tasks/index.md and append the corresponding log.md entry.
  7. Run /board-sync so _docs/BOARD.md reflects the closed task — see §12.
  8. Ensure log-like entries (log.md, journal history) are not rewritten retroactively.
  9. /task-close never 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-sync proposes 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 verified gate in §9.
  • verified is file-level, not delta-level. Approving a proposed delta does not mark the file verified — only a full, deliberate review of the entire module file does, appended in the same { by, at } shape as TASK.verified.
  • stale_after (default 90 days): if no full human verification has occurred within this window, the module should be treated as needs-review — checked at sync time, not enforced by a background job.
  • _docs/modules/index.md is 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.md is entirely rebuilt on every /board-sync run, 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-sync performs pure read+render with no interpretation or judgment — it never blocks, never asks for confirmation, and is safe to run automatically.
  • Automatic trigger. /task-new and /task-close both run /board-sync as 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-progress whose updated is more than 14 days old gets a ⚠ stale marker on its card — informational only, never blocking.
  • No history. BOARD.md reflects only the current moment; it is not appended to log.md (see §7) and carries no changelog of its own.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.