Add 10 rig samples (160-169) — 2026-07-26 (#169)

Author: github-actions[bot]

skills/rig/samples/160-dead-code-detector.md

@@ -0,0 +1,49 @@
+# 160 - Dead Code Detector
+
+```rig
+import { agent, defineTool, p, s } from "rig";
+import { repair } from "rig/addons";
+
+// Agent role: detect dead TypeScript exports by scanning for exported symbols and estimating usage counts.
+const deadCodeDetector = agent({
+  model: "small",
+  instructions: p`Detect dead code in this TypeScript project. 
+
+Files in project:
+${p.bash("find . -name '*.ts' -not -path '*/node_modules/*' -not -path '*/.git/*' | head -40")}
+
+Exported symbols found:
+${p.bash("grep -rn '^export ' --include='*.ts' . 2>/dev/null | grep -v node_modules | head -60")}
+
+Use the estimateUsage tool for each exported symbol name to count how many times it appears across the codebase. Classify each as: "used" (>1 reference), "possibly-dead" (exactly 1, the declaration itself), or "dead" (0 references outside declaration). Return only the declared output.`,
+  tools: [
+    defineTool("estimateUsage", {
+      description: "Count non-declaration usages of an exported symbol across the codebase",
+      parameters: s.object({ symbol: s.string }),
+      async handler({ symbol }) {
+        const { execSync } = await import("node:child_process");
+        try {
+          const out = execSync(
+            `grep -rn "\\b${symbol}\\b" --include="*.ts" . 2>/dev/null | grep -v "^export " | grep -v node_modules | wc -l`,
+            { encoding: "utf-8" }
+          );
+          return { symbol, usageCount: parseInt(out.trim(), 10) };
+        } catch {
+          return { symbol, usageCount: 0 };
+        }
+      },
+    }),
+  ],
+  addons: [repair()],
+  output: s.object({
+    symbols: s.record(s.object({
+      usageCount: s.int,
+      status: s.enum("used", "possibly-dead", "dead"),
+    })),
+    totalExported: s.int,
+    deadCount: s.int,
+  }),
+});
+
+export default deadCodeDetector;
+```

skills/rig/samples/161-openapi-spec-validator.md

@@ -0,0 +1,52 @@
+# 161 - OpenAPI Spec Validator
+
+```rig
+import { agent, defineTool, p, s } from "rig";
+
+// Agent role: validate an OpenAPI spec file for structural correctness and report issues.
+const openapiSpecValidator = agent({
+  model: "small",
+  instructions: p`Validate the OpenAPI specification in this workspace.
+
+openapi.json content:
+${p.readOptional("openapi.json")}
+
+openapi.yaml content:
+${p.readOptional("openapi.yaml")}
+
+Use the checkStructure tool to validate the spec content. Check for: required fields (openapi version, info.title, info.version, paths), valid HTTP methods, proper response codes, and schema references. Return only the declared output.`,
+  tools: [
+    defineTool("checkStructure", {
+      description: "Check structural validity of OpenAPI spec content",
+      parameters: s.object({ content: s.string }),
+      handler({ content }) {
+        const issues: Array<{ type: "error" | "warning" | "info"; message: string; path?: string }> = [];
+        try {
+          const spec = JSON.parse(content);
+          if (!spec.openapi) issues.push({ type: "error", message: "Missing required field 'openapi'", path: "openapi" });
+          if (!spec.info) issues.push({ type: "error", message: "Missing required field 'info'", path: "info" });
+          else {
+            if (!spec.info.title) issues.push({ type: "error", message: "Missing info.title", path: "info.title" });
+            if (!spec.info.version) issues.push({ type: "error", message: "Missing info.version", path: "info.version" });
+          }
+          if (!spec.paths) issues.push({ type: "error", message: "Missing required field 'paths'", path: "paths" });
+        } catch {
+          issues.push({ type: "warning", message: "Content is not valid JSON — may be YAML or empty" });
+        }
+        return { issues };
+      },
+    }),
+  ],
+  output: s.object({
+    valid: s.boolean,
+    issues: s.array(s.object({
+      type: s.enum("error", "warning", "info"),
+      message: s.string,
+      path: s.optional(s.string),
+    })),
+    issueCount: s.int,
+  }),
+});
+
+export default openapiSpecValidator;
+```

skills/rig/samples/162-api-endpoint-extractor.md

@@ -0,0 +1,40 @@
+# 162 - API Endpoint Extractor
+
+```rig
+import { agent, p, s } from "rig";
+
+// Agent role: classify purpose of each API endpoint found in route files.
+const endpointClassifier = agent({
+  name: "endpointClassifier",
+  model: "nano",
+  input: s.object({ route: s.string }),
+  instructions: p`Classify this API route: return purpose and description.`,
+  output: s.object({
+    purpose: s.enum("read", "write", "delete", "auth", "health", "other"),
+    description: s.string,
+  }),
+});
+
+// Agent role: extract API endpoints from route/controller files and classify each by purpose.
+const apiEndpointExtractor = agent({
+  model: "small",
+  agents: { endpointClassifier },
+  instructions: p`Extract and classify all API endpoints in this workspace.
+
+Route patterns found:
+${p.bash("grep -rn '\\.(get|post|put|delete|patch)(' --include='*.ts' --include='*.js' . 2>/dev/null | grep -v node_modules | head -40")}
+
+For each unique route pattern found, delegate to the endpointClassifier subagent to determine its purpose. Return all discovered endpoints with method, path, and purpose. Return only the declared output.`,
+  output: s.object({
+    endpoints: s.array(s.object({
+      method: s.enum("GET", "POST", "PUT", "DELETE", "PATCH"),
+      path: s.string,
+      purpose: s.enum("read", "write", "delete", "auth", "health", "other"),
+    })),
+    totalCount: s.int,
+    hasCrud: s.boolean,
+  }),
+});
+
+export default apiEndpointExtractor;
+```

skills/rig/samples/163-source-file-annotator.md

@@ -0,0 +1,41 @@
+# 163 - Source File Annotator
+
+```rig
+import { agent, p, s } from "rig";
+
+// Agent role: generate JSDoc annotations for TypeScript source files and write annotated output.
+const jsDocAnnotator = agent({
+  name: "jsDocAnnotator",
+  model: "nano",
+  input: s.object({ filePath: s.path, content: s.string }),
+  instructions: p`Add JSDoc comments to every exported function, class, and interface in the TypeScript source. Return only the declared output.`,
+  output: s.object({
+    annotatedContent: s.string,
+    annotationsAdded: s.int,
+  }),
+});
+
+// Agent role: annotate TypeScript source files with JSDoc comments using a subagent and write results.
+const sourceFileAnnotator = agent({
+  model: "small",
+  agents: { jsDocAnnotator },
+  instructions: p`Annotate TypeScript source files with JSDoc comments.
+
+TypeScript files in workspace:
+${p.bash("find . -name '*.ts' -not -path '*/node_modules/*' -not -name '*.test.ts' -not -name '*.d.ts' | head -20")}
+
+For each file, read its content, delegate to the jsDocAnnotator subagent, then write the annotated version back using p.write. Track which files were processed successfully and which were skipped.
+
+${p.write("annotated-summary.md", "# Annotation Summary\n<!-- will be filled by agent -->")}
+
+Return only the declared output.`,
+  output: s.object({
+    filesProcessed: s.int,
+    filesSkipped: s.int,
+    totalAnnotations: s.int,
+    processedPaths: s.array(s.path),
+  }),
+});
+
+export default sourceFileAnnotator;
+```

skills/rig/samples/164-stale-dependency-detector.md

@@ -0,0 +1,47 @@
+# 164 - Stale Dependency Detector
+
+```rig
+import { agent, defineTool, p, s } from "rig";
+import { repair } from "rig/addons";
+
+// Agent role: detect stale npm dependencies by comparing installed versions with latest published versions.
+const staleDependencyDetector = agent({
+  model: "small",
+  instructions: p`Identify stale npm dependencies that need updating.
+
+package.json contents:
+${p.read("package.json")}
+
+npm outdated results:
+${p.bash("npm outdated --json 2>/dev/null || echo '{}'")}
+
+Use the classifyDrift tool for each outdated package to classify the version drift level. Determine the overall risk for the project. Return only the declared output.`,
+  tools: [
+    defineTool("classifyDrift", {
+      description: "Classify version drift between current and latest version",
+      parameters: s.object({ current: s.string, latest: s.string }),
+      handler({ current, latest }) {
+        const parse = (v: string) => v.replace(/^[^0-9]*/, "").split(".").map(Number);
+        const [cMaj, cMin] = parse(current);
+        const [lMaj, lMin] = parse(latest);
+        if (lMaj > cMaj) return { driftLevel: "major" as const };
+        if (lMin > cMin) return { driftLevel: "minor" as const };
+        return { driftLevel: "patch" as const };
+      },
+    }),
+  ],
+  addons: [repair()],
+  output: s.object({
+    packages: s.array(s.object({
+      name: s.string,
+      current: s.string,
+      latest: s.string,
+      driftLevel: s.enum("major", "minor", "patch", "ok"),
+    })),
+    overallRisk: s.enum("safe", "moderate", "critical"),
+    staleCount: s.int,
+  }),
+});
+
+export default staleDependencyDetector;
+```

skills/rig/samples/165-git-tag-timeline.md

@@ -0,0 +1,50 @@
+# 165 - Git Tag Timeline
+
+```rig
+import { agent, p, s } from "rig";
+
+// Agent role: summarize commits and authors between two git tags.
+const timelineSummarizer = agent({
+  name: "timelineSummarizer",
+  model: "nano",
+  input: s.object({
+    tag: s.string,
+    prevTag: s.string,
+    commits: s.string,
+  }),
+  instructions: p`Summarize the git log between two tags and return structured timeline entry.`,
+  output: s.object({
+    tag: s.string,
+    date: s.string,
+    commitCount: s.int,
+    topAuthors: s.array(s.string),
+  }),
+});
+
+// Agent role: build a release timeline from git tags showing commit counts and top authors per tag.
+const gitTagTimeline = agent({
+  model: "small",
+  agents: { timelineSummarizer },
+  instructions: p`Build a git tag release timeline.
+
+Git tags (sorted by date):
+${p.bash("git tag --sort=version:refname 2>/dev/null | tail -20 || echo 'No tags found'")}
+
+Recent commit log:
+${p.bash("git log --oneline --format='%h %an %ad %s' --date=short -40 2>/dev/null || echo 'No commits'")}
+
+For each tag pair, delegate to the timelineSummarizer subagent with the relevant commit log section. Also check for unreleased commits after the latest tag. Return only the declared output.`,
+  output: s.object({
+    timeline: s.array(s.object({
+      tag: s.string,
+      date: s.string,
+      commitCount: s.int,
+      topAuthors: s.array(s.string),
+    })),
+    hasUnreleasedCommits: s.boolean,
+    totalTags: s.int,
+  }),
+});
+
+export default gitTagTimeline;
+```

skills/rig/samples/166-env-variable-type-inferrer.md

@@ -0,0 +1,44 @@
+# 166 - Env Variable Type Inferrer
+
+```rig
+import { agent, defineTool, p, s } from "rig";
+
+// Agent role: infer the type and purpose of each variable defined in a .env.example file.
+const envVariableTypeInferrer = agent({
+  model: "small",
+  instructions: p`Infer the type and purpose of each environment variable in the project.
+
+.env.example contents:
+${p.readOptional(".env.example")}
+
+.env.sample contents:
+${p.readOptional(".env.sample")}
+
+For each KEY=value pair found, use the inferType tool to classify the value type. Produce a description of each variable's likely purpose based on its name. Determine whether all variables appear to be documented (have a non-empty value or comment). Return only the declared output.`,
+  tools: [
+    defineTool("inferType", {
+      description: "Infer the type of an environment variable value",
+      parameters: s.object({ key: s.string, value: s.string }),
+      handler({ value }) {
+        const v = value.trim();
+        if (/^https?:\/\//i.test(v)) return { type: "url" as const };
+        if (/^\/|^\.\.?\//.test(v)) return { type: "path" as const };
+        if (/^(true|false)$/i.test(v)) return { type: "boolean" as const };
+        if (/^\d+(\.\d+)?$/.test(v)) return { type: "number" as const };
+        if (v === "") return { type: "unknown" as const };
+        return { type: "string" as const };
+      },
+    }),
+  ],
+  output: s.object({
+    variables: s.record(s.object({
+      type: s.enum("string", "number", "boolean", "url", "path", "unknown"),
+      description: s.string,
+    })),
+    totalCount: s.int,
+    allDocumented: s.boolean,
+  }),
+});
+
+export default envVariableTypeInferrer;
+```

skills/rig/samples/167-makefile-target-extractor.md

@@ -0,0 +1,48 @@
+# 167 - Makefile Target Extractor
+
+```rig
+import { agent, defineTool, p, s } from "rig";
+import { repair } from "rig/addons";
+
+// Agent role: extract and classify Makefile targets into phony vs real file targets with descriptions.
+const makefileTargetExtractor = agent({
+  model: "small",
+  instructions: p`Extract and classify all targets from the Makefile in this workspace.
+
+Makefile contents:
+${p.readOptional("Makefile")}
+
+Use the parseTargets tool to extract target names, then classify each. Phony targets are declared with .PHONY or have no corresponding file. Check if each target has an adjacent comment (##) for help text. Return only the declared output.`,
+  tools: [
+    defineTool("parseTargets", {
+      description: "Parse Makefile content and extract target names with their type",
+      parameters: s.object({ content: s.string }),
+      handler({ content }) {
+        const phonyTargets = new Set<string>();
+        const phonyMatch = content.match(/^\.PHONY\s*:(.*)/gm) || [];
+        for (const line of phonyMatch) {
+          line.replace(/^\.PHONY\s*:/, "").trim().split(/\s+/).forEach(t => phonyTargets.add(t));
+        }
+        const targetLines = content.match(/^([a-zA-Z0-9_-]+)\s*:/gm) || [];
+        const targets = targetLines
+          .map(l => l.replace(/:.*/, "").trim())
+          .filter(t => t && t !== ".PHONY");
+        return { targets, phonyTargets: [...phonyTargets] };
+      },
+    }),
+  ],
+  addons: [repair()],
+  output: s.object({
+    targets: s.array(s.object({
+      name: s.string,
+      isPhony: s.boolean,
+      hasHelp: s.boolean,
+      description: s.optional(s.string),
+    })),
+    totalCount: s.int,
+    phonyCount: s.int,
+  }),
+});
+
+export default makefileTargetExtractor;
+```