skills.rest
astashov
astashovCOMMUNITY
Explore all skills by this author →
Website𝕏@anton_astashovGitHub

archdoc

Generates architecture walkthrough docs with verified file:line links for subsystems or branches.

692|107|Updated Feb 29, 2020
Search Tags:#architecture documentation#Technical Writing#api extraction#code walkthrough#Git diff#Code review#file line links
One-click install
npx skills add https://github.com/astashov/liftosaur --skill archdoc
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: archdoc
Source: https://github.com/astashov/liftosaur/tree/main/.claude/skills/archdoc
Command: npx skills add https://github.com/astashov/liftosaur --skill archdoc

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Understanding a subsystem or feature branch by reading raw implementation code is slow and error-prone, and architecture notes go stale quickly. This Skill produces a top-down markdown walkthrough doc with verified clickable file:line links, a mechanically extracted public API, invariants, and a debugging map, so reviewers can track architecture changes through doc diffs instead of reading code.

Core Features & Use Cases

  • Verified deep links: Every file:line anchor is grep-verified against the working tree before writing, so links act as a staleness alarm when code moves.
  • Mechanical API extraction: An awk-based extraction script pulls exported signatures and interfaces into a canonical Public API section instead of hand-copying.
  • Structured doc format: Produces a fixed structure — one-paragraph summary, ASCII layer stack, public API, cascade narrative, invariants, and a symptom-to-file debugging map.
  • Refresh mode: Re-verifies anchors and diffs the API extraction against an existing doc to update only what changed.
  • Use Case: After finishing a feature branch, ask for an archdoc of the branch; the Skill maps the diff, explores the call chain top-down, verifies every anchor, and writes lambda/scripts/archdocs/<feature>.md for review.

Quick Start

Generate an archdoc for the current feature branch and save it under lambda/scripts/archdocs with verified file:line links.

Frequently Asked Questions about archdoc

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I document the architecture of a feature branch?▼

Run the archdoc skill on the branch: it diffs against the merge base, explores the call chain top-down with agents, verifies every file:line anchor with grep, and writes a structured markdown walkthrough to lambda/scripts/archdocs/<name>.md.

How do I keep architecture documentation from going stale?▼

Use refresh mode: the skill re-verifies existing anchors against the working tree, re-runs the API extraction, diffs it against the Public API section, and updates only the links and sections that changed, keeping the doc diff minimal.

Why must every file:line link be grep-verified before writing?▼

Exploration agents routinely report stale or wrong line numbers after refactors. Verifying each anchor with grep ensures links land on the correct line, so a broken link later reliably signals the doc is stale.

Can archdoc output use mermaid diagrams or flowcharts?▼

No. The skill enforces text-first documentation: plain-language narrative, verbatim signatures in code blocks, and simple ASCII sketches only. Mermaid, SVG, and flow diagrams are explicitly excluded.

Where are archdoc files stored and are they committed automatically?▼

Docs are written to lambda/scripts/archdocs/<subsystem>.md, never to docs/ which is served publicly. The skill does not commit the file; the user reviews and commits it themselves.

Related Skills

Explore More Software Engineering Skills→
orbanorban
8

git-history

Analyze per-directory git history, PR descriptions, and blame data to categorize codebase insights.

Community
Basic
alexanderguyalexanderguy
4

code-review

Reviews Git branch diffs for correctness, conventions, and architecture with cited checks.

Community
Advanced
oaldersoalders
4

adversarial-review

Coordinate two reviewers to identify defects and invariant violations in code.

Community
Advanced
llmh333llmh333

manim-video

Generate animated technical explainers with Manim for graph and workflow visuals.

Community
Intermediate