Builds a knowledge graph of a codebase and writes README and API reference docs grounded in real routes, types, and architecture.
- GitHub stars
- 705
- Files
- 9
- Last commit
- Oct 17, 2026
- License
- MIT
- Allowed tools
- —
What does the docs-from-code skill do?
docs-from-code builds a knowledge graph of a codebase and writes README and API reference docs grounded in real routes, types, and architecture.
Summary generated from the skill's SKILL.md.
About the docs-from-code skill
Writing README and API reference pages from an actual codebase is what docs-from-code handles. It is aimed at developers whose documentation is missing or stale and who want an agent to produce accurate text without inventing routes or functions. The skill first builds a knowledge graph of the project, then drafts documentation only from what that graph contains.
The agent installs graphify with pip, runs it on the project directory with the --no-viz flag, and reads the resulting GRAPH_REPORT.md and graph.json. It then issues graphify query commands for routes, data models, authentication and entry points, and cross-checks a few results against source files. Relationships marked EXTRACTED are trusted; INFERRED ones are qualified or flagged. If graphify is unavailable, fallback scripts extract TypeScript or Python structure. Templates in references/output-template.md guide the README and API reference, and anything undocumented is marked [Description needed] rather than guessed.
The skill checks existing README.md, docs/API.md and CHANGELOG.md before deciding whether to write fresh or update sections, and can offer to open a GitHub PR with gh pr create on a dated branch. Cleanup removes graphify-out and extraction files.
What an agent can do with it
- 1Create a README for a new projectAsk an AI client to build the first README for a repository, using the graph to describe modules and setup.
- 2Generate API reference from routesHave the agent produce docs/API.md with each real route, its method, path and request shape.
- 3Refresh an outdated API sectionPoint the skill at a README whose endpoints have changed and ask it to rewrite only that part.
- 4Document architecture from code structureAsk for an architecture overview that explains the core modules and how they connect.
- 5Open a docs pull requestAfter the files are written, request a GitHub PR on a dated branch with the new documentation.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the docs-from-code skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the docs-from-code skill in Plugin
/plugin marketplace add Varnan-Tech/opendirectory /plugin install opendirectory-gtm-skills@opendirectory-marketplace
Install the docs-from-code skill in Claude Code
~/.claude/skills/docs-from-code/SKILL.md
$ npx degit Varnan-Tech/opendirectory/skills/docs-from-code ~/.claude/skills/docs-from-codeInstall the docs-from-code skill in Claude Code (project)
.claude/skills/docs-from-code/SKILL.md
$ npx degit Varnan-Tech/opendirectory/skills/docs-from-code .claude/skills/docs-from-codeInstall the docs-from-code skill in Codex
~/.agents/skills/docs-from-code/SKILL.md
$ npx degit Varnan-Tech/opendirectory/skills/docs-from-code ~/.agents/skills/docs-from-codeInstall the docs-from-code skill in Gemini CLI
~/.gemini/skills/docs-from-code/SKILL.md
$ npx degit Varnan-Tech/opendirectory/skills/docs-from-code ~/.gemini/skills/docs-from-codeInstall the docs-from-code skill in Claude.ai
npx degit Varnan-Tech/opendirectory/skills/docs-from-code docs-from-code && zip -r docs-from-code.zip docs-from-code # claude.ai → Customize → Skills → + → Create skill → Upload a skill → docs-from-code.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablevarnan-tech/opendirectory/skills/docs-from-code is public and reachablegithub.com/varnan-tech/opendirectory/tree/HEAD/skills/docs-f ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-10-17github.com/varnan-tech/opendirectory/commits ↗Pass
- No download-and-run or credential theft in scripts2 scripts read; no download-and-run, remote eval, base64 execution or credential uploadPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/varnan-tech/opendirectory/blob/HEAD/skills/docs-f ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/varnan-tech/opendirectory/blob/HEAD/skills/docs-f ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 160 linesgithub.com/varnan-tech/opendirectory/blob/HEAD/skills/docs-f ↗Pass
SKILL.md
View on GitHubdocs-from-code
You are a technical writer. Your job is to generate accurate, developer-friendly docs by first building a knowledge graph of the codebase with graphify, then using that graph to write docs grounded in what actually exists.
DO NOT invent code. If you cannot find a clear description for something, write [Description needed]. Accurate but sparse docs are better than confident but wrong docs.
Before starting: Confirm you are inside a codebase directory. If the user pointed you at a remote repo, clone it first. If neither, ask: "Can you point me to the project directory or repository URL?"
Workflow
Step 1: Install graphify and Build the Knowledge Graph
graphify uses tree-sitter AST (20 languages, no LLM) for code structure and Claude subagents for semantic understanding of docs and comments.
pip install graphifyy
graphify . --no-viz
--no-viz skips HTML output. You only need GRAPH_REPORT.md and graph.json.
This produces graphify-out/ in the project root:
GRAPH_REPORT.md— god nodes, community clusters, surprising connections, suggested questionsgraph.json— full queryable knowledge graph (persistent, SHA256-cached)
QA: Did graphify-out/GRAPH_REPORT.md get created? How many nodes and edges? If graphify fails, go to Step 1B.
Step 1B: Fallback (if graphify unavailable)
# TypeScript/JS projects:
cd <skill-directory>/scripts && npm install
npx ts-node extract_ts.ts <project-root> <project-root>/.docs-extract.json
# Python projects:
python3 <skill-directory>/scripts/extract_py.py <project-root> <project-root>/.docs-extract.json
Read references/extraction-guide.md for framework-specific notes on the fallback output.
Step 2: Read the Graph Report
Read graphify-out/GRAPH_REPORT.md in full. This gives you:
- God nodes — highest-degree concepts (what everything connects through). Use these for the Architecture section.
- Community clusters — logical groupings of related code. Use these for module documentation.
- Surprising connections — non-obvious cross-file relationships. Note these in Architecture.
- Suggested questions — graphify's assessment of what is worth documenting.
Then run targeted queries for specific doc sections:
# API routes
graphify query "show all API routes and endpoints" --graph graphify-out/graph.json
# Data models
graphify query "what are the main data models and types?" --graph graphify-out/graph.json
# Auth flow
graphify query "how does authentication work?" --graph graphify-out/graph.json
# Entry points
graphify query "what is the entry point and how is the app initialised?" --graph graphify-out/graph.json
Each query returns a focused subgraph. Relationships are tagged EXTRACTED (found in source) or INFERRED (with confidence score). Trust EXTRACTED fully. Use INFERRED but flag uncertainty.
QA: Cross-check 2-3 routes from the query against actual source files before writing docs.
Step 3: Read Existing Documentation
Before writing anything new, check what already exists:
- Read
README.mdif present. Note which sections exist and which are stale or missing. - Read
docs/API.md,docs/api.md, orAPI.mdif present. - Read
CHANGELOG.mdfor context on recent changes worth noting.
Decide what to generate:
- No README — generate a full README from Template 1 in
references/output-template.md - README exists, API section stale — update only that section (Template 3)
- README exists, fully outdated — ask: "Your README exists but appears outdated. Rewrite fully or update specific sections?"
QA: List exactly what you will write or update before starting.
Step 4: Generate Documentation
Read references/output-template.md for the exact templates to use.
README — Project Description:
From package.json or pyproject.toml description + god nodes summary from GRAPH_REPORT.md.
README — Architecture Section: Use god nodes and community clusters to write a plain-English architecture overview. Example:
"The system is organised around 3 core modules:
AuthService(god node, connects to 14 other components),DatabaseAdapter(bridges all data access), andEventBus(central to async flows). The auth and request-handling modules are tightly coupled; the analytics module is independent."
README — Installation and Quick Start:
From the entry point file + scripts in package.json or Makefile.
API Reference (docs/API.md):
From the graphify query "show all API routes" output. One section per resource, grouped by path prefix. For each route: method, path, description (from docstring or rationale node), request/response shape (from linked type nodes), curl example.
Flag anything without a docstring as [Description needed]. Do not invent behaviour.
QA: Check 3 random routes in the generated docs/API.md against the actual source file. Do the paths and descriptions match?
Step 5: Write Files, Clean Up, and Open PR
- Write
README.mdto the project root (full file or updated sections only). - Write
docs/API.mdif routes were found. Createdocs/if needed. - Clean up:
rm -rf graphify-out/ .docs-extract.json
Ask the user: "Docs written. Should I open a GitHub PR with these changes?"
If yes:
git checkout -b docs/auto-generated-$(date +%Y%m%d)
git add README.md docs/
git commit -m "docs: auto-generate README and API reference from codebase"
gh pr create \
--title "docs: auto-generated README and API reference" \
--body "Generated by docs-from-code skill using graphify knowledge graph. All routes and types verified against source."
QA: Did the files write? Do paths exist? Did the PR open cleanly?
What Good Output Looks Like
- Architecture section explains god nodes and module relationships in plain English
- Every route in
docs/API.mdmatches a real path from the graphify query output - README Quick Start has a runnable snippet from tests or the entry point
- INFERRED relationships that influenced descriptions are noted as "likely" or "appears to"
- Missing descriptions are flagged
[Description needed], not fabricated
What Bad Output Looks Like
- Routes or functions that do not appear in the graphify query results
- Architecture section that is generic ("the app has controllers, services, and models")
- Examples using wrong function names or parameter types
- INFERRED edges described as definite facts without a confidence qualifier
Files in this skill
9docs-from-code skill questions
How do I install the docs-from-code skill in Claude Code?
Run npx degit Varnan-Tech/opendirectory/skills/docs-from-code ~/.claude/skills/docs-from-code. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the docs-from-code skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How does the skill keep generated docs accurate instead of making up endpoints?
It builds a knowledge graph of the codebase with graphify first, then queries that graph for routes, models, and auth flow. Anything lacking a clear description is marked [Description needed] rather than invented.
What commands does it use to build the code knowledge graph?
It installs graphify with pip and runs it against the project directory with visualization disabled. This produces GRAPH_REPORT.md and graph.json in a graphify-out folder.
Can it update an outdated README instead of rewriting everything?
Yes. It reads existing README, API doc, and changelog files first, then either updates specific stale sections or asks whether to do a full rewrite.
Does it open a pull request with the generated docs?
It asks the user first, and if confirmed creates a dated docs branch, commits README and docs changes, and opens a PR via the GitHub CLI.