agentleFS
jsmastery-projsmastery-pro/jsm-hq/.agents/skills/document/SKILL.md

document

Skill102 starsChanged 33 days agoMITView on GitHub

Generate documentation from what was actually built and decided. Three modes: PR description and changelog for a single feature, developer-facing docs as a proper linked folder structure, or user-facing docs. Detects which modes are relevant before offering them. Optional — run when documentation is actually needed, not after every feature.

54 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use develop, scope and 7 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.
  • hong9LeeSkill

    develop

    빌드, 아키텍처, git 관련 작업 시 OMS MSA 공통 인프라 규칙을 적용한다. 기술 스택, 빌드 명령, 헥사고날 아키텍처 구조, git 워크플로우, AI Context 동기화 규칙을 다룬다. 코드 작성 컨벤션은 /convention, 테스트 컨벤션은 /test-guide 스킬을 참조.

    Also in 5 projects that use this

  • YuriNachosSkill

    scope

    Configure claude-scope status line widgets for Claude Code. Use when user wants to customize widgets, change theme, reorder elements, or modify display style.

    Also in 5 projects that use this

  • ralphkraussSkill

    resolve-conflicts

    Resolve git merge conflicts or re-apply changes from a stale branch onto current main. Use when user says "resolve conflicts", "merge conflicts", "rebase branch", "branch is behind", "re-apply changes", "port branch", or a branch is too far behind main to merge cleanly.

    Also in 3 projects that use this

  • MicrosoftSkill

    sync

    Sync the current session branch with its upstream branch, or publish the current session branch to a remote. Use when the user asks to sync a branch, pull latest changes, rebase onto upstream, push current branch, publish branch, or set upstream.

    Also in 5 projects that use this

  • kt057Skill

    check

    lint, typecheck, test を一括実行して結果をサマリーする

    Also in 7 projects that use this

  • Microsoft AzureSkill

    test

    Also in 12 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

27 rules. 0 are common, 19 are distinctive, and 8 are very specific to this project.

  • 0

    Common

    Most of the 50 edited versions we read keep these.

  • 19

    Distinctive

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before doing anything else, check for the minimum required context.

    line 30
  2. Distinctive:

    If none of these exist:

    line 38
  3. Distinctive:

    Stop completely. Do not proceed.

    line 53
  4. Distinctive:

    If at least one source exists, continue to Step 1.

    line 55
  5. Very specific:

    If the developer specified a mode directly — /document pr, /document dev, or /document user — skip to that mode's section.

    line 61
  6. Distinctive:

    If no mode was specified, figure out which modes are relevant before asking.

    line 63
  7. Very specific:

    Read context/mvp.md if it exists.

    line 67
  8. Very specific:

    If context/mvp.md does not exist, ask:

    line 73
  9. Distinctive:

    If user docs are not relevant:

    line 83
  10. Distinctive:

    If user docs are relevant:

    line 96
  11. Distinctive:

    Wait for the developer's choice before proceeding.

    line 105
  12. Distinctive:

    Ask if not obvious:

    line 115
  13. Very specific:

    Read only context/dev-log/[feature-concern].md for this feature — the most recent entry only.

    line 123
  14. Distinctive:

    If no dev-log exists for this feature:

    line 125
  15. Distinctive:

    Ask where to save it:

    line 159
  16. Distinctive:

    Write one entry, plain language, one sentence:

    line 165
  17. Distinctive:

    Read in this order:

    line 182
  18. Very specific:

    Check whether README.md and a docs/ folder already exist.

    line 192
  19. Distinctive:

    Before finalising, list anything that could not be filled from the available context:

    line 290
  20. Distinctive:

    Only after confirmation do any files get written.

    line 319
  21. Very specific:

    Read context/mvp.md — product description, user, features that shipped.

    line 329
  22. Very specific:

    Do not include anything from context/architecture.md.

    line 331
  23. Very specific:

    If a feature is listed in context/mvp.md but not confirmed as shipped in the dev-logs — do not document it as available.

    line 356
  24. Distinctive:

    Add a link to the user guide from README.md if it is not already there.

    line 360
  25. Distinctive:

    It does not run on empty projects: If no project context exists, it stops immediately and tells the developer what to do first.

    line 370
  26. Distinctive:

    It does not invent: Every line in the output comes from what was captured in context files and dev-logs.

    line 374
  27. Distinctive:

    It does not overwrite existing accurate docs: If README.md already exists and is accurate, it proposes additions — not a replacement.

    line 376

“Common” is measured: kept by at least 6 in 10 of the 50 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

Project Context File

This skill reads the project context file. The name depends on your tool:

  • Claude Code → CLAUDE.md
  • Cursor → .cursor/rules/rules.md
  • Codex → AGENTS.md
  • Windsurf → .windsurfrules
  • Other tools → check your tool's documentation

Throughout this skill, "project context file" refers to whichever file your tool uses.


Good documentation explains what exists to someone who was not there when it was built. It is never one long page — it is a folder of focused files, each with a single job, linked from a root README so a developer can find exactly what they need in seconds.

This skill writes from what was actually built and decided. It does not invent. If something was not captured, the documentation says so rather than guessing.


Step 0 — Check That Something Exists

Before doing anything else, check for the minimum required context.

Look for:

  • The project context file
  • context/architecture.md
  • context/mvp.md
  • Any files in context/dev-log/

If none of these exist:

There is no project context to document yet.

To generate documentation, I need at least one of:
- A project context file (CLAUDE.md or equivalent)
- context/architecture.md — for developer docs
- context/mvp.md — for product or user docs
- context/dev-log/ entries — for PR descriptions

Run /architect on a new project or /audit on an
existing one first, then come back to /document.

Stop completely. Do not proceed.

If at least one source exists, continue to Step 1.


Step 1 — Determine the Mode

If the developer specified a mode directly — /document pr, /document dev, or /document user — skip to that mode's section.

If no mode was specified, figure out which modes are relevant before asking.

Check whether user docs make sense

Read context/mvp.md if it exists. Look at the User field and product description.

User docs are relevant when the product has someone who needs to learn how to operate it — a SaaS tool, an app with features to discover, a CLI, a library with an API.

User docs are not relevant when the product has no real operator — a portfolio site, a personal tool, a static page, anything where there is no external user.

If context/mvp.md does not exist, ask:

Does this project have end users who need documentation
on how to use it — or is it a personal project,
portfolio, or internal tool?

Present only the modes that make sense

If user docs are not relevant:

This looks like [reasoning]. User documentation does not
apply here, but you can ask for it directly any time.

What I can generate:
- PR description / changelog — for a specific feature
- Developer docs — README + linked docs/ folder

Which do you need?

If user docs are relevant:

What kind of documentation do you need?
- PR description / changelog — for a specific feature
- Developer docs — README + linked docs/ folder
- User docs — how to use the product

Wait for the developer's choice before proceeding.


Mode: PR

For a single feature, scoped tightly. Use after a feature is built and ready to merge.

Step PR-1 — Identify the feature

Ask if not obvious:

Which feature is this PR for?

Step PR-2 — Read the relevant dev-log

Read only context/dev-log/[feature-concern].md for this feature — the most recent entry only. Do not read other dev-logs.

If no dev-log exists for this feature:

I don't see a dev-log entry for this feature.
The PR description will be limited to what I can
infer from the conversation. Run /remember save
after future features to capture more detail.

Continue with what is available.

Step PR-3 — Write the PR description

This goes into a GitHub PR form — it is one block of text, not a file in the repo.

## What This Does
[One to two sentences — what changed and why, in plain terms]

## Changes
- [Specific file or area changed]
- [Specific file or area changed]

## Why
[The reasoning, pulled from decisions made during the
session — not invented, only what was captured]

## Testing
[How this was verified, if captured in the dev-log.
If not captured: "Not yet verified — needs manual testing"]

Step PR-4 — Write the changelog entry

Ask where to save it:

Save changelog entry to docs/changelog.md or CHANGELOG.md?

Write one entry, plain language, one sentence:

## [Date] — [Feature Name]
[One sentence for someone scanning a list of changes]

Mode: Developer Docs

For documentation aimed at another developer joining, extending, or maintaining the project.

Production developer documentation is never one page. It is a docs/ folder with focused files, each with a single job, linked from README.md. A developer landing on the repo reads the README in 30 seconds and follows the link to exactly what they need.

Step DEV-1 — Gather source material

Read in this order:

  • The project context file — stack, commands, rules
  • context/architecture.md — technical decisions and reasoning
  • context/mvp.md — what the product is, if it exists
  • context/dev-log/ — scan all files for what has been built

Note anything unclear or missing as a gap. Do not invent.

Step DEV-2 — Check what already exists

Check whether README.md and a docs/ folder already exist.

If neither exists: you are creating from scratch. Generate the full structure.

If README.md exists: propose additions or updates to it, not a replacement. Show the developer what would change before touching anything.

If docs/ folder exists: generate only the files that are missing or need updating. Do not regenerate files that are already accurate.

Step DEV-3 — Generate the docs/ structure

Produce the following files. Each is short, focused, and linked from README.

README.md — the front door. Never more than one screen of content.

# [Project Name]

[One paragraph — what this is, who it's for, what problem it solves]

## Quick Start

\`\`\`bash
[install and run commands from the project context file]
\`\`\`

## Documentation

- [Architecture](docs/architecture.md) — how the system is built and why
- [Getting Started](docs/getting-started.md) — full setup guide
- [Contributing](docs/contributing.md) — conventions and PR process
- [Changelog](docs/changelog.md) — what changed and when

docs/getting-started.md — full setup from zero.

# Getting Started

## Prerequisites
[What needs to be installed before this project]

## Installation
[Step by step — clone, install dependencies, environment setup]

## Running the project
[Dev, build, test commands — pulled from project context file]

## Common issues
[Anything captured in dev-logs as a recurring problem]

docs/architecture.md — technical decisions and reasoning.

# Architecture

## Overview
[How the system is structured — pulled from context/architecture.md]

## Stack
[Every layer with the reason it was chosen for this project]

## Project Structure
[Folder layout and what lives where]

## Key Decisions
[The decisions that shaped the codebase — from context/architecture.md]

## What Was Not Chosen
[Alternatives considered and why they were rejected]

docs/contributing.md — how to contribute.

# Contributing

## Conventions
[From context/architecture.md's Conventions section]

## Making changes
[Branch naming, commit style, PR process if defined]

## Running tests
[Test command from project context file]

docs/changelog.md — running list of what changed.

# Changelog

## [Date] — [Feature]
[One sentence summary]

Step DEV-4 — Flag gaps honestly

Before finalising, list anything that could not be filled from the available context:

Generated docs/ structure. The following sections could
not be fully populated from existing context:

- [Section]: [what is missing and why]
- [Section]: [what is missing and why]

These are marked as gaps in the files. Fill them in
manually or run /remember save after future sessions
to capture more detail.

Step DEV-5 — Confirm before writing anything

Show the list of files that will be created or updated. Wait for confirmation.

Ready to write:
- README.md [created / updated]
- docs/getting-started.md [created]
- docs/architecture.md [created]
- docs/contributing.md [created]
- docs/changelog.md [created]

Write these files?

Only after confirmation do any files get written.


Mode: User Docs

For documentation aimed at someone using the finished product, not building it.

Step USER-1 — Gather source material

Read context/mvp.md — product description, user, features that shipped. Read dev-logs only to confirm what is actually built and working.

Do not include anything from context/architecture.md. A user does not need to know what database was chosen.

Step USER-2 — Write docs/user-guide.md

# [Product Name] — User Guide

[One or two sentences — what this does and who it's for.
Plain language, no jargon]

## Getting Started
[How a user begins — sign up, install, open the app]

## Features

### [Feature Name]
[What it does and how to use it, in plain language]

### [Feature Name]
[What it does and how to use it, in plain language]

## Getting Help
[Where to go for support, if applicable]

If a feature is listed in context/mvp.md but not confirmed as shipped in the dev-logs — do not document it as available. Mark it as coming soon or omit it.

Step USER-3 — Update README.md

Add a link to the user guide from README.md if it is not already there. Show the proposed addition before writing it.

Step USER-4 — Confirm before writing

Show what will be written. Wait for confirmation before touching any file.


What This Skill Does Not Do

It does not run on empty projects. If no project context exists, it stops immediately and tells the developer what to do first.

It does not produce one big file. Developer documentation is always a docs/ folder with linked files. A single 300-line markdown file is not documentation — it is a document that will become outdated and ignored.

It does not invent. Every line in the output comes from what was captured in context files and dev-logs. Gaps are flagged, not filled.

It does not overwrite existing accurate docs. If README.md already exists and is accurate, it proposes additions — not a replacement.

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.