---
name: project-docs
description: Use when entering an unfamiliar project, when creating or repairing a project's agent docs (AGENTS.md, feature map, lat.md folder map, VISION.md, ES.md), or when the workspace check reports doc problems.
title: project-docs
canonical_url: https://skilld.dev/gh/masihmoafi/skills/project-docs
last_updated: 2026-11-03T09:01:25.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install masihmoafi/skills/project-docs`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/project-docs`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/masihmoafi/skills/project-docs) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/project-docs`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/project-docs --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/project-docs --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Project docs

Each fact about a project has one home. Read in this order: `AGENTS.md` (loaded already), `ES.md`, then the feature file for the task. Use the folder map before you add a file and `VISION.md` when scope is in question. A README supplements these files; it never replaces them.

## One file per job

| File | Holds | Limit |
| --- | --- | --- |
| `AGENTS.md` (+ `CLAUDE.md` = `@AGENTS.md`) | `## Start here` (pointers), `## Common mistakes` (this project's lessons), `## Rules` | 60 lines |
| `ES.md`, title "(updated YYYY-MM-DD)" | `## Now`, `## Next`, `## Broken`, `## Open decisions` | 40 lines |
| `VISION.md` | identity in one line, `## Thesis`, `## Non-goals` | 25 lines |
| `lat.md/workspace.md` | every top-level item and why it exists | — |
| `.agents/skills/verify-<app>/features/` | one file per user-facing feature: how to reach it, drive it, its code, its gotchas; made by `create-verification-skill`, kept true by `maintain-verification-skill` | — |
| `reports/`, commit messages | evidence: hashes, run IDs, verification prose | — |

A workspace check can enforce the limits and headings (here: `findability/check_pointers.py`). These files are local notes: keep them out of public git and link them into new worktrees.

## What goes in AGENTS.md

It loads into every session, so each line must apply to every task there (HumanLayer, *Writing a Good CLAUDE.md*; Anthropic, *Steering Claude Code*).

- Yes: what the project is, how to build, test and verify it, where things live (as pointers), and rules that hold for every task.
- No: procedures (a skill), task-specific notes (the feature file), state (`ES.md`), copies of global rules (the user-level instructions), code style (a linter).
- A "never do X" that agents keep breaking needs a check or hook; the line in `AGENTS.md` is not enough.
- A common mistake is one dated line: what went wrong, the rule, and its guard (or "No guard").

## What goes in ES.md

- `## Now`: what is true today, in up to five lines. Each line states a fact; its proof goes to `reports/`.
- `## Next`: the user's open requests, newest date first, one line each, starting `Feature:`, `Fix:`, `Remove:` or `Keep:`. Delete a line only when the user has seen it working. When the log outgrows the file, it moves to a local `REQUESTS.md` beside `ES.md` (same line format), and `## Next` keeps the user's ranked items and a link.
- `## Broken` and `## Open decisions`: one line each; a decision names who decides.
- Rewrite the file in place; never append a progress log.

## Keep them true

- Change a fact in its home only; elsewhere, point to it.
- When a doc contradicts the code or another doc, check the code, fix or delete the wrong text, and say what changed.
- Before you delete old text, move each lesson or prohibition that is still valid to a feature's gotchas or to `AGENTS.md`.
- Add a harness part (`init.sh`, a rubric, a lint) only for a workflow that repeats, and only the smallest that fixes the bottleneck. If you are not sure it is still needed, remove it and keep the simpler setup if quality holds.

## Create the layout when absent

Inspect the project two levels deep, draft the missing files in the shape above, and show the user `VISION.md` before you save it. Exemplar: this library's `VISION.md`.
