@opendirectory.dev/skills 0.1.0

package/skills/docs-from-code/scripts/extract_py.py

@@ -0,0 +1,238 @@
+"""
+docs-from-code — Python Code Extractor
+Uses Python's built-in `ast` module to extract structured metadata.
+Works for Flask, FastAPI, Django REST, and plain Python projects.
+
+Usage: python extract_py.py <project-root> [output-file]
+"""
+
+import ast
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+
+def get_docstring(node: ast.AST) -> str:
+    """Extract docstring from a function, class, or module node."""
+    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Module)):
+        if (node.body and isinstance(node.body[0], ast.Expr)
+                and isinstance(node.body[0].value, ast.Constant)
+                and isinstance(node.body[0].value.value, str)):
+            return node.body[0].value.value.strip()
+    return ""
+
+
+def get_annotation(node: Any) -> str:
+    """Convert AST annotation to string."""
+    if node is None:
+        return ""
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Constant):
+        return str(node.value)
+    if isinstance(node, ast.Attribute):
+        return f"{get_annotation(node.value)}.{node.attr}"
+    if isinstance(node, ast.Subscript):
+        return f"{get_annotation(node.value)}[{get_annotation(node.slice)}]"
+    if isinstance(node, ast.Tuple):
+        return ", ".join(get_annotation(e) for e in node.elts)
+    if isinstance(node, ast.BinOp):
+        return f"{get_annotation(node.left)} | {get_annotation(node.right)}"
+    try:
+        return ast.unparse(node)
+    except Exception:
+        return ""
+
+
+def extract_functions(tree: ast.Module, file_path: str, is_exported_only: bool = False):
+    """Extract top-level functions and their signatures."""
+    functions = []
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if node.col_offset != 0:  # skip nested functions / methods
+            continue
+        if is_exported_only and node.name.startswith("_"):
+            continue
+
+        args = node.args
+        params = []
+        all_args = args.posonlyargs + args.args + args.kwonlyargs
+        for i, arg in enumerate(all_args):
+            params.append({
+                "name": arg.arg,
+                "type": get_annotation(arg.annotation),
+                "description": ""
+            })
+
+        returns = get_annotation(node.returns)
+        is_async = isinstance(node, ast.AsyncFunctionDef)
+
+        functions.append({
+            "name": node.name,
+            "signature": f"{'async ' if is_async else ''}def {node.name}({', '.join(p['name'] + (': ' + p['type'] if p['type'] else '') for p in params)}) -> {returns}",
+            "description": get_docstring(node),
+            "params": params,
+            "returns": returns,
+            "file": file_path,
+            "isExported": not node.name.startswith("_")
+        })
+    return functions
+
+
+def extract_routes(tree: ast.Module, file_path: str, framework: str):
+    """Extract API routes from FastAPI, Flask, or Django decorators."""
+    routes = []
+
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+
+        for decorator in node.decorator_list:
+            # FastAPI / Flask style: @app.get("/path") or @router.post("/path")
+            if isinstance(decorator, ast.Call) and isinstance(decorator.func, ast.Attribute):
+                method = decorator.func.attr.upper()
+                if method in ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"]:
+                    route_path = ""
+                    if decorator.args and isinstance(decorator.args[0], ast.Constant):
+                        route_path = decorator.args[0].value
+                    routes.append({
+                        "method": method,
+                        "path": route_path,
+                        "handler": node.name,
+                        "description": get_docstring(node),
+                        "file": file_path
+                    })
+
+            # Django REST: @api_view(['GET', 'POST'])
+            if isinstance(decorator, ast.Call) and isinstance(decorator.func, ast.Name):
+                if decorator.func.id == "api_view":
+                    for arg in decorator.args:
+                        if isinstance(arg, ast.List):
+                            for elt in arg.elts:
+                                if isinstance(elt, ast.Constant):
+                                    routes.append({
+                                        "method": elt.value,
+                                        "path": "",
+                                        "handler": node.name,
+                                        "description": get_docstring(node),
+                                        "file": file_path
+                                    })
+
+    return routes
+
+
+def extract_classes(tree: ast.Module, file_path: str):
+    """Extract class definitions with their public methods."""
+    classes = []
+    for node in ast.iter_child_nodes(tree):
+        if not isinstance(node, ast.ClassDef):
+            continue
+        methods = []
+        for item in ast.iter_child_nodes(node):
+            if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                if not item.name.startswith("__"):
+                    methods.append(item.name)
+        classes.append({
+            "name": node.name,
+            "kind": "class",
+            "definition": f"class {node.name}",
+            "description": get_docstring(node),
+            "methods": methods,
+            "file": file_path
+        })
+    return classes
+
+
+def detect_framework(project_root: str) -> str:
+    """Detect Python framework from requirements.txt or pyproject.toml."""
+    req_files = [
+        os.path.join(project_root, "requirements.txt"),
+        os.path.join(project_root, "requirements/base.txt"),
+    ]
+    for req_file in req_files:
+        if os.path.exists(req_file):
+            content = open(req_file).read().lower()
+            if "fastapi" in content:
+                return "fastapi"
+            if "flask" in content:
+                return "flask"
+            if "django" in content:
+                return "django"
+            if "tornado" in content:
+                return "tornado"
+
+    pyproject = os.path.join(project_root, "pyproject.toml")
+    if os.path.exists(pyproject):
+        content = open(pyproject).read().lower()
+        if "fastapi" in content:
+            return "fastapi"
+        if "flask" in content:
+            return "flask"
+        if "django" in content:
+            return "django"
+
+    return "python"
+
+
+def main():
+    project_root = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
+    output_file = sys.argv[2] if len(sys.argv) > 2 else os.path.join(project_root, ".docs-extract.json")
+
+    framework = detect_framework(project_root)
+    skip_dirs = {"__pycache__", ".git", "node_modules", "venv", ".venv", "env",
+                 "dist", "build", ".tox", "migrations", "static", "media"}
+
+    metadata = {
+        "projectName": os.path.basename(project_root),
+        "language": "python",
+        "framework": framework,
+        "entryPoints": [],
+        "functions": [],
+        "routes": [],
+        "types": [],
+        "dependencies": {},
+        "scripts": {}
+    }
+
+    for root, dirs, files in os.walk(project_root):
+        dirs[:] = [d for d in dirs if d not in skip_dirs and not d.startswith(".")]
+        for file in files:
+            if not file.endswith(".py"):
+                continue
+            file_path = os.path.join(root, file)
+            try:
+                source = open(file_path, encoding="utf-8").read()
+                tree = ast.parse(source, filename=file_path)
+            except (SyntaxError, UnicodeDecodeError):
+                continue
+
+            metadata["functions"].extend(extract_functions(tree, file_path, is_exported_only=True))
+            metadata["routes"].extend(extract_routes(tree, file_path, framework))
+            metadata["types"].extend(extract_classes(tree, file_path))
+
+    # Detect entry points
+    for candidate in ["main.py", "app.py", "server.py", "manage.py", "run.py", "wsgi.py"]:
+        if os.path.exists(os.path.join(project_root, candidate)):
+            metadata["entryPoints"].append(candidate)
+
+    # Read requirements
+    req_file = os.path.join(project_root, "requirements.txt")
+    if os.path.exists(req_file):
+        for line in open(req_file):
+            line = line.strip()
+            if line and not line.startswith("#"):
+                parts = line.split("==")
+                metadata["dependencies"][parts[0]] = parts[1] if len(parts) > 1 else "*"
+
+    with open(output_file, "w") as f:
+        json.dump(metadata, f, indent=2)
+
+    print(f"Extracted {len(metadata['functions'])} functions, {len(metadata['routes'])} routes, {len(metadata['types'])} classes")
+    print(f"Output: {output_file}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/docs-from-code/scripts/extract_ts.ts

@@ -0,0 +1,284 @@
+/**
+ * docs-from-code — TypeScript/JavaScript Code Extractor
+ * Uses ts-morph to extract structured metadata from a TS/JS codebase.
+ * Outputs a JSON file the agent feeds to Gemini for doc generation.
+ *
+ * Usage: npx ts-node extract_ts.ts <project-root> [output-file]
+ */
+
+import { Project, SyntaxKind, SourceFile } from "ts-morph";
+import * as fs from "fs";
+import * as path from "path";
+
+interface FunctionDoc {
+  name: string;
+  signature: string;
+  description: string;
+  params: { name: string; type: string; description: string }[];
+  returns: string;
+  file: string;
+  isExported: boolean;
+}
+
+interface RouteDoc {
+  method: string;
+  path: string;
+  handler: string;
+  description: string;
+  file: string;
+}
+
+interface TypeDoc {
+  name: string;
+  kind: "interface" | "type" | "enum" | "class";
+  definition: string;
+  description: string;
+  file: string;
+}
+
+interface CodeMetadata {
+  projectName: string;
+  language: "typescript" | "javascript";
+  framework: string | null;
+  entryPoints: string[];
+  functions: FunctionDoc[];
+  routes: RouteDoc[];
+  types: TypeDoc[];
+  dependencies: Record<string, string>;
+  scripts: Record<string, string>;
+}
+
+function detectFramework(pkgJson: any): string | null {
+  const deps = {
+    ...pkgJson.dependencies,
+    ...pkgJson.devDependencies,
+  };
+  if (deps["next"]) return "nextjs";
+  if (deps["express"]) return "express";
+  if (deps["hono"]) return "hono";
+  if (deps["fastify"]) return "fastify";
+  if (deps["@nestjs/core"]) return "nestjs";
+  if (deps["koa"]) return "koa";
+  if (deps["@sveltejs/kit"]) return "sveltekit";
+  if (deps["astro"]) return "astro";
+  return null;
+}
+
+function extractJsDocComment(node: any): string {
+  try {
+    const docs = node.getJsDocs?.();
+    if (docs && docs.length > 0) {
+      return docs[0].getDescription().trim();
+    }
+  } catch {}
+  return "";
+}
+
+function extractRoutes(sourceFile: SourceFile, framework: string | null): RouteDoc[] {
+  const routes: RouteDoc[] = [];
+  const filePath = sourceFile.getFilePath();
+
+  // Express / Hono / Fastify / Koa style: app.get('/path', handler)
+  const callExpressions = sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression);
+  for (const call of callExpressions) {
+    const expr = call.getExpression().getText();
+    const httpMethods = ["get", "post", "put", "patch", "delete", "options", "head"];
+    const methodMatch = httpMethods.find((m) => expr.endsWith(`.${m}`));
+    if (methodMatch) {
+      const args = call.getArguments();
+      if (args.length >= 1) {
+        const routePath = args[0].getText().replace(/['"]/g, "");
+        routes.push({
+          method: methodMatch.toUpperCase(),
+          path: routePath,
+          handler: args[1]?.getText()?.slice(0, 80) || "",
+          description: "",
+          file: filePath,
+        });
+      }
+    }
+  }
+
+  // Next.js app router: export async function GET/POST etc
+  if (framework === "nextjs" && filePath.includes("/api/")) {
+    const functions = sourceFile.getFunctions();
+    for (const fn of functions) {
+      const name = fn.getName() || "";
+      const httpMethods = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+      if (httpMethods.includes(name) && fn.isExported()) {
+        const routePath = filePath
+          .replace(/.*\/app/, "")
+          .replace(/\/route\.(ts|tsx|js|jsx)$/, "")
+          || "/";
+        routes.push({
+          method: name,
+          path: routePath,
+          handler: fn.getName() || "",
+          description: extractJsDocComment(fn),
+          file: filePath,
+        });
+      }
+    }
+  }
+
+  return routes;
+}
+
+function extractFunctions(sourceFile: SourceFile): FunctionDoc[] {
+  const functions: FunctionDoc[] = [];
+  const filePath = sourceFile.getFilePath();
+
+  // Regular functions
+  for (const fn of sourceFile.getFunctions()) {
+    if (!fn.isExported()) continue;
+    const name = fn.getName() || "anonymous";
+    const params = fn.getParameters().map((p) => ({
+      name: p.getName(),
+      type: p.getType().getText(),
+      description: "",
+    }));
+    functions.push({
+      name,
+      signature: `${name}(${fn.getParameters().map((p) => p.getText()).join(", ")}): ${fn.getReturnType().getText()}`,
+      description: extractJsDocComment(fn),
+      params,
+      returns: fn.getReturnType().getText(),
+      file: filePath,
+      isExported: true,
+    });
+  }
+
+  // Arrow functions assigned to exported const
+  for (const varDecl of sourceFile.getVariableDeclarations()) {
+    const init = varDecl.getInitializer();
+    if (!init) continue;
+    const isArrow = init.getKind() === SyntaxKind.ArrowFunction;
+    if (!isArrow) continue;
+    const varStatement = varDecl.getVariableStatement();
+    if (!varStatement?.isExported()) continue;
+    const name = varDecl.getName();
+    functions.push({
+      name,
+      signature: `${name} = ${init.getText().slice(0, 120)}`,
+      description: extractJsDocComment(varStatement),
+      params: [],
+      returns: "",
+      file: filePath,
+      isExported: true,
+    });
+  }
+
+  return functions;
+}
+
+function extractTypes(sourceFile: SourceFile): TypeDoc[] {
+  const types: TypeDoc[] = [];
+  const filePath = sourceFile.getFilePath();
+
+  for (const iface of sourceFile.getInterfaces()) {
+    if (!iface.isExported()) continue;
+    types.push({
+      name: iface.getName(),
+      kind: "interface",
+      definition: iface.getText().slice(0, 400),
+      description: extractJsDocComment(iface),
+      file: filePath,
+    });
+  }
+
+  for (const typeAlias of sourceFile.getTypeAliases()) {
+    if (!typeAlias.isExported()) continue;
+    types.push({
+      name: typeAlias.getName(),
+      kind: "type",
+      definition: typeAlias.getText().slice(0, 400),
+      description: extractJsDocComment(typeAlias),
+      file: filePath,
+    });
+  }
+
+  for (const cls of sourceFile.getClasses()) {
+    if (!cls.isExported()) continue;
+    types.push({
+      name: cls.getName() || "AnonymousClass",
+      kind: "class",
+      definition: cls.getText().slice(0, 600),
+      description: extractJsDocComment(cls),
+      file: filePath,
+    });
+  }
+
+  return types;
+}
+
+async function main() {
+  const projectRoot = process.argv[2] || process.cwd();
+  const outputFile = process.argv[3] || path.join(projectRoot, ".docs-extract.json");
+
+  // Load package.json
+  const pkgPath = path.join(projectRoot, "package.json");
+  let pkgJson: any = {};
+  if (fs.existsSync(pkgPath)) {
+    pkgJson = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+  }
+
+  const framework = detectFramework(pkgJson);
+
+  // Init ts-morph project
+  const project = new Project({
+    tsConfigFilePath: fs.existsSync(path.join(projectRoot, "tsconfig.json"))
+      ? path.join(projectRoot, "tsconfig.json")
+      : undefined,
+    addFilesFromTsConfig: false,
+  });
+
+  // Add source files — skip node_modules, .next, dist, build
+  const extensions = [".ts", ".tsx"];
+  const skipDirs = ["node_modules", ".next", "dist", "build", ".turbo", "coverage", ".cache"];
+
+  function addFiles(dir: string) {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (!skipDirs.includes(entry.name)) {
+          addFiles(path.join(dir, entry.name));
+        }
+      } else if (extensions.some((ext) => entry.name.endsWith(ext))) {
+        project.addSourceFileAtPath(path.join(dir, entry.name));
+      }
+    }
+  }
+
+  addFiles(projectRoot);
+
+  const metadata: CodeMetadata = {
+    projectName: pkgJson.name || path.basename(projectRoot),
+    language: "typescript",
+    framework,
+    entryPoints: [],
+    functions: [],
+    routes: [],
+    types: [],
+    dependencies: pkgJson.dependencies || {},
+    scripts: pkgJson.scripts || {},
+  };
+
+  for (const sourceFile of project.getSourceFiles()) {
+    metadata.functions.push(...extractFunctions(sourceFile));
+    metadata.routes.push(...extractRoutes(sourceFile, framework));
+    metadata.types.push(...extractTypes(sourceFile));
+  }
+
+  // Detect entry points
+  const commonEntries = ["src/index.ts", "index.ts", "src/main.ts", "server.ts", "app.ts"];
+  metadata.entryPoints = commonEntries
+    .filter((e) => fs.existsSync(path.join(projectRoot, e)))
+    .map((e) => e);
+
+  fs.writeFileSync(outputFile, JSON.stringify(metadata, null, 2));
+
+  console.log(`Extracted ${metadata.functions.length} functions, ${metadata.routes.length} routes, ${metadata.types.length} types`);
+  console.log(`Output: ${outputFile}`);
+}
+
+main().catch(console.error);

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

@@ -0,0 +1,18 @@
+{
+  "name": "docs-from-code-scripts",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Extraction scripts for docs-from-code skill",
+  "scripts": {
+    "extract:ts": "ts-node extract_ts.ts",
+    "extract:py": "python3 extract_py.py"
+  },
+  "dependencies": {
+    "ts-morph": "^21.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.4.0"
+  }
+}

package/skills/explain-this-pr/README.md

@@ -0,0 +1,74 @@
+# explain-this-pr
+
+<img width="1280" height="640" alt="explain-this-pr" src="https://github.com/user-attachments/assets/9e76fc64-f982-4c4c-9b58-4398541aab97" />
+
+
+Point this skill at any GitHub PR and it writes a plain-English explanation of what changed and why, then posts it as a PR comment.
+
+## What It Does
+
+- Fetches the PR diff and metadata via `gh`
+- Writes two paragraphs: what changed (technical) and why it matters (impact)
+- Posts the explanation as a PR comment with `gh pr comment`
+- Works with any public or private repo you have access to via `gh`
+
+## Requirements
+
+| Requirement | Purpose | How to Set Up |
+|------------|---------|--------------|
+| `gh` CLI | Fetching PR data and posting comments | https://cli.github.com, then run `gh auth login` |
+
+No API keys needed.
+
+## How to Use
+
+Explain a PR by URL:
+
+```
+"Explain this PR: https://github.com/owner/repo/pull/123"
+"What does this PR do? https://github.com/owner/repo/pull/456"
+"Summarize this pull request: [URL]"
+```
+
+Explain by PR number (in the current repo):
+
+```
+"Explain PR #42"
+"Add a summary comment to PR #99"
+```
+
+Explain the current branch PR:
+
+```
+"Explain the current branch PR"
+"Add a plain-English comment to my PR"
+```
+
+Output without posting:
+
+```
+"Explain this PR but don't post the comment: [URL]"
+"What does this PR change? Just give me the text."
+```
+
+## Output Format
+
+Two paragraphs, under 150 words total.
+
+Paragraph 1: What it does (technical). Names the specific files, functions, or systems that changed. States the before/after if visible in the diff.
+
+Paragraph 2: Why it matters (impact). Explains who benefits and what problem is solved. Omitted if there is no clear "why" in the diff or commits. The skill never guesses at impact.
+
+## Project Structure
+
+```
+explain-this-pr/
+├── SKILL.md
+├── README.md
+└── evals/
+    └── evals.json
+```
+
+## License
+
+MIT