Skip to content

AGENTS.md

Latest commit

 

History

History
120 lines (94 loc) · 4.36 KB

AGENTS.md

File metadata and controls

120 lines (94 loc) · 4.36 KB
Raw

AGENTS.md — Seven-Action Documentation Model

This file describes https://7act.org/ for AI agents, and the repository that builds it for coding agents. It is published at https://7act.org/AGENTS.md.

The Seven-Action Documentation Model is a descriptive model of user needs for technical documentation. It names seven actions a reader may want to accomplish: Appraise, Understand, Explore, Practice, Remember, Develop, and Troubleshoot. The model describes reader intent; it does not prescribe a content taxonomy.

Getting started

Every page on the site is published in four forms at the same path:

Artifact Path Media type
HTML / text/html
Markdown mirror /index.md text/markdown
Machine-readable model /model.json application/json
Agent index /llms.txt text/plain

Site-wide entry points:

  • /sitemap.md — every page, as Markdown links, grouped by section.
  • /sitemap.xml — the same set with <lastmod> dates.
  • /glossary/index.md — definitions of the seven actions and model terms.

Start with /llms.txt for orientation and /model.json when you need the model as data. Fetching / with an Accept: text/markdown request header returns the Markdown mirror instead of HTML.

Configuration

The site is available in 16 languages. English lives at the root; every other language is served under its code, and each language has its own artifacts:

https://7act.org/model.json        # English
https://7act.org/es/model.json     # Spanish
https://7act.org/ja/llms.txt       # Japanese

Language codes: en, es, fr, it, pt, de, pl, tr, ru, ja, zh-cn, ko, hi, ar, fa, ur.

All AI crawlers are welcome; robots.txt allows them explicitly. Content is CC BY 4.0, so quote and reuse it with attribution to Fabrizio Ferri Benedetti and a link to https://7act.org/.

Usage

model.json is the single source of truth. Its shape:

{
  "model": { "version": "2025-01-09", "title": "…", "description": "…" },
  "actions": [
    {
      "id": "appraise",
      "verb": "Appraise",
      "alt": "Discern",
      "definition": "…",
      "description": "…",
      "signals": ["…"],
      "examples": [{ "title": "…", "url": "…" }],
      "frameworks": { "dita": ["…"], "diataxis": ["…"], "good_docs": ["…"] },
      "metric": { "name": "…", "description": "…" }
    }
  ]
}

The seven actions, in heptagon order:

  1. Appraise (Discern) — judge the product's qualities and compare it to others.
  2. Understand (Learn) — grasp the abstractions the product is built around.
  3. Explore (Discover) — try the product with a low barrier to entry.
  4. Practice (Train) — operate the product in daily, standard use.
  5. Remember (Recall) — look up what cannot be memorized.
  6. Develop (Integrate) — extend or integrate with the product.
  7. Troubleshoot (Solve) — diagnose and resolve issues under pressure.

To apply the model to a documentation set, identify the primary action a page serves, then check whether the whole set covers all seven. An agent skill that encodes this workflow is at https://7act.org/skill/:

npx skills add theletterf/sevenactionmodel \
  --skill seven-action-documentation \
  --agent claude-code

Working on this repository

The site is Hugo (extended, pinned in .github/workflows/) deployed to Cloudflare Workers.

hugo server        # local preview
hugo --minify --gc # production build into public/

Conventions to follow when changing the repo:

  • No fact about the model may live only in a template. Verbs, definitions, signals, examples, frameworks, and metrics belong in data/<lang>/model.yaml; layouts render from there.
  • Content prose lives in content/, one file per language (rationale.md, rationale.es.md, …). UI strings live in i18n/<lang>.toml.
  • Adding a page means adding it in all 16 languages, or not at all.
  • worker.js owns HTTP behavior: canonical Link headers, charset, and Markdown content negotiation. Static output belongs in Hugo, not the worker.
  • CI runs a Hugo build, link checking with lychee, html-validate, and Vale. Keep all four green.