An AI-agent-ready framework for generating, maintaining, and validating product documentation — from specs, designs, analytics, and implementation code.
It gives your team (and your agents) a consistent, hierarchical knowledge base that humans can read top-down and AI agents can navigate progressively, without burning context on the entire repo.
AI agents: start at
setup.md. That file is the one-shot onboarding guide for configuring this framework into a target docs repository.
Docs are organized Product Area → Product Section → Feature. Every product section follows the same hierarchy, for example: overview → definitions → access → data → features → widgets/actions, with templates in _templates/ enforcing the shape of each file. Each product area has its own area.json — machine-readable config listing its wired repos, Slack owners, and agent-diffing rules (see skeleton/product-area-starter/area.json).
The structure is designed for gradual reveal: an agent (or a person) reads the root overview.md first (product-area map), drills into an area's overview.md (product sections), then a section's overview.md, then the relevant feature — only loading detail files (tracking.md, apis.md, individual widget docs) when needed. This keeps agent context small and answers grounded.
See examples/product/taskflow/ for a fully documented fictional product area showing the structure end-to-end.
Optional CI in skeleton/optional/ci/ runs an agent on a schedule (GitHub Actions or GitLab CI) that:
- Diffs recent commits across your wired repositories (frontend, backend, data).
- Updates the affected docs in place using the
docs-from-codeskill. - Appends entries to each product section's
CHANGELOG.md. - Posts a digest of changes to Slack via
scripts/notify-slack-changelog.shand surfaces open questions vianotify-slack-issues.sh. - Optionally publishes a filtered public docs branch via
publish-docs-branch.sh.
The framework ships agent skills (in skeleton/agents/cursor/.cursor/skills/, shared with Claude) covering the full loop:
| Skill | Use For |
|---|---|
writing-stories |
Brainstorming features, drafting user stories and tickets, planning changes — grounded in the existing docs as context. |
verifying-requirements |
Reviewing a story/spec/ticket for gaps, contradictions, missing info, and open questions before implementation. |
updating-product-docs |
Adding or restructuring docs from any source — specs, UI, code, designs. |
docs-from-code |
Generating or auditing docs by exploring code across multiple repos. Powers the daily CI updates. |
acceptance-check |
Validating that a PR/branch implementation actually matches its spec or ticket. |
writing-skills, writing-rules |
Authoring and validating new agent skills and rules in this repo. |
Together these let an agent brainstorm a feature against the existing product context, harden the spec, write the code, and then verify the implementation against the spec — all using the same documentation source of truth.
- Read
setup.md. - Ask the user the setup questions in Step 1.
- Copy and adapt files from
skeleton/per Steps 2–6. - After setup, give the user an example prompt for documenting their first real feature (Step 10) — setup only scaffolds empty structure, not actual product content.
- Fork or copy this repository.
- Open it in your AI agent and say:
Read setup.md and walk me through the setup. - Answer the questions; let the agent generate your configured docs repo.
- Commit the result as your documentation baseline.
- Use the agent's example prompt to start documenting real features one user-facing surface at a time — attach any design docs, specs, or slides you have for extra context.
| Path | Purpose |
|---|---|
setup.md |
One-shot onboarding guide for AI agents. Start here. |
skeleton/base/ |
Files copied into every configured docs repo: README.md, root overview.md (product-area map), .docsignore, .gitignore, _templates/. |
skeleton/agents/ |
Agent payloads for Cursor and Claude (rules + skills). |
skeleton/optional/ |
Optional CI (including a GitLab CI/CD variables reference sheet), MCPs, and browser-verification modules. |
skeleton/product-area-starter/ |
Starter product area (overview.md + area.json) copied for each product area during setup. |
skeleton/product-section-starter/ |
Starter product section, copied inside a product area during setup. |
skeleton/sample-templates/ |
Compact filled examples for every template type. |
examples/product/taskflow/ |
Full fictional TaskFlow product area — a complete reference of what a filled-out docs tree looks like. |
skeleton/ is operational (copied during setup). examples/ is educational (reference only).
Each product section is a hierarchy rooted at an overview.md, with conventional files for definitions, access, data, features, widgets, and actions. The exact shape is configurable per project — see _templates/ for the canonical templates and examples/product/taskflow/ for a worked example.
- Read the relevant template before writing or updating a doc.
- Keep product docs user-facing: behavior, access, metrics, limitations, APIs. Exclude private implementation details.
- For docs-from-code work, verify behavior across multiple layers before changing docs.
- Propagate changes up the hierarchy: feature → feature index → product overview → metrics, definitions, access, tracking, APIs, changelog.
- Stop and ask when sources conflict or required repositories/tools are missing.
- CI (GitLab):
skeleton/optional/ci/— scheduled agent updates, changelog Slack posts, public docs publishing. - MCPs:
skeleton/optional/mcps/— Figma and Mixpanel companion rules +.cursor/mcp.jsonsnippets.
Created and maintained by Ronen Yacobi at Similarweb. See AUTHORS for the full list of contributors.
The writing-skills skill (and supporting files in skeleton/agents/cursor/.cursor/skills/writing-skills/) is derived from the writing-skills skill in obra/superpowers by Jesse Vincent, used under the MIT License and substantially modified. See LICENSE for the upstream copyright and permission notice.
MIT. See LICENSE.