@opendirectory.dev/skills 0.1.0

package/skills/docs-from-code/README.md

@@ -0,0 +1,97 @@
+# docs-from-code
+
+![docs-from-code](https://github.com/user-attachments/assets/493c7c61-9aa9-48e9-a71b-7c77c8c6a949)
+
+Automatically generate and maintain README.md, API reference docs, and an Architecture section by reading your codebase. Uses [graphify](https://github.com/safishamsi/graphify) to build a knowledge graph first, then uses AI to write clean documentation grounded in what actually exists.
+
+## What It Generates
+
+| Output | When |
+|--------|------|
+| `README.md` (full) | Project has no README |
+| `README.md` (sections) | README exists but API or architecture sections are stale |
+| `docs/API.md` | Project has HTTP routes |
+| Architecture section | Always, from graphify's god nodes and communities |
+| GitHub PR | When you ask it to open one |
+
+## Why graphify?
+
+The skill uses graphify as its extraction engine:
+- 20 languages via tree-sitter AST: Python, TypeScript, Go, Rust, Java, and 15 more
+- Architecture insight: god nodes and community clusters show what everything connects through
+- 71.5x fewer tokens than reading raw files, efficient on large codebases
+- SHA256 cache: re-runs only process changed files
+- Honest tagging: `EXTRACTED` (found in source) vs `INFERRED` (reasonable inference with confidence score)
+- Extracts rationale from `# NOTE:`, `# WHY:`, `# HACK:` comments and docstrings
+
+The bundled `scripts/` (TypeScript and Python AST extractors) serve as a fallback if graphify is unavailable.
+
+## Supported Languages (via graphify)
+
+Python, TypeScript, JavaScript, Go, Rust, Java, C, C++, Ruby, C#, Kotlin, Scala, PHP, Swift, Lua, Zig, PowerShell, Elixir, Objective-C, Julia
+
+## Requirements
+
+- Python 3.10+ (for graphify)
+- Node.js 18+ (for fallback TypeScript extractor)
+- `gh` CLI (optional, for opening PRs automatically)
+- `GITHUB_TOKEN` env var (optional, for PRs)
+
+## Setup
+
+### 1. Install graphify
+
+```bash
+pip install graphifyy
+```
+
+No API keys needed for extraction. graphify uses your agent's existing model access.
+
+### 2. Configure (Optional)
+
+```bash
+cp .env.example .env
+# Add GITHUB_TOKEN if you want auto-PR support
+```
+
+## How to Use
+
+Be inside your project and ask:
+
+```
+"Generate a README for this project"
+"My API docs are out of date, update them from the code"
+"Create docs/API.md from my FastAPI routes"
+"Add an architecture section to our README"
+"Document this TypeScript library"
+```
+
+The agent will:
+1. Run `graphify . --no-viz` to build a knowledge graph of your codebase
+2. Read `GRAPH_REPORT.md` for god nodes, communities, and architecture insights
+3. Query the graph for routes, types, and data models
+4. Read existing docs to understand what needs updating
+5. Generate accurate docs grounded in the graph
+6. Write files and optionally open a GitHub PR
+
+## Project Structure
+
+```
+docs-from-code/
+├── SKILL.md                         # Agent instructions
+├── README.md                        # This file
+├── .env.example                     # Environment variables template
+├── scripts/
+│   ├── package.json                 # Script dependencies (ts-morph)
+│   ├── extract_ts.ts                # TypeScript/JS AST extractor
+│   └── extract_py.py                # Python AST extractor
+├── references/
+│   ├── extraction-guide.md          # Per-framework extraction notes
+│   └── output-template.md          # README and API.md templates
+└── evals/
+    └── evals.json                   # Test prompts
+```
+
+## License
+
+MIT

package/skills/docs-from-code/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: docs-from-code
+description: Generates and updates README.md and API reference docs by reading your codebase's functions, routes, types, schemas, and architecture. Uses graphify to build a knowledge graph first, then writes accurate docs from it. Use when asked to write docs, generate a README, document an API, update stale docs, create an API reference from code, add an architecture section, or document a project in any language. Trigger when a user says their docs are missing, outdated, or wants to document their codebase without writing it manually.
+compatibility: [claude-code, gemini-cli, github-copilot]
+author: OpenDirectory
+version: 1.0.0
+---
+
+# docs-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.
+
+```bash
+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 questions
+- `graph.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)
+
+```bash
+# 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:
+
+```bash
+# 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:
+
+1. Read `README.md` if present. Note which sections exist and which are stale or missing.
+2. Read `docs/API.md`, `docs/api.md`, or `API.md` if present.
+3. Read `CHANGELOG.md` for 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), and `EventBus` (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
+
+1. Write `README.md` to the project root (full file or updated sections only).
+2. Write `docs/API.md` if routes were found. Create `docs/` if needed.
+3. 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:
+```bash
+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.md` matches 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
+
+

package/skills/docs-from-code/evals/evals.json

@@ -0,0 +1,29 @@
+{
+  "skill_name": "docs-from-code",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "My Express API has no README at all. Generate one from the codebase.",
+      "expected_output": "Agent runs `graphify . --no-viz` to build the knowledge graph. Reads GRAPH_REPORT.md for god nodes and community clusters. Queries graph for routes and types. Generates a complete README.md with: project name and description, installation steps, an Architecture section based on god nodes, API reference with all found routes (method, path, description from graphify), configuration table from .env.example. Writes README.md to the project root.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "My FastAPI project has routes across 3 router files but no API docs. Generate docs/API.md for me.",
+      "expected_output": "Agent runs graphify on the project. Queries `graphify query 'show all API routes'` to get routes across all router files. Groups routes by resource prefix from graph output. Generates docs/API.md with each route containing: method, path, description from docstring or rationale node (or [Description needed]), request params from Pydantic model nodes in graph, curl example. INFERRED relationships are qualified with 'likely' or 'appears to'.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "I have a Next.js app router project. The README exists but the API section is 6 months out of date — we added 5 new endpoints. Update only the API section.",
+      "expected_output": "Agent runs graphify and queries for API routes. Reads existing README.md to locate the current API section. Replaces only that section with updated route documentation from graphify output. Leaves all other README sections untouched. Cleans up graphify-out/. Offers to open a PR.",
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "Add an architecture section to our README. We have a Go backend with a lot of internal packages and nobody knows how they connect.",
+      "expected_output": "Agent runs graphify on the Go project (tree-sitter supports Go natively). Reads GRAPH_REPORT.md to identify god nodes and community clusters. Writes an Architecture section in README.md describing: the top 3-5 god nodes by name and what they connect to, the 2-3 main community clusters and what they represent, any surprising cross-module connections flagged by graphify. Plain English, no invented relationships.",
+      "files": []
+    }
+  ]
+}

package/skills/docs-from-code/references/extraction-guide.md

@@ -0,0 +1,174 @@
+# Extraction Guide
+
+## Primary: graphify
+
+graphify is the primary extraction engine. Run it first:
+
+```bash
+pip install graphifyy
+graphify . --no-viz
+```
+
+### What graphify produces for docs
+
+| Output | Use for |
+|--------|---------|
+| `GRAPH_REPORT.md` god nodes | Architecture section: "what everything connects through" |
+| `GRAPH_REPORT.md` communities | Module breakdown: how to organise the API reference |
+| `graphify query "API routes"` | `docs/API.md` route list |
+| `graphify query "data models"` | Request/response types in API docs |
+| `graphify query "auth flow"` | Authentication section in README |
+| `graphify query "entry point"` | Quick start and installation section |
+| `rationale_for` nodes in graph | Architecture decisions and "why it was built this way" |
+
+### Querying the graph
+
+```bash
+# Routes
+graphify query "show all HTTP routes and endpoints" --graph graphify-out/graph.json
+
+# Types
+graphify query "what are the main data models, interfaces, and types?" --graph graphify-out/graph.json
+
+# Auth
+graphify query "how does authentication and authorization work?" --graph graphify-out/graph.json
+
+# Config
+graphify query "what environment variables and configuration options are available?" --graph graphify-out/graph.json
+
+# Architecture
+graphify query "what are the most connected components and how do modules relate?" --graph graphify-out/graph.json
+
+# Entry point
+graphify query "how is the application started and initialised?" --graph graphify-out/graph.json
+```
+
+### Reading graph output
+
+Every edge in graphify output is tagged:
+- `EXTRACTED` — found directly in source code. Treat as fact.
+- `INFERRED` — reasonable inference with confidence score (0.0-1.0). Use in docs but qualify: "likely", "appears to", or add `[verify]`.
+- `AMBIGUOUS` — flagged for review. Do not include in docs without manual verification.
+
+---
+
+## Fallback: Custom Extraction Scripts
+
+Use this when graphify is unavailable. The scripts produce `.docs-extract.json` with the same structure used to write docs.
+
+---
+
+## TypeScript / JavaScript Projects
+
+### Next.js (App Router)
+- Routes: `app/**/route.ts` — exported HTTP method handlers (GET, POST, etc.)
+- Pages: `app/**/page.tsx` — document as "page components", not endpoints
+- Types: `src/types/**/*.ts`, `lib/types.ts` — shared TypeScript interfaces
+- Utilities: `lib/**/*.ts`, `utils/**/*.ts` — exported helper functions
+- Key files to read: `app/layout.tsx` (app metadata), `next.config.ts` (config)
+
+### Next.js (Pages Router)
+- Routes: `pages/api/**/*.ts` — default exported handler functions
+- Types: same as App Router
+- Key config: `next.config.js`
+
+### Express
+- Routes: calls to `app.get()`, `app.post()`, `router.get()`, etc.
+- Middleware: exported functions used as middleware
+- Models: any class or interface representing data shapes
+- Key files: `src/app.ts` or `app.js`, `src/routes/`, `src/models/`
+
+### Hono
+- Routes: `app.get('/path', handler)`, `app.post()`, etc. Same pattern as Express.
+- Zod schemas: exported `z.object(...)` definitions. Document as request/response schemas.
+
+### Fastify
+- Routes: `fastify.get('/path', opts, handler)` calls
+- Schemas: inline JSON schema objects in route options
+
+---
+
+## Python Projects
+
+### FastAPI
+- Routes: functions decorated with `@app.get()`, `@app.post()`, `@router.get()`, etc.
+- Pydantic models: classes extending `BaseModel`. Document as request/response schemas.
+- Dependencies: functions used with `Depends()`. Document if they affect auth or request shape.
+- Key files: `main.py`, `app/main.py`, `routers/`
+
+### Flask
+- Routes: functions decorated with `@app.route('/path', methods=['GET'])` or `@blueprint.route()`
+- Models: SQLAlchemy model classes (extend `db.Model`)
+- Key files: `app.py`, `__init__.py`, `routes/`, `models/`
+
+### Django REST Framework
+- Views: classes extending `APIView`, `ViewSet`, `ModelViewSet`
+- Serializers: classes extending `Serializer` or `ModelSerializer`
+- URLs: `urlpatterns` lists. Read `urls.py` directly.
+- Key files: `views.py`, `serializers.py`, `urls.py`, `models.py`
+
+---
+
+## Output JSON Schema
+
+The extraction scripts output `.docs-extract.json`:
+
+```json
+{
+  "projectName": "my-api",
+  "language": "typescript",
+  "framework": "express",
+  "entryPoints": ["src/index.ts"],
+  "functions": [
+    {
+      "name": "createUser",
+      "signature": "createUser(name: string, email: string): Promise<User>",
+      "description": "Creates a new user record in the database",
+      "params": [
+        { "name": "name", "type": "string", "description": "" },
+        { "name": "email", "type": "string", "description": "" }
+      ],
+      "returns": "Promise<User>",
+      "file": "/src/services/user.ts",
+      "isExported": true
+    }
+  ],
+  "routes": [
+    {
+      "method": "POST",
+      "path": "/users",
+      "handler": "createUserHandler",
+      "description": "",
+      "file": "/src/routes/users.ts"
+    }
+  ],
+  "types": [
+    {
+      "name": "User",
+      "kind": "interface",
+      "definition": "interface User { id: string; name: string; email: string; }",
+      "description": "",
+      "file": "/src/types/user.ts"
+    }
+  ],
+  "dependencies": { "express": "^4.18.0" },
+  "scripts": { "start": "node dist/index.js" }
+}
+```
+
+---
+
+## What to Prioritise When Writing Docs
+
+From the extracted data, prioritise in this order:
+
+1. Routes — developers integrating with your API need these most
+2. Public types and interfaces — define the data contract
+3. Exported utility functions — frequently called helpers
+4. Classes — especially models and services
+5. Internal or private functions — lowest priority, often skip
+
+Skip:
+- Test files (`*.test.ts`, `*.spec.ts`, `_test.py`)
+- Generated files (`*.generated.ts`, Prisma client output)
+- Config files with no user-facing exports

package/skills/docs-from-code/references/output-template.md

@@ -0,0 +1,135 @@
+# Output Templates
+
+Use these templates when generating documentation. Fill in real content from the extracted code metadata. Never invent function signatures or examples.
+
+---
+
+## Template 1: README.md
+
+Use when the project has no README, or when asked to generate a fresh one.
+
+```markdown
+# [Project Name]
+
+[1-2 sentence description of what this project does. Derived from package.json description or the main entry file's module docstring.]
+
+## Installation
+
+```bash
+# Clone the repo
+git clone <repo-url>
+cd <project-name>
+
+# Install dependencies
+npm install        # or: pip install -r requirements.txt
+
+# Configure environment
+cp .env.example .env
+# Edit .env with your values
+```
+
+## Quick Start
+
+```[language]
+[Minimal working example derived from the entry point or test files]
+```
+
+## API Reference
+
+[Generated from routes — see API Reference template below]
+
+## Configuration
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| [from .env.example or config files] | | |
+
+## Scripts
+
+| Command | Description |
+|---------|-------------|
+[from package.json scripts or Makefile]
+
+## License
+
+[from package.json or LICENSE file]
+```
+
+---
+
+## Template 2: API Reference (docs/API.md)
+
+Use for projects with HTTP routes. One entry per route.
+
+```markdown
+# API Reference
+
+Base URL: `https://api.yourdomain.com`
+
+Authentication: [describe auth method if detected: Bearer token, API key header, etc.]
+
+---
+
+## [Resource Name]
+
+### [METHOD] [/path]
+
+[Description from JSDoc or docstring if available; otherwise inferred from function name]
+
+**Request**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| [from function params, Zod schema, or Pydantic model] | | | |
+
+**Request Body** (if POST/PUT/PATCH)
+
+```json
+{
+  [derived from type definitions, Pydantic model, or Zod schema]
+}
+```
+
+**Response**
+
+```json
+{
+  [derived from return type or response model]
+}
+```
+
+**Example**
+
+```bash
+curl -X [METHOD] https://api.yourdomain.com[/path] \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '[request body if applicable]'
+```
+
+---
+```
+
+---
+
+## Template 3: README Update (Sections Only)
+
+Use when README already exists and only specific sections need updating.
+Identify which sections are stale (missing routes, outdated function signatures) and regenerate only those. Preserve the rest verbatim.
+
+Sections commonly stale after code changes:
+- `## API Reference` — when routes are added or changed
+- `## Configuration` — when new env vars are added
+- `## Installation` — when dependencies change
+- `## Quick Start` — when the entry point changes
+
+---
+
+## Rules for Filling Templates
+
+1. Document only exported functions and public routes. Skip private or internal helpers.
+2. Every code example must be runnable. If you cannot produce a real working example, write `[TODO: add example]` rather than inventing fake code.
+3. Route descriptions come from JSDoc or docstrings. If none exist, infer from the function or handler name only. Do not make up behaviour.
+4. Types come from the extraction output. Do not guess or invent type signatures.
+5. Keep descriptions factual. "Creates a user and returns the new record" is good. "Seamlessly manages your user lifecycle" is bad.
+6. Flag missing information explicitly. If a route has no docstring and an unclear name, write `[Description needed]` rather than hallucinating.