<p>I want to go from "vague idea of something neat to build" to
"well-scoped project with definite value, acceptance criteria, and
no remaining uncertainty." The first step is a PRD agent that
interviews me before it writes anything.</p>
<h1 id="why-a-prd-agent">Why a PRD agent</h1>
<p>I ran three Deep Research reports on AI-augmented PRDs and
AI-native SDLCs
(<a href="/wiki/research/ai-augmented-prds.html">notes</a>). One finding
kept showing up across all three: AI agents don't ask clarifying
questions. They assume. Hand a coding agent a vague idea and
it'll produce something plausible, polished, and wrong in ways
you won't notice until later.</p>
<p>The traditional PRD solves a different version of this problem.
A human engineer reads a vague spec and asks "what happens
when the user does X?" or "does this need to work offline?" An
AI agent fills those gaps with assumptions. All three research
reports converged on this: the biggest risk isn't bad output,
it's convincingly mediocre output that looks complete enough to
skip the hard thinking.</p>
<p>So the fix is an agent that does the asking. One that
interviews me first, pushes back on vague answers, and refuses
to write until it has real clarity.</p>
<h1 id="the-prd-writer">The PRD Writer</h1>
<p>The <a href="/wiki/agent-team/prd-writer.html">PRD Writer</a> is a Claude
Code agent that turns vague ideas into scoped PRDs. It runs on
Opus because it needs to recognize when an answer is too vague,
when goals contradict constraints, and when I'm hand-waving
instead of thinking.</p>
<p><img src="/images/agent-prd-writer.png" alt="PRD Writer, the Bowerbird"></p>
<h2 id="phase-1-interview">Phase 1: Interview</h2>
<p>The agent reads the project's
CLAUDE.md, the wiki, existing PRDs, and all agent definitions
for context. Then it asks me questions one at a time, covering
five categories: problem clarity, solution validation, success
criteria, constraints, and strategic fit.</p>
<p>One at a time matters. When questions come in batches, the
first two get real answers and the rest get skimmed. One
question, one answer,
then the agent decides what to ask next based on what I said.
It pushes back on contradictions, flags gaps, and won't accept
"make it better" as a success criterion.</p>
<p>The gate is explicit. When it has enough, it says "I have enough
to write a PRD. Proceeding to research." No ambiguity about
when the interview ends.</p>
<h2 id="phase-2-research">Phase 2: Research</h2>
<p>The agent delegates to a researcher subagent to gather facts on
the problem space. It also reads the wiki, codebase, and prior
PRDs to find existing patterns or infrastructure that could be
reused. The point is to ground the PRD in what actually exists,
not what the agent imagines.</p>
<h2 id="phase-3-write">Phase 3: Write</h2>
<p>It writes the PRD to the wiki using a standard <a href="/wiki/prds/template.html">template</a>. The
template has the sections that all three research reports agreed
on: problem, goal, success metrics, non-goals, user stories with
acceptance criteria, scope, open questions, and risks.</p>
<ul>
<li><strong>Non-goals come before scope.</strong> <a href="https://kevinyien.com/">Kevin Yien</a>'s
<a href="https://docs.google.com/document/d/1mEMDcHmtQ6twzNlpvF-9maNlAcezpWDtCnyIqWkODZs/edit">"perimeter of the solution space"</a> pattern. Draw
the boundary first, then fill it in. This
matters more for a solo dev than a team because there's no
one else to say "that's out of scope."</li>
<li><strong>Acceptance criteria live on each user story, not in a
separate section.</strong> Keeps them co-located with the context
that makes them meaningful. 3-5 per story, not 20. Addy
Osmani's <a href="https://addyosmani.com/blog/good-spec/">guide on specs for AI agents</a>
describes the failure mode: pile on too many criteria and
agents start ignoring or contradicting them.</li>
</ul>
<p>No implementation details in the PRD. That's the design doc's
job.</p>
<h1 id="using-it">Using it</h1>
<p>Start the agent directly:</p>
<pre><code class="language-bash">claude --agent prd-writer
</code></pre>
<p>Or describe a product idea to vanilla Claude and it'll
auto-delegate based on the agent's description field.</p>
<p>The output is a draft PRD at
<code>apps/blog/blog/markdown/wiki/prds/&#x3C;slug>.md</code>. Review it,
approve it, then hand it off to the Design Doc Writer.</p>
<h1 id="the-design-doc-writer">The Design Doc Writer</h1>
<p>The PRD answers "what and why." The <a href="/wiki/agent-team/design-doc-writer.html">Design Doc Writer</a>
answers "how," and produces output a coding agent can pick up
without interpretation.</p>
<p><img src="/images/agent-design-doc-writer.png" alt="Design Doc Writer, the Nautilus"></p>
<pre><code class="language-bash">claude --agent design-doc-writer
</code></pre>
<h2 id="the-gap-between-prds-and-code">The gap between PRDs and code</h2>
<p>A PRD says "the publisher pipeline should run autonomously in
K8s." A coding agent needs to know which files to create, what
interfaces to define, what depends on what, and in what order
to build it all.</p>
<p>Handing a PRD directly to a coding agent doesn't work. Agents
fill gaps with assumptions. The PRD says "use Claude Max
tokens" but doesn't say whether that means OAuth tokens, API
keys, or something else. A coding agent will pick one and keep
going. Three files later you realize it picked wrong.</p>
<p>The design doc takes the PRD's acceptance criteria and
translates them into architecture decisions, file change lists,
and ordered tasks through an interview, research, and
structured writing process.</p>
<h2 id="five-phases">Five phases</h2>
<p>The Design Doc Writer runs five gated phases:</p>
<pre class="mermaid">
graph LR
    A["Phase 0<br/>Discover PRD"] --> B["Phase 1<br/>Interview"]
    B --> C["Phase 2<br/>Research"]
    C --> D["Phase 3<br/>Write"]
    D --> E["Phase 4<br/>Validate"]
</pre>
<p><strong>Phase 0: Discover PRD.</strong> The agent finds and loads the target
PRD. If you don't specify one, it lists available PRDs from the
wiki and asks which one. It warns if the PRD's status is still
<code>draft</code> instead of <code>approved</code>.</p>
<p><strong>Phase 1: Interview.</strong> Same pattern as the PRD Writer, one
question at a time, but focused on architecture instead of
product clarity. Five categories: architecture constraints,
component boundaries, data model and flow, integration points,
and operational concerns. Cap is 12 questions. Gaps go into
the Open Questions section.</p>
<p><strong>Phase 2: Research.</strong> Delegates to a researcher subagent for
external context. Also reads the codebase, wiki, and prior
design docs for existing patterns to reuse.</p>
<p><strong>Phase 3: Write.</strong> Writes the design doc to the wiki using a
structured template.</p>
<p><strong>Phase 4: Validate.</strong> A separate subagent reads both the
design doc and the source PRD, checking that every acceptance
criterion maps to a task, no circular dependencies exist, and
no implementation code leaked in. Fixes issues before
finishing.</p>
<h2 id="the-template">The template</h2>
<p>The template has the sections all three Deep Research reports
agreed on as the minimum viable structure: context,
goals/non-goals, proposed design, alternatives considered, and
open questions. Two sections are specific to agent consumption.</p>
<p><strong>File Change List.</strong> An explicit table of every file to
create, modify, or delete:</p>
<pre><code class="language-markdown">| Action | File | Rationale |
|--------|------|-----------|
| CREATE | `path/to/new-file.ts` | Reason |
| MODIFY | `path/to/existing.ts` | Reason |
| DELETE | `path/to/old-file.ts` | Reason |
</code></pre>
<p>Two of the three research reports I ran
(<a href="/wiki/research/design-docs-for-agents.html">notes</a>) found
that file-level change lists improve agent implementation
quality. Both
<a href="https://githubnext.com/projects/copilot-workspace">Copilot Workspace</a>
and
<a href="https://cursor.com/blog/plan-mode">Cursor's Plan Mode</a>
implement this pattern. The third report (Gemini) noted a
dissenting view: some practitioners argue file-level lists
make docs brittle when frameworks change. The template
includes them because for a solo dev with a known codebase,
brittleness matters less than precision.</p>
<p><strong>Task Breakdown.</strong> Tasks are dependency-ordered, each with a
consistent structure:</p>
<pre><code class="language-markdown">### TASK-001: Create OAuth token manager

- **Requirement:** PRD Story 2, AC 1 (authenticate against
  Max subscription)
- **Files:** `src/auth/token-manager.ts`,
  `src/auth/token-manager.test.ts`
- **Dependencies:** None
- **Acceptance criteria:**
  - [ ] Token manager reads CLAUDE_CODE_OAUTH_TOKEN from env
  - [ ] Validates token format before use
  - [ ] Returns clear error on invalid/expired token

### TASK-002: Add network policy for publisher pod [P]

- **Requirement:** PRD Story 4, AC 2 (restrict network egress)
- **Files:** `k8s/publisher-netpol.yaml`
- **Dependencies:** TASK-001
- **Acceptance criteria:**
  - [ ] Allows egress only to api.anthropic.com,
        github.com, registry.npmjs.org
  - [ ] Denies all other egress
  - [ ] Policy applies only to publisher pods
</code></pre>
<p>Each task traces back to a PRD requirement. Files are listed
explicitly. Dependencies are declared so tasks can be executed
in order. The <code>[P]</code> marker means a task can run in parallel
with others at the same dependency level.</p>
<p>The acceptance criteria are checkboxes, not prose. A coding
agent (or a human) can verify each one independently.</p>
<h2 id="why-this-structure-matters">Why this structure matters</h2>
<p>Three findings from the
<a href="/wiki/research/design-docs-for-agents.html">research synthesis</a>
informed the template design.</p>
<p><strong>Agents re-propose rejected approaches.</strong>
<a href="https://www.mahdiyusuf.com/why-your-coding-agent-keeps-undoing-your-architecture/">Mahdi Yusuf</a>
calls this the "amnesiac agent" problem: an agent consolidated
three microservices into one because the separation "added
unnecessary complexity," but the separation existed because
the services scaled differently under load. The Alternatives
Considered section addresses this directly.</p>
<p><strong>Self-orchestrating agents fail on larger codebases.</strong>
<a href="https://medium.com/quantumblack/agentic-workflows-for-software-development-dc8e64f4a79d">McKinsey's QuantumBlack team</a>
published a two-layer architecture separating deterministic
orchestration from agent execution. Letting agents decide
their own sequencing led to "skipped steps, circular
dependencies, or analysis loops." The Task Breakdown's
explicit dependency ordering is the design doc's version of
that deterministic layer.</p>
<p><strong>Task granularity has a sweet spot.</strong>
<a href="https://arxiv.org/pdf/2509.16941">SWE-bench Pro</a> measures
this: models scoring 70%+ on SWE-bench Verified dropped to
roughly 23% on Pro's more complex multi-file edits. The
template targets tasks that are each a single coherent
change, testable in isolation.
<a href="https://boristane.com/blog/how-i-use-claude-code/">Boris Tane</a>
puts it well: "I want implementation to be boring. The
creative work happened in the annotation cycles."</p>
<h1 id="prd-to-design-doc-to-code">PRD to design doc to code</h1>
<p>The PRD Writer and Design Doc Writer form two stages of a
three-stage pipeline:</p>
<pre class="mermaid">
graph LR
    A["PRD Writer<br/><i>What & Why</i>"] --> B["Design Doc Writer<br/><i>How</i>"]
    B --> C["Claude Code Plan Mode<br/><i>Implementation</i>"]
</pre>
<ol>
<li><strong>PRD Writer</strong> interviews you, researches the problem
space, and writes a scoped PRD with acceptance criteria.</li>
<li><strong>Design Doc Writer</strong> takes that PRD, interviews you on
architecture, researches technical approaches, and writes
a design doc with ordered tasks.</li>
<li><strong>Claude Code</strong> reads the design doc's Task Breakdown and
executes each task in order, checking off acceptance
criteria as it goes.</li>
</ol>
<p>The third stage isn't automated yet. Today you'd copy the
Task Breakdown into a Claude Code session or reference the
design doc file in your prompt.</p>
<p>Invoking either agent:</p>
<pre><code class="language-bash">claude --agent prd-writer
claude --agent design-doc-writer
</code></pre>
<p>Or describe what you want and Claude will auto-delegate based
on the agent's description field.</p>
<h1 id="what-happened-when-the-design-doc-hit-reality">What happened when the design doc hit reality</h1>
<p>The task breakdown held up for the known work. TASK-001 through
TASK-008 executed mostly as written. Dependency ordering meant
clear starting points: validate OAuth first, build the image
second, wire up the controller third. Each task had explicit
acceptance criteria with checkboxes. An agent could pick up
TASK-003 without reading the whole doc because its inputs,
outputs, and dependencies were declared.</p>
<p>For these eight tasks, implementation was boring. That's the
point.</p>
<p>TASK-009, the deployment and end-to-end test, broke the plan.
Ten issues surfaced that the design doc couldn't have predicted:</p>
<ul>
<li>UID 1001 in the new runtime image vs UID 1000 on the workspace</li>
<li>Helm's field manager fighting kubectl patch over secret ownership</li>
<li>The QA subagent starting <code>next dev</code> in a pod with 1.5GB
available, hanging until OOMKill after 37 minutes</li>
<li>An import of <code>RemarkMermaid.js</code> that worked on macOS
(case-insensitive) and failed on Linux (case-sensitive)</li>
</ul>
<p>These were integration bugs. The design doc told you what to
build, not what would go wrong when you plugged it all together.</p>
<p>The design doc became a living document during deployment. An
"Implementation Additions" section appeared, documenting changes
that weren't in the original plan.</p>
<p>Per-branch PVCs replaced the shared workspace after stale state
leaked between runs. GitHub App auth replaced the placeholder
PAT. The google-news MCP server got dropped because the
journalist agent worked fine with WebSearch. The design doc
stopped being a static spec and started being a changelog of
decisions made under pressure.</p>
<p>The three-stage pipeline didn't need a fourth stage. Child
documents under the design doc captured per-task completion
notes and a deploy runbook. When the OOMKill bug hit, the
TASK-001 completion note already had the memory limits I'd
tested, so the fix was a one-line edit instead of a fresh
investigation. The design doc earned its keep during
deployment, not before it.</p>


<p>I wanted research-backed guidance for my Claude Code agents. I had
Claude read everything Anthropic has published on agent design, then
ran deep research reports from ChatGPT, Gemini, and Claude on the
same topic. Notes are in the wiki
(<a href="/wiki/research/anthropic-guidance.html">Anthropic guidance</a>,
<a href="/wiki/research/coding-agent-best-practices.html">deep research synthesis</a>).
Here's what I applied.</p>
<p>Some key findings:</p>
<ul>
<li><strong>Most multi-agent failures are specification problems</strong>, not
infrastructure. Bad task descriptions, ambiguous instructions,
missing termination conditions. Berkeley's
<a href="https://arxiv.org/abs/2503.13657">MAST taxonomy</a> analyzed
150+ tasks across 5 frameworks and found specification and
system design issues were the dominant failure category.</li>
<li><strong>Teach delegation.</strong> Give subagents an objective, output
format, tool/source guidance, and task boundaries. Without
all four, agents duplicate work or leave gaps.
(<a href="https://www.anthropic.com/engineering/multi-agent-research-system">Multi-Agent Research System</a>)</li>
<li><strong>Evaluators need isolated context.</strong> If the evaluator shares
context with the producer, it becomes "another participant
in collective delusion."
(<a href="https://www.anthropic.com/research/building-effective-agents">Building Effective Agents</a>)</li>
<li><strong>Start wide, then narrow.</strong> Agents default to overly specific
queries in unfamiliar territory. Begin with broad queries to
map what exists before drilling in.
(Gemini deep research,
<a href="/wiki/research/coding-agent-best-practices.html">wiki</a>)</li>
<li><strong>Action-oriented descriptions improve auto-delegation.</strong>
Trigger phrases like "MUST BE USED when..." in agent
descriptions help Claude decide when to invoke subagents.
(Claude deep research,
<a href="/wiki/research/coding-agent-best-practices.html">wiki</a>)</li>
<li><strong>Agents without browser tools ship half-working features.</strong>
Unit tests pass but the rendered page is broken. Playwright
catches what tests miss.
(<a href="https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents">Effective Harnesses</a>)</li>
<li><strong>Route models by risk, not task complexity.</strong> Opus for
judgment calls that are hard to verify. Sonnet for mechanical
work that's easy to check. A complex summarization is
low-risk because you can read and discard it. A one-line
security review is high-risk because getting it wrong has
consequences.
(<a href="https://www.anthropic.com/research/building-effective-agents">Building Effective Agents</a>,
all three deep research reports)</li>
<li><strong>Deny-by-default permissions.</strong> Start with no tool access
and progressively allowlist. The opposite of what most people
do (give the agent everything, restrict when something goes
wrong).
(<a href="https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents">Context Engineering</a>,
Claude deep research,
<a href="/wiki/research/coding-agent-best-practices.html">wiki</a>)</li>
<li><strong>The harness enforces termination, not the agent.</strong> Don't
rely on the agent to know when to stop. Set max iterations,
token budgets, and repetition detection in the system that
runs the agent.
(<a href="https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents">Effective Harnesses</a>,
Claude deep research,
<a href="/wiki/research/coding-agent-best-practices.html">wiki</a>)</li>
<li><strong>Write results to files, pass back references.</strong> Subagents
writing full output through the orchestrator bloats its
context window. Subagents should write to files and return
a summary and a path.
(<a href="https://www.anthropic.com/engineering/multi-agent-research-system">Multi-Agent Research System</a>)</li>
<li><strong>Research, plan, then implement.</strong> Without explicit
instructions, Claude jumps straight to coding. Say "read X,
then make a plan, then implement." Three phases, stated
explicitly. Claude won't reliably do them on its own.
(<a href="https://code.claude.com/docs/en/best-practices">Claude Code Best Practices</a>)</li>
<li><strong>One feature per prompt, commit after each piece.</strong> Agents
try to do everything and exhaust context mid-task. Commits
are rollback points. If the agent breaks something on step
3, you revert to step 2 instead of starting over.
(<a href="https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents">Effective Harnesses</a>)</li>
<li><strong>Agents use ~4x more tokens than chat. Multi-agent uses
~15x.</strong> Don't pay that unless the task needs it. Multi-agent
is an economic decision, not an architectural one.
(<a href="https://www.anthropic.com/engineering/multi-agent-research-system">Multi-Agent Research System</a>)</li>
<li><strong>Start simple, add layers only when measured outcomes
improve.</strong> The canonical agent loop is ~50 lines. Don't
build the full stack on day one.
(<a href="https://www.anthropic.com/research/building-effective-agents">Building Effective Agents</a>)</li>
</ul>
<p>Security baseline: the
<a href="https://genai.owasp.org/llm-top-10/">OWASP Top 10 for LLM Applications</a>.
All three deep research reports recommended it. I use it as a
checklist for the Security Auditor agent.</p>
<h1 id="2026-03-15s-agent-roster">2026-03-15's Agent Roster</h1>
<p>The agents from the
<a href="/agent-org-chart.html">org-chart post</a> were made off-the-cuff.
16 agents, too ambitious, didn't have the infrastructure to support
them. I deleted most and got down to 7. This time: I had Claude
load the deep research synthesis, I extracted the best practices
that applied, and I updated the agent definitions with specific,
traceable changes.</p>
<table>
<thead>
<tr>
<th>Agent</th>
<th>Model</th>
<th>Role &#x26; Applied Research</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="https://github.com/kylep/multi/blob/main/.claude/agents/publisher.md">Publisher</a></td>
<td>Opus</td>
<td>Content pipeline orchestration, writing. <a href="https://www.anthropic.com/engineering/multi-agent-research-system">Delegation specs</a>, trigger phrase.</td>
</tr>
<tr>
<td><a href="https://github.com/kylep/multi/blob/main/.claude/agents/analyst.md">Analyst</a></td>
<td>Opus</td>
<td>Research ingestion, system improvements. Trigger phrase.</td>
</tr>
<tr>
<td><a href="https://github.com/kylep/multi/blob/main/.claude/agents/synthesizer.md">Synthesizer</a></td>
<td>Opus</td>
<td>Compare/contrast Deep Research reports. No changes needed.</td>
</tr>
<tr>
<td><a href="https://github.com/kylep/multi/blob/main/.claude/agents/researcher.md">Researcher</a></td>
<td>Sonnet</td>
<td>Sourced facts, research briefs. <a href="/wiki/research/coding-agent-best-practices.html">Start wide, then narrow</a> search strategy, trigger phrase.</td>
</tr>
<tr>
<td><a href="https://github.com/kylep/multi/blob/main/.claude/agents/reviewer.md">Reviewer</a></td>
<td>Opus</td>
<td>Style, substance, sourcing. <a href="https://www.anthropic.com/research/building-effective-agents">Context isolation</a> from producer.</td>
</tr>
<tr>
<td><a href="https://github.com/kylep/multi/blob/main/.claude/agents/qa.md">QA</a></td>
<td>Sonnet</td>
<td>Build, render, links via <a href="https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents">Playwright</a>. Trigger phrase.</td>
</tr>
<tr>
<td><a href="https://github.com/kylep/multi/blob/main/.claude/agents/security-auditor.md">Security Auditor</a></td>
<td>Opus</td>
<td><a href="https://genai.owasp.org/llm-top-10/">OWASP LLM Top 10</a>, confidential data. Added LLM05 check.</td>
</tr>
</tbody>
</table>
<pre class="mermaid">
graph TD
    Claude["Vanilla Claude"]
    Publisher["Publisher (Opus)"]
    Analyst["Analyst (Opus)"]
    Synthesizer["Synthesizer (Opus)"]
    Researcher["Researcher (Sonnet)"]
    Reviewer["Reviewer (Opus)"]
    QA["QA (Sonnet)"]
    Security["Security Auditor (Opus)"]

    Claude --> Publisher
    Claude --> Analyst
    Claude --> Synthesizer
    Claude --> Researcher
    Claude --> Reviewer
    Claude --> QA
    Claude --> Security
    Publisher --> Researcher
    Publisher --> Reviewer
    Publisher --> QA
    Publisher --> Security
</pre>
<p>Three report directly to me (Publisher, Analyst, Synthesizer).
Four are subagents under Publisher. Model routing follows the
research: Opus for judgment calls (review, security, editorial,
synthesis), Sonnet for mechanical work (research, QA).</p>
<h2 id="calling-the-agents">Calling the agents</h2>
<p>Three ways to use them:</p>
<p><strong>Vanilla Claude auto-delegates.</strong> Each agent definition has a
<code>description</code> field that Claude reads when deciding whether to
spawn a subagent. The trigger phrases ("MUST BE USED when
writing blog posts", "MUST BE USED when gathering facts") tell
Claude when to invoke each one. If I ask vanilla Claude to
write a blog post, it sees the Publisher's description and
delegates. It can also run multiple subagents in parallel
when the tasks are independent.</p>
<p><strong>CLAUDE.md tells Claude what's available.</strong> The project's
<code>CLAUDE.md</code> includes a section listing all 7 agents with their
roles and invocation commands. This gives vanilla Claude the
full picture of what agents exist without having to discover
them from the file system.</p>
<p><strong><code>claude --agent publisher</code> for the full pipeline.</strong> This
starts Claude with the Publisher's system prompt as the main
thread. Publisher then orchestrates the entire content
pipeline: research, substance gate, write, review, QA,
security audit. It spawns each subagent natively using Claude
Code's Agent tool, not CLI calls. Independent stages (QA and
security audit) run in parallel. This is the heavy path for
writing a full post from scratch.</p>
<p>Claude Code enforces a single-level subagent hierarchy.
Publisher can spawn subagents, but those subagents can't
spawn their own. If Reviewer needs research, it doesn't call
Researcher. It reports back to Publisher, which decides
what to do next.</p>


<p>This is a companion to the <a href="/ga4-mcp.html">GA4 MCP post</a>. Same idea,
different service. Cloudflare ships a remote MCP server that covers
their entire API. You connect it to Claude Code, authenticate via
OAuth in your browser, and then Claude can query your Cloudflare
account directly.</p>
<p>I <a href="/dns-xfer-godaddy-cloudflare.html">moved my DNS to Cloudflare</a> a
while back and use the CDN proxy on
<a href="https://kyle.pericak.com">kyle.pericak.com</a>. The MCP server lets me
check DNS records, zone settings, and account details without opening
the dashboard. Read-only access is fine for this.</p>
<h1 id="how-it-works">How it works</h1>
<p>Cloudflare's MCP server is different from most. It has
<a href="https://developers.cloudflare.com/api/">thousands of API endpoints</a>,
but instead of exposing one tool per endpoint, it exposes two:
<code>search</code> and <code>execute</code>.</p>
<p><code>search</code> queries the OpenAPI spec to find the right endpoint.
<code>execute</code> runs JavaScript code server-side against the Cloudflare
API using a
<a href="https://github.com/cloudflare/mcp"><code>cloudflare.request()</code></a>
function. Claude writes the code, the server runs it, and the
result comes back.</p>
<p>Cloudflare calls this
"<a href="https://blog.cloudflare.com/code-mode-mcp/">Code Mode</a>."
The full Cloudflare API (2,500+ endpoints) fits in about 1,000
tokens of tool definitions instead of 1.17 million for native
MCP with full schemas.</p>
<h1 id="one-command-to-connect">One command to connect</h1>
<pre><code class="language-bash">claude mcp add --transport http cloudflare-api \
  https://mcp.cloudflare.com/mcp
</code></pre>
<p>This adds the server to your <code>~/.claude.json</code> under the current
project. Restart Claude Code and run <code>/mcp</code> to confirm it shows up.</p>
<h2 id="oauth">OAuth</h2>
<p>The first time Claude calls a Cloudflare tool, your browser opens to
an authorization page. You pick an access level:</p>
<ul>
<li><strong>Read Only</strong> (recommended): view resources without making changes</li>
<li><strong>Workers Full Access</strong>: full access to Workers, KV, D1, R2</li>
<li><strong>DNS Full Access</strong>: full access to DNS records and zone settings</li>
<li><strong>Advanced</strong>: pick individual permissions</li>
</ul>
<p>You can always re-auth later with broader
permissions if you need to manage Workers or edit DNS from the
terminal.</p>
<p>After you log in and grant access, the OAuth token is cached
in <code>~/.mcp-auth/</code> (by the
<a href="https://github.com/geelen/mcp-remote">mcp-remote</a> transport
layer). Delete that directory to force re-authentication or
change access levels.</p>
<h1 id="querying-my-account">Querying my account</h1>
<h2 id="list-zones">List zones</h2>
<pre><code>> What zones do I have in Cloudflare?
</code></pre>
<p>Claude called <code>execute</code> with code that hit <code>GET /zones</code> and returned:</p>
<table>
<thead>
<tr>
<th>Zone</th>
<th>Status</th>
</tr>
</thead>
<tbody>
<tr>
<td>example.com</td>
<td>active</td>
</tr>
<tr>
<td>example.info</td>
<td>active</td>
</tr>
</tbody>
</table>
<h2 id="dns-records">DNS records</h2>
<pre><code>> Show me the DNS records for example.com
</code></pre>
<p>This one appears the most useful. Sanitized sample from the
full output:</p>
<table>
<thead>
<tr>
<th>Type</th>
<th>Name</th>
<th>Content</th>
<th>Proxied</th>
</tr>
</thead>
<tbody>
<tr>
<td>A</td>
<td>example.com</td>
<td>198.51.100.1</td>
<td>No</td>
</tr>
<tr>
<td>CNAME</td>
<td>blog.example.com</td>
<td>c.storage.googleapis.com</td>
<td>Yes</td>
</tr>
<tr>
<td>MX</td>
<td>example.com</td>
<td>example-com.mail.protection.outlook.com</td>
<td>No</td>
</tr>
<tr>
<td>TXT</td>
<td>example.com</td>
<td>v=spf1 include:spf.protection.outlook.com -all</td>
<td>No</td>
</tr>
</tbody>
</table>
<p>The blog subdomain is proxied through Cloudflare (the orange cloud),
pointing at a GCS bucket. The root domain has A records from a
previous setup. The MX and TXT records are for email.</p>
<p>Useful when debugging
<a href="/cloudflare-https-frontend.html">certificate issues</a> or verifying
propagation after a change.</p>
<h2 id="zone-details">Zone details</h2>
<pre><code>> What are the nameservers for example.com?
</code></pre>
<p>It returned the two Cloudflare nameservers assigned to the zone,
plus the creation date and plan tier.</p>
<h2 id="what-else-to-ask-it">What else to ask it</h2>
<p>DNS lookups are the obvious use, but the full API means you can
ask about things you'd otherwise dig through the dashboard for:</p>
<ul>
<li>"Is Cloudflare proxying blog.example.com or is it DNS-only?"</li>
<li>"Do I have any DNS records still pointing at my old hosting
IP?"</li>
<li>"Show me all TXT records across all my zones"</li>
<li>"What Workers do I have deployed?"</li>
<li>"Compare the DNS records for example.com and example.info"</li>
<li>"Are there any firewall events for my zone?"</li>
<li>"What countries is my traffic coming from right now?"</li>
</ul>
<h1 id="product-specific-servers">Product-specific servers</h1>
<p>The main <code>mcp.cloudflare.com/mcp</code> endpoint covers the entire API,
but Cloudflare also ships
<a href="https://developers.cloudflare.com/agents/model-context-protocol/mcp-servers-for-cloudflare/">focused MCP servers</a>
for individual products:</p>
<ul>
<li><strong>DNS Analytics</strong>: <code>dns-analytics.mcp.cloudflare.com/mcp</code></li>
<li><strong>Observability</strong>: <code>observability.mcp.cloudflare.com/mcp</code></li>
<li><strong>Workers Builds</strong>: <code>builds.mcp.cloudflare.com/mcp</code></li>
<li><strong>Radar</strong>: <code>radar.mcp.cloudflare.com/mcp</code> (internet traffic
data)</li>
<li><strong>Browser Rendering</strong>: <code>browser.mcp.cloudflare.com/mcp</code></li>
</ul>
<p>Same transport, same <code>claude mcp add --transport http</code> setup.
The main server is enough for general use.</p>
<h1 id="compared-to-the-ga4-mcp-server">Compared to the GA4 MCP server</h1>
<p>The <a href="/ga4-mcp.html">GA4 MCP server</a> runs locally via <code>pipx</code>, uses
Google Application Default Credentials, and exposes five specific
tools. Setting it up requires enabling GCP APIs and running
<code>gcloud auth</code>.</p>
<p>The Cloudflare MCP is a remote server. No local install, no API
keys to manage. OAuth in the browser and you're done. The tradeoff
is you need network access to <code>mcp.cloudflare.com</code> and the
server's availability depends on Cloudflare.</p>
<p>The two-tool design (search + execute) is interesting. It means Claude
has to write JavaScript to query the API. But it
also means the responses are raw API output rather than pre-formatted
tool results. For most queries that's fine.</p>


<h2 id="table-of-contents">Table of contents</h2>
<ul>
<li><a href="#why-one-router">Why one router</a>
<ul>
<li><a href="#claudes-token-efficiencies">Claude's token efficiencies</a></li>
</ul>
</li>
<li><a href="#getting-an-openrouter-key">Getting an OpenRouter key</a></li>
<li><a href="#claude-code">Claude Code</a></li>
<li><a href="#opencode">OpenCode</a>
<ul>
<li><a href="#what-didnt-work">What didn't work</a></li>
<li><a href="#what-worked">What worked</a></li>
</ul>
</li>
<li><a href="#openclaw">OpenClaw</a></li>
<li><a href="#custom-openrouter-usage-mcp">Custom OpenRouter Usage MCP</a>
<ul>
<li><a href="#registering-it">Registering it</a></li>
<li><a href="#usage-output">Usage output</a></li>
<li><a href="#model-pricing-snapshot">Model pricing snapshot</a></li>
</ul>
</li>
</ul>
<h1 id="why-one-router">Why one router</h1>
<p>I run three AI tools regularly: Claude Code, OpenCode,
and OpenClaw. Each has its own API key, its own billing
dashboard, and its own model config. Anthropic bills
Claude Code. Google bills OpenClaw's Gemini usage.
OpenCode can talk to either.</p>
<p>That's three places to check spend, three sets of rate
limits, and no single view of what I'm burning through.
OpenRouter fixes this. It's a proxy that sits between
your tools and the model providers. You get one API key,
one billing dashboard, and the ability to swap models
without changing provider credentials.</p>
<p>The tradeoff is a small markup on token costs and an
extra network hop. For a personal setup where I want
visibility and flexibility, that's fine.</p>
<h2 id="claudes-token-efficiencies">Claude's token efficiencies</h2>
<p>Anthropic's Pro and Max plans include Claude Code
usage at a steep discount compared to raw API pricing.
Pro is $20/month with generous token allowances. Max
plans scale up from there. If you only use Claude Code,
the Pro plan is the cheapest way to run it.</p>
<p>The problem is that those plan tokens only work with
Claude Code through Anthropic's direct API. OpenCode
and OpenClaw are third-party tools. They can call
Claude models, but not through your Pro subscription.
They hit the standard API and bill at full rate.</p>
<p>So the choice is: keep Claude Code on the Pro plan
(cheapest for that one tool) and manage the other two
separately, or route everything through OpenRouter and
get unified billing at API rates. I went with
OpenRouter because the visibility across all three
tools matters more to me than the per-token savings
on Claude Code alone.</p>
<h1 id="getting-an-openrouter-key">Getting an OpenRouter key</h1>
<ol>
<li>Sign up at <a href="https://openrouter.ai">openrouter.ai</a></li>
<li>Go to Settings > Keys and create a new API key</li>
<li>Add credits (pay-as-you-go, no minimum)</li>
</ol>
<p>OpenRouter gave me $100 in free credits as a signup
promo. That's a lot of tokens to experiment with before
committing any money.</p>
<p>Set the key in your shell:</p>
<pre><code class="language-bash">export OPENROUTER_API_KEY="sk-or-v1-..."
</code></pre>
<p>Add it to your <code>~/.zshrc</code> or <code>~/.bashrc</code> so it persists.
The same key works for every tool below.</p>
<p>OpenRouter's <a href="https://openrouter.ai/models">models page</a>
shows per-token pricing for every model. Useful for
comparing costs before swapping models around.</p>
<h1 id="claude-code">Claude Code</h1>
<p>Claude Code normally talks directly to Anthropic's API.
To route it through OpenRouter, you override the base
URL and auth token via environment variables:</p>
<pre><code class="language-bash">ANTHROPIC_BASE_URL="https://openrouter.ai/api" \
ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY" \
ANTHROPIC_API_KEY="" \
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 \
claude
</code></pre>
<p>Four variables. <code>ANTHROPIC_BASE_URL</code> points Claude Code
at OpenRouter instead of Anthropic. <code>ANTHROPIC_AUTH_TOKEN</code>
passes your OpenRouter key. <code>ANTHROPIC_API_KEY</code> must be
set to an empty string, otherwise Claude Code tries to
use it and the auth conflicts.
<code>CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC</code> stops
telemetry calls that would fail against OpenRouter.</p>
<p>That's verbose to type every time. I wrapped it in a
shell function:</p>
<pre><code class="language-bash"># ~/.zshrc
orclaude() {
  ANTHROPIC_BASE_URL="https://openrouter.ai/api" \
  ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY" \
  ANTHROPIC_API_KEY="" \
  CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 \
  claude "$@"
}
</code></pre>
<p>Now <code>orclaude</code> launches Claude Code through OpenRouter.
Regular <code>claude</code> still uses the Anthropic API directly.</p>
<p>You can also swap models. Claude Code has three model
slots (Opus, Sonnet, Haiku) that you can override:</p>
<pre><code class="language-bash">export ANTHROPIC_DEFAULT_SONNET_MODEL=\
  "google/gemini-2.5-pro"
export ANTHROPIC_DEFAULT_HAIKU_MODEL=\
  "google/gemini-2.5-flash"
</code></pre>
<p>Any model on OpenRouter that supports tool use works.
Models without tool use will break Claude Code since
it relies on tools for file reading, editing, and
command execution.</p>
<h1 id="opencode">OpenCode</h1>
<p>OpenCode has native OpenRouter support.</p>
<h2 id="what-didnt-work">What didn't work</h2>
<p>I tried putting the API key in <code>opencode.json</code>. It passed config validation but
OpenCode still tried to bill through its own payment system. "No payment method" error
pointing at OpenCode's billing page, not OpenRouter's.</p>
<h2 id="what-worked">What worked</h2>
<p>OpenCode picks up <code>OPENROUTER_API_KEY</code> from the environment automatically. The config
file only needs the model names. <code>opencode.json</code> goes in the project root where you
launch it, or the global <code>~/.config/opencode/opencode.json</code>.</p>
<pre><code class="language-json">{
  "model": "openrouter/anthropic/claude-sonnet-4-6",
  "small_model": "openrouter/anthropic/claude-haiku-4-5"
}
</code></pre>
<p>The key has to be registered through OpenCode's auth system. Inside the TUI:</p>
<ol>
<li>Run <code>/connect</code></li>
<li>Search for "OpenRouter"</li>
<li>Paste your API key</li>
</ol>
<p>After that, OpenCode routes through OpenRouter. The
<code>openrouter/</code> prefix on model names tells it which
provider to use.</p>
<p>Note: OpenCode shows a warning when you select
OpenRouter saying requests "will often be routed to
subpar providers." That feels like they're trying to just sell their own model hosting.</p>
<h1 id="openclaw">OpenClaw</h1>
<p>OpenClaw has native OpenRouter support. The model
reference format is <code>openrouter/&#x3C;provider>/&#x3C;model></code>,
same as OpenCode.</p>
<p>In OpenClaw's home directory, <code>openclaw.json</code>, for the K8s setup
<code>/home/node/.openclaw/openclaw.json</code> (the PVC mount). For a local install it'd be
<code>~/.openclaw/openclaw.json.</code>:</p>
<pre><code class="language-json5">{
  env: { OPENROUTER_API_KEY: "sk-or-..." },
  agents: {
    defaults: {
      model: {
        primary: "openrouter/anthropic/claude-sonnet-4-6"
      },
    },
  },
}
</code></pre>
<p>Or use the CLI:</p>
<pre><code class="language-bash">openclaw onboard \
  --auth-choice apiKey \
  --token-provider openrouter \
  --token "$OPENROUTER_API_KEY"
</code></pre>
<p>Since my OpenClaw runs in K8s with secrets injected via
Vault, I added <code>OPENROUTER_API_KEY</code> to the Vault secret
and updated the Vault Agent template to export it. Same
pattern as the
<a href="/openclaw-linear-skill.html">Linear API key</a> from the
previous post.</p>
<p>After redeploying, I cleared my OpenClaw agent's sessions (OpenClaw
caches the model config per session) and asked what
model it was running:</p>
<pre><code class="language-text">Claude: What model are you running on?
Pai: I'm running on Claude Sonnet 4.6 via OpenRouter
  (openrouter/anthropic/claude-sonnet-4-6).
</code></pre>
<p>Previously Pai ran Gemini 2.5 Flash through Google's
API directly. Now it's Claude Sonnet 4.6 through
OpenRouter. Same Vault-injected credentials pattern,
different model, one billing dashboard.</p>
<p>The Linear skill still works through the new model.
Pai listed my teams and issues the same as before.
The skill's curl commands don't care which model is
driving the agent.</p>
<h1 id="custom-openrouter-usage-mcp">Custom OpenRouter Usage MCP</h1>
<p>With everything routed through OpenRouter, I wanted
to check my spend without leaving the terminal. OpenRouter
has a billing API, so I built a small
<a href="https://github.com/kylep/multi/tree/main/apps/mcp-servers/openrouter">MCP server</a>
that queries it.</p>
<p>The server has two tools. <code>get_usage</code> calls the
<code>/api/v1/key</code> endpoint and returns daily, weekly, monthly,
and total spend plus remaining credits. <code>get_model_pricing</code>
calls <code>/api/v1/models</code> and shows per-million-token costs,
with an optional filter to search by model name.</p>
<p>The whole thing is one TypeScript file using the MCP SDK
with stdio transport. It reads <code>OPENROUTER_API_KEY</code> from
the environment, same key the other tools already use.</p>
<h2 id="registering-it">Registering it</h2>
<p>In <code>~/.claude.json</code>, under the project's <code>mcpServers</code>:</p>
<pre><code class="language-json">"openrouter": {
  "type": "stdio",
  "command": "node",
  "args": [
    "/path/to/openrouter-mcp/build/index.js"
  ]
}
</code></pre>
<p>No <code>env</code> block needed. Claude Code spawns it as a child
process, which inherits the shell environment.</p>
<h2 id="usage-output">Usage output</h2>
<p>After restarting Claude Code, I asked it to check my
OpenRouter usage:</p>
<pre><code class="language-text">Key: sk-or-v1-3fd...374
Free tier: no

Usage:
  Today:  $0.5467
  Week:   $0.5467
  Month:  $0.5467
  Total:  $0.5467

Credit limit:
  Limit:     $200.0000
  Remaining: $199.4533
</code></pre>
<p>That $0.55 is from a few hours of Claude Code and
OpenCode use. The $200 limit is what I set on the key
in OpenRouter's dashboard.</p>
<p>The pricing tool is useful for comparing models before
switching. Searching "claude-sonnet-4" shows all the
Sonnet variants and their per-million-token rates side
by side.</p>
<h2 id="model-pricing-snapshot">Model pricing snapshot</h2>
<p>Pulled from <code>get_model_pricing</code> on 2026-03-10:</p>
<table>
<thead>
<tr>
<th>Model</th>
<th>Prompt</th>
<th>Completion</th>
<th>Context</th>
</tr>
</thead>
<tbody>
<tr>
<td>openai/gpt-5.4-pro</td>
<td>$30.00/M</td>
<td>$180.00/M</td>
<td>1050k</td>
</tr>
<tr>
<td>openai/gpt-5.4</td>
<td>$2.50/M</td>
<td>$15.00/M</td>
<td>1050k</td>
</tr>
<tr>
<td>openai/gpt-5.3-codex</td>
<td>$1.75/M</td>
<td>$14.00/M</td>
<td>400k</td>
</tr>
<tr>
<td>openai/gpt-5.2-pro</td>
<td>$21.00/M</td>
<td>$168.00/M</td>
<td>400k</td>
</tr>
<tr>
<td>openai/gpt-5.1</td>
<td>$1.25/M</td>
<td>$10.00/M</td>
<td>400k</td>
</tr>
<tr>
<td>anthropic/claude-opus-4.6</td>
<td>$5.00/M</td>
<td>$25.00/M</td>
<td>1000k</td>
</tr>
<tr>
<td>anthropic/claude-sonnet-4.6</td>
<td>$3.00/M</td>
<td>$15.00/M</td>
<td>1000k</td>
</tr>
<tr>
<td>anthropic/claude-haiku-4.5</td>
<td>$1.00/M</td>
<td>$5.00/M</td>
<td>200k</td>
</tr>
<tr>
<td>anthropic/claude-opus-4</td>
<td>$15.00/M</td>
<td>$75.00/M</td>
<td>200k</td>
</tr>
<tr>
<td>anthropic/claude-sonnet-4</td>
<td>$3.00/M</td>
<td>$15.00/M</td>
<td>200k</td>
</tr>
<tr>
<td>google/gemini-3.1-pro-preview</td>
<td>$2.00/M</td>
<td>$12.00/M</td>
<td>1049k</td>
</tr>
<tr>
<td>google/gemini-2.5-pro</td>
<td>$1.25/M</td>
<td>$10.00/M</td>
<td>1049k</td>
</tr>
<tr>
<td>google/gemini-2.5-flash</td>
<td>$0.30/M</td>
<td>$2.50/M</td>
<td>1049k</td>
</tr>
<tr>
<td>google/gemini-2.5-flash-lite</td>
<td>$0.10/M</td>
<td>$0.40/M</td>
<td>1049k</td>
</tr>
<tr>
<td>deepseek/deepseek-v3.2</td>
<td>$0.25/M</td>
<td>$0.40/M</td>
<td>164k</td>
</tr>
<tr>
<td>deepseek/deepseek-r1-0528</td>
<td>$0.45/M</td>
<td>$2.15/M</td>
<td>164k</td>
</tr>
<tr>
<td>meta-llama/llama-4-maverick</td>
<td>$0.15/M</td>
<td>$0.60/M</td>
<td>1049k</td>
</tr>
<tr>
<td>mistralai/mistral-large-2512</td>
<td>$0.50/M</td>
<td>$1.50/M</td>
<td>262k</td>
</tr>
<tr>
<td>qwen/qwen3.5-397b-a17b</td>
<td>$0.39/M</td>
<td>$2.34/M</td>
<td>262k</td>
</tr>
<tr>
<td>qwen/qwen3-coder-plus</td>
<td>$0.65/M</td>
<td>$3.25/M</td>
<td>1000k</td>
</tr>
</tbody>
</table>
<p>Prices are per million tokens. These change often.
Check OpenRouter's models page for current rates.</p>


<h2 id="table-of-contents">Table of contents</h2>
<ul>
<li><a href="#why-i-dont-trust-the-skill-marketplace">Why I don't trust the skill marketplace</a></li>
<li><a href="#how-openclaw-skills-work">How OpenClaw skills work</a></li>
<li><a href="#the-skill">The skill</a></li>
<li><a href="#one-ai-writing-tools-for-another">One AI writing tools for another</a></li>
<li><a href="#loading-it-into-k8s">Loading it into K8s</a>
<ul>
<li><a href="#injecting-the-api-key">Injecting the API key</a></li>
<li><a href="#mounting-the-skill">Mounting the skill</a></li>
<li><a href="#the-jq-problem">The jq problem</a></li>
<li><a href="#stale-sessions">Stale sessions</a></li>
</ul>
</li>
<li><a href="#talking-to-pai-pericak-ai">Talking to Pai (Pericak AI)</a></li>
</ul>
<h1 id="why-i-dont-trust-the-skill-marketplace">Why I don't trust the skill marketplace</h1>
<p>In the <a href="/openclaw-k8s.html">K8s post</a> I mentioned wanting
to connect OpenClaw to Linear for issue tracking. The
obvious path is ClawHub, OpenClaw's public skill
marketplace. Install a community skill, set your API key,
done. I didn't do that.</p>
<p>In February 2026, a campaign called
<a href="https://cybersecuritynews.com/clawhavoc-poisoned-openclaws-clawhub/">ClawHavoc</a>
compromised ClawHub. Researchers at Trend Micro and Antiy
documented over 1,184 malicious skills that had been
published to the registry. The skills looked legitimate,
had normal names and descriptions, and passed ClawHub's
automated checks. They distributed
<a href="https://www.trendmicro.com/en_us/research/26/b/openclaw-skills-used-to-distribute-atomic-macos-stealer.html">Atomic macOS Stealer</a>,
a credential harvester targeting Keychain, browser
passwords, and crypto wallets.</p>
<p>The publishing bar was low. A one-week-old GitHub account
was enough to push a skill to ClawHub. No code review, no
signing, no sandbox. Once installed, a skill runs inside
the agent process with access to every environment variable
the agent has. That includes API keys, tokens, and anything
else injected via Vault or config.</p>
<p>This is the same pattern that hit npm, PyPI, and VS Code
extensions. A package registry with low friction publishing
and high-privilege execution is a target. ClawHub is no
different.</p>
<p>My approach: write the skill myself, keep it in my repo,
and audit every line. The Linear skill I need is about 150
lines of markdown. That's a small surface to own compared
to trusting a stranger's code with my credentials.</p>
<h1 id="how-openclaw-skills-work">How OpenClaw skills work</h1>
<p>An OpenClaw skill is a directory with a <code>SKILL.md</code> file.
The file has YAML frontmatter (name, description, required
tools and environment variables) and a markdown body with
instructions the agent follows.</p>
<p>There's no compiled code. No dependencies to install. No
background process. The agent reads the markdown, learns
what commands are available, and executes them via bash
when you ask it to. If you want to audit a skill, you read
one file.</p>
<p>Compare this to MCP servers, which are running processes
that the agent connects to over a transport protocol. MCP
servers can do more (stateful connections, streaming), but
they're also harder to audit and have a larger attack
surface. For something like "list my Linear issues," a
static document with curl commands is plenty.</p>
<p>The frontmatter declares what the skill needs:</p>
<pre><code class="language-yaml">---
name: linear
description: Manage Linear issues, projects,
  and comments via the Linear GraphQL API.
metadata: {"openclaw": {"emoji": "📐",
  "requires": {"bins": ["curl"],
  "env": ["LINEAR_API_KEY"]}}}
---
</code></pre>
<p>OpenClaw checks these requirements at load time. If <code>curl</code>
isn't on PATH, or <code>LINEAR_API_KEY</code> isn't set, the skill
doesn't load. No runtime errors, no mysterious failures.</p>
<h1 id="the-skill">The skill</h1>
<p>I had Claude write a Linear skill covering the operations
I actually use: listing issues, creating and updating them,
managing labels, and adding comments. The full skill lives
at <code>apps/openclaw-skills/linear/SKILL.md</code> in my monorepo.</p>
<p>Linear's API is GraphQL-only. No REST endpoints. Every
request is a POST to <code>https://api.linear.app/graphql</code> with
a JSON body containing the query. The skill uses <code>curl</code>
for HTTP. One API key, no OAuth dance.</p>
<p>The auth header is <code>Authorization: $LINEAR_API_KEY</code>.
Linear personal API keys don't use a <code>Bearer</code> prefix.</p>
<p>Here's what listing issues looks like:</p>
<pre><code class="language-bash">curl -s -X POST https://api.linear.app/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: $LINEAR_API_KEY" \
  -d '{"query": "{ issues(filter: { team: \
    { key: { eq: \"PER\" } } }, first: 25) \
    { nodes { id identifier title \
    state { name } } } }"}'
</code></pre>
<p>And creating an issue:</p>
<pre><code class="language-bash">curl -s -X POST https://api.linear.app/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: $LINEAR_API_KEY" \
  -d '{"query": "mutation { issueCreate(input: \
    { teamId: \"TEAM_UUID\", \
    title: \"Issue title\", \
    description: \"Issue description\" }) \
    { success issue { id identifier url } } }"}'
</code></pre>
<p>The skill also covers workflow statuses. Changing an
issue's status in Linear means looking up the target
state's UUID first, then passing it to <code>issueUpdate</code>. The
agent chains these naturally: list statuses, find the one
named "Todo", grab its ID, update the issue.</p>
<p>This matches the workflow I described in the
<a href="/linear-mcp.html">Linear MCP post</a>. Nightly agents create
Suggestion issues in Backlog, I promote the good ones to
Todo, working agents pick them up. The skill gives OpenClaw
the same Linear access that Claude Code gets through its
MCP server.</p>
<p>The full skill is about 150 lines of markdown. Ten
operations with copy-paste curl commands and a few compound
examples at the end. I read every line.</p>
<h1 id="one-ai-writing-tools-for-another">One AI writing tools for another</h1>
<p>Claude Code (Opus 4.6) wrote this skill. It read the
Trello skill as a pattern, checked the Linear GraphQL API
docs, and produced a skill that follows the same structure.
One AI building capabilities for another AI.</p>
<p>I described what I wanted at a high level, and Claude
handled the GraphQL query syntax, the jq filters, and the
escape sequences. I reviewed the output. The whole thing
took one conversation.</p>
<p>The skill lives in my monorepo under version control. If
Linear changes their API or I need a new operation, I
update one file.</p>
<h1 id="loading-it-into-k8s">Loading it into K8s</h1>
<p>Getting the skill into the running OpenClaw pod took more
work than writing it. The skill file needs to end up in
the right directory inside the container, the API key
needs to be injected, and OpenClaw needs to discover it.</p>
<h2 id="injecting-the-api-key">Injecting the API key</h2>
<p>I added the Linear API key to Vault alongside the existing
Gemini and Telegram secrets, then updated the Vault Agent
template to export it:</p>
<pre><code class="language-text">{{- with secret "secret/openclaw" -}}
export GEMINI_API_KEY="{{ .Data.data.gemini_api_key }}"
export TELEGRAM_BOT_TOKEN="..."
{{ if .Data.data.linear_api_key }}
export LINEAR_API_KEY="{{ .Data.data.linear_api_key }}"
{{ end }}
{{- end }}
</code></pre>
<h2 id="mounting-the-skill">Mounting the skill</h2>
<p>I stored the SKILL.md in a ConfigMap and mounted it into
the init container. ConfigMap mounts use symlinks
internally, and OpenClaw's skill loader rejects symlinked
paths as a security measure. So the init container copies
the file onto the PVC as a regular file:</p>
<pre><code class="language-yaml">initContainers:
  - name: config-seed
    command: ["sh", "-c"]
    args:
      - |
        # ... existing config seed logic ...
        # Copy skills onto PVC workspace
        mkdir -p /data/workspace/skills/linear
        cp /skill-src/linear/SKILL.md \
          /data/workspace/skills/linear/SKILL.md
    volumeMounts:
      - name: linear-skill
        mountPath: /skill-src/linear
        readOnly: true
</code></pre>
<p>The key detail: skills must live under the workspace
directory (<code>&#x3C;workspace>/skills/</code>), not just anywhere on
the filesystem. OpenClaw's skill discovery only scans
three locations: bundled, managed (<code>~/.openclaw/skills</code>),
and workspace. I initially tried <code>extraDirs</code> and the
managed path. Neither worked until I put it in the
workspace.</p>
<h2 id="the-jq-problem">The jq problem</h2>
<p>The original skill required both <code>curl</code> and <code>jq</code> in its
<code>requires.bins</code> frontmatter. The OpenClaw container has
<code>curl</code> but not <code>jq</code>. The skill gating check runs at
startup: missing binary means the skill silently doesn't
load. Claude dropped <code>jq</code> from the requirements. The agent
is smart enough to parse JSON responses on its own using
the <code>node</code> binary that's already in the container.</p>
<h2 id="stale-sessions">Stale sessions</h2>
<p>After all that, I asked Pai what skills it had. Still
three. OpenClaw snapshots eligible skills when a session
starts and reuses that list for the session's lifetime.
The <code>openclaw agent --message</code> CLI command was reusing an
existing session from before the skill was loaded.
Clearing the sessions directory forced a fresh snapshot:</p>
<pre><code class="language-bash">rm -rf /home/node/.openclaw/agents/main/sessions/*
</code></pre>
<p>After that, the skill appeared.</p>
<h1 id="talking-to-pai-pericak-ai">Talking to Pai (Pericak AI)</h1>
<p>With the skill loaded, Claude Code talked to Pai (the
OpenClaw agent running Gemini 2.5 Flash) through
<code>kubectl exec</code>, using the same pattern from the
<a href="/openclaw-k8s.html">K8s post</a>.</p>
<pre><code class="language-text">Claude: List my Linear teams using the linear skill.
Pai: Your Linear teams are:
  - Pericak (Key: PER)

Claude: List my Linear issues for team PER.
Pai: Here are the Linear issues for team PER:
  - PER-10: ... (State: Backlog)
  - PER-9: ... (State: Todo)
  - PER-8: ... (State: Todo)
  - PER-7: ... (State: Todo)
  - PER-6: ... (State: Todo)
  - PER-5: ... (State: Todo)
  ...
</code></pre>
<p>That's real output (titles redacted). Pai read the
skill's curl commands, called the Linear GraphQL API
with the Vault-injected API key, and returned my actual
issues. The full chain: Claude Code runs <code>kubectl exec</code>,
which calls the <code>openclaw agent</code> CLI, which sends the
message to Gemini 2.5 Flash, which reads the skill, runs
curl against Linear's API, and returns the result.</p>
<p>Two AIs, two different models, coordinating through a
Kubernetes pod with Vault-injected secrets and a
hand-written skill file. The whole thing is auditable
from end to end.</p>


<h1 id="what-openclaw-is">What OpenClaw is</h1>
<p><a href="https://openclaw.ai/">OpenClaw</a> is wildly popular and kind of confusing. From what I
can tell before starting, other than being a first-class security concern, it's meant
to be a tool that lets you connect to your ai agents over chat tools like WhatsApp.</p>
<p>It runs locally, you bring your own API key (Anthropic, OpenAI,
DeepSeek), and your data stays on your machine (until you screw up). The gateway
connects to messaging platforms like Telegram, Signal, WhatsApp,
Discord, and apparently about 20 others.</p>
<h1 id="install-on-macos">Install on macOS</h1>
<p>Prerequisites: Node.js 22+ and an API key for your chosen
model provider (more on that next).</p>
<p>The recommended install uses their script:</p>
<pre><code class="language-bash">curl -fsSL https://openclaw.ai/install.sh | bash
</code></pre>
<p>That handles Node detection and installs the <code>openclaw</code> CLI.
If you want to skip the wizard and install the binary only:</p>
<pre><code class="language-bash">curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
</code></pre>
<p>Then run the onboarding wizard separately:</p>
<pre><code class="language-bash">openclaw onboard
</code></pre>
<p>The wizard walks through gateway setup, workspace directory,
and API key config. Everything lives in <code>~/.openclaw/</code>.</p>
<h1 id="picking-a-model">Picking a model</h1>
<p>The onboard wizard asks which model to use. OpenClaw supports
a long list of providers, but here are the ones that matter
for a personal assistant:</p>
<table>
<thead>
<tr>
<th>Model</th>
<th>Input / Output (per 1M tokens)</th>
<th>Good for</th>
</tr>
</thead>
<tbody>
<tr>
<td>Claude Haiku 4.5</td>
<td>$1 / $5</td>
<td>Cheap daily driver</td>
</tr>
<tr>
<td>Claude Sonnet 4.6</td>
<td>$3 / $15</td>
<td>Solid middle ground</td>
</tr>
<tr>
<td>Claude Opus 4.6</td>
<td>$5 / $25</td>
<td>Best reasoning</td>
</tr>
<tr>
<td>GPT-5</td>
<td>$1.25 / $10</td>
<td>Strong alternative</td>
</tr>
<tr>
<td>GPT-4o Mini</td>
<td>$0.15 / $0.60</td>
<td>Budget OpenAI</td>
</tr>
<tr>
<td>Gemini 2.5 Flash</td>
<td>Free (250 req/day) / ~$0.30 paid</td>
<td>Free option</td>
</tr>
<tr>
<td>Gemini 3 Pro</td>
<td>$2 / $12</td>
<td>Strong reasoning</td>
</tr>
<tr>
<td>DeepSeek (via Ollama)</td>
<td>Free (local)</td>
<td>Fully offline</td>
</tr>
</tbody>
</table>
<h2 id="can-you-use-your-20month-subscription">Can you use your $20/month subscription?</h2>
<p><strong>ChatGPT Plus/Pro:</strong> No. The subscription doesn't include API
access. You need a separate OpenAI API key with pay-as-you-go
billing.</p>
<p><strong>Claude Pro ($20/mo):</strong> Not anymore. Early on, people found a
workaround using OAuth tokens from the Claude Code CLI.
Anthropic shut that down in January 2026. You need a separate
Anthropic API key.</p>
<p><strong>Claude Max ($200/mo) and Claude Code subscription:</strong> Same
story. The setup-token auth path existed briefly but Anthropic
scoped the tokens so they only work with the official Claude
Code client.</p>
<h2 id="trying-geminis-model">Trying Gemini's model</h2>
<p>Apparently Google's Gemini API has a free tier, I tried it out. Gemini 2.5 Flash gets
250 requests/day free. For texting a bot a few times a day to manage issues, that's ok.</p>
<p>Annoyingly there are a bunch of 2.5 options. No idea if they all have free tiers.</p>
<p>I initially picked <code>google/gemini-2.5-flash-preview-09-2025</code> during the wizard and
gave it my api key using the <code>Paste API key now</code> option. Sadly that had an error</p>
<pre><code class="language-test">models/gemini-2.5-flash-preview-09-2025 is not found for API version v1beta,
</code></pre>
<p>Fixing it was a pain in the ass, their <code>/model</code> and <code>/models</code> tools TUI setup was jank
af and just didnt work.</p>
<pre><code class="language-bash">/exit
openclaw configure
</code></pre>
<p>I tried to switch the model up to <code>google/gemini-2.5-flash</code>.</p>
<p>Note that this thing stays running in the background</p>
<pre><code class="language-bash">➜  ~ ps aux | grep openclaw
kp               39009   0.1  1.0 444980720 173456   ??  R    11:03AM   0:07.97 openclaw-gateway
</code></pre>
<p>Re-open the TUI with <code>openclaw tui</code> if you end up out of it.</p>
<h2 id="connect-telegram">Connect Telegram</h2>
<p>I paused here to install Telegram on my MacBook. It's pretty easy if you already have
it on your phone, you just scan a QR code.</p>
<p>During the quick start it recommends you use Telegram. I chose to use
<code>Telegram (Bot API)</code>. Then I followed the instructions:</p>
<pre><code class="language-text">◇  Telegram bot token ───────────────────────────────────────────────────────────────────╮
│                                                                                        │
│  1) Open Telegram and chat with @BotFather                                             │
│  2) Run /newbot (or /mybots)                                                           │
│  3) Copy the token (looks like 123456:ABC...)                                          │
│  Tip: you can also set TELEGRAM_BOT_TOKEN in your env.                                 │
│  Docs: https://docs.openclaw.ai/telegram  │
│  Website: https://openclaw.ai                                                          │
│                                                                                        │
├────────────────────────────────────────────────────────────────────────────────────────╯
</code></pre>
<p>The /newbot prompt had me name it. Then I got the key to give OpenClaw.</p>
<h2 id="set-up-search">Set up Search</h2>
<p>I chose to use Gemini since I'm giving it that API key anyways. Plus, Google's gotta be
the best at search, right? It's like, their thing. Suprisingly it asked again for
<code>Gemini (Google Search) API key</code>. I just gave it the same key as before.</p>
<h2 id="sketchy-skills-time">Sketchy Skills Time</h2>
<p>Then I got to here and just proceeed. There was some news about malware in the skills.</p>
<pre><code class="language-text">◇  Skills status ─────────────╮
│                             │
│  Eligible: 8                │
│  Missing requirements: 43   │
│  Unsupported on this OS: 0  │
│  Blocked by allowlist: 0    │
│                             │
├─────────────────────────────╯
</code></pre>
<h2 id="places-api">Places API</h2>
<p>What, why?</p>
<pre><code class="language-text">◆  Set GOOGLE_PLACES_API_KEY for goplaces?
│  ○ Yes / ● No
</code></pre>
<h2 id="gemini-for-nano-banana">Gemini for nano banana</h2>
<p>I mean yeah but I already gave it this key twice, kinda annoying.</p>
<pre><code class="language-text">◆  Set GEMINI_API_KEY for nano-banana-pro?
│  ● Yes / ○ No
</code></pre>
<h2 id="the-other-keys-it-wants">The other keys it wants</h2>
<p>... It wants a lot of keys, just start saying no.</p>
<h2 id="hooks">Hooks</h2>
<p>I don't trust boot-md yet.</p>
<pre><code class="language-text">◆  Enable hooks?
│  ◻ Skip for now
│  ◻ 🚀 boot-md
│  ◼ 📎 bootstrap-extra-files (Inject additional workspace bootstrap files via glob/path patterns)
│  ◼ 📝 command-logger (Log all command events to a centralized audit file)
│  ◼ 💾 session-memory (Save session context to memory when /new or /reset command is issued)
</code></pre>
<h2 id="node-wants-to-find-devices-on-local-networks">Node wants to find devices on local networks</h2>
<p>MacOS popup. Yeah, nah. This is already probably the least secure thing I've ever done
on purpose.</p>
<h2 id="hatch-the-bot">Hatch the bot</h2>
<p>I love a good TUI.</p>
<pre><code class="language-text">◆  How do you want to hatch your bot?
│  ● Hatch in TUI (recommended)
│  ○ Open the Web UI
│  ○ Do this later
</code></pre>
<h1 id="talk-to-the-bot-on-telegram">Talk to the bot on Telegram</h1>
<p>The BotFather sends you a link to your bot account. I clicked it, hit start, and that
sent /start to it. It immediately told me OpenClaw: access not configured. Love it.
I copied its whole message and just dumped it into the TUI for OC to sort it out.</p>
<p>Aand, it's that error again:</p>
<pre><code class="language-text">LLM error: {
"error": {
"code": 404,
"message": "models/gemini-2.5-flash-preview-09-2025 is not found for API version v1beta, or is not supported for generateContent. Call ListModels to see the list of available models and their supported methods.",
"status": "NOT_FOUND"
}
}
</code></pre>
<p>Turns out changing the model doesn't stick unless you restart the gateway.
Entertainingly I asked it to restart the gateway in the TUI. It killed the gateway and
then immediately went unresponsive, not having a gateway to work with.</p>
<p>Restarting it... <code>openclaw gateway</code>: Conveniently that opens it in the foreground, it
looks great in tmux.</p>
<h2 id="set-up-the-tone-and-such">Set up the tone and such</h2>
<p>When the messaging finally works on Telegram it'll ask you for an identity and tone.
It's kind of fun.</p>
<h1 id="shutdown-procedure">Shutdown Procedure</h1>
<p>Don't wanna leave this thing running until it's secured.</p>
<pre><code class="language-bash"># Stop the gateway
openclaw gateway stop

# Verify nothing is still running
ps aux | grep openclaw
pkill -f openclaw-gateway
</code></pre>
<h1 id="whats-next">What's next</h1>
<p>I wanted to set this up with Linear, but honestly I don't love it runing flat on my
Macbook. I'm gonna <a href="/openclaw-k8s.html">put it in K8s</a> and producitonize this now
that I've got the MVP figured out.</p>


<p>After building a <a href="/ai-security-toolkit.html">security scanning toolkit</a>, I wanted the
same pattern for linting. Tedious rules that slow developers down are trivial for a
coding agent to stick to, and it'll help provide some baseline quality.</p>
<p>I also don't want the agent to ever make a mess, and knowing they love to git commit
constantly, I'm leaning again on pre-commit hooks to keep things deterministic.</p>
<h1 id="megalinter-is-slow">MegaLinter is SLOW</h1>
<p>I tried <a href="https://megalinter.io/">MegaLinter</a> first. It's a
popular containerized linter that bundles 100+ tools. The full
image is 17GB. The "cupcake" flavor with common languages is
10GB. Even the language-specific flavors are 5GB on disk.</p>
<p>The scan took over five minutes on a monorepo with a few
thousand files. That's not something I want AI agents running
on demand. So I built my own.</p>
<h1 id="introducing-kpericakai-lint-toolkit">Introducing kpericak/ai-lint-toolkit</h1>
<p>Cool thing about agentic coding is you can roll your own anything with basically no
effort. I asked it to make me my own faster one, and to run it then fix up my own
project.</p>
<p>Ended up with an image containing four linters, each the fastest in its category:</p>
<table>
<thead>
<tr>
<th>Language</th>
<th>Tool</th>
<th>Written in</th>
</tr>
</thead>
<tbody>
<tr>
<td>Python</td>
<td><a href="https://docs.astral.sh/ruff/">ruff</a></td>
<td>Rust</td>
</tr>
<tr>
<td>JS / TS</td>
<td><a href="https://biomejs.dev/">biome</a></td>
<td>Rust</td>
</tr>
<tr>
<td>Dockerfile</td>
<td><a href="https://github.com/hadolint/hadolint">hadolint</a></td>
<td>Haskell</td>
</tr>
<tr>
<td>Terraform</td>
<td><a href="https://github.com/terraform-linters/tflint">tflint</a></td>
<td>Go</td>
</tr>
</tbody>
</table>
<p>All four are single compiled binaries. No Python runtime, no
Node.js, no JVM. The final image is <strong>282MB</strong>.</p>
<p>Ruff replaces flake8, pylint, isort, and black in one tool.
Biome replaces eslint and prettier. Both are written in Rust
and finish in under a second on this monorepo.</p>
<h1 id="the-dockerfile">The Dockerfile</h1>
<p>Multi-stage build. Copy hadolint and tflint from their
official images, download ruff and biome as release binaries.</p>
<pre><code class="language-dockerfile">FROM hadolint/hadolint:v2.14.0-alpine AS hadolint
FROM ghcr.io/terraform-linters/tflint:v0.61.0 AS tflint

FROM alpine:3.21

ARG RUFF_VERSION=0.15.5
ARG BIOME_VERSION=2.4.6
ARG TARGETARCH

RUN apk upgrade --no-cache

COPY --from=hadolint /bin/hadolint /usr/local/bin/hadolint
COPY --from=tflint /usr/local/bin/tflint /usr/local/bin/tflint

# ruff: Python linter (Rust binary)
RUN if [ "$TARGETARCH" = "arm64" ]; then \
      RUFF_ARCH="aarch64"; else RUFF_ARCH="x86_64"; fi \
    &#x26;&#x26; wget -qO- \
    "https://github.com/astral-sh/ruff/releases/download/\
${RUFF_VERSION}/ruff-${RUFF_ARCH}-unknown-linux-musl.tar.gz" \
    | tar xz --strip-components=1 -C /usr/local/bin

# biome: JS/TS linter (Rust binary)
RUN if [ "$TARGETARCH" = "arm64" ]; then \
      BIOME_ARCH="linux-arm64-musl"; \
      else BIOME_ARCH="linux-x64-musl"; fi \
    &#x26;&#x26; wget -qO /usr/local/bin/biome \
    "https://github.com/biomejs/biome/releases/download/\
%40biomejs%2Fbiome%40${BIOME_VERSION}/biome-${BIOME_ARCH}" \
    &#x26;&#x26; chmod +x /usr/local/bin/biome

RUN addgroup -S linter &#x26;&#x26; adduser -S linter -G linter
RUN mkdir -p /workspace &#x26;&#x26; chown linter:linter /workspace

WORKDIR /workspace
USER linter
ENTRYPOINT ["/bin/sh"]
</code></pre>
<p>The <code>TARGETARCH</code> arg is set automatically by Docker BuildKit,
so the same Dockerfile works on both amd64 and arm64. A
non-root <code>linter</code> user runs the tools. The image builds in
under 10 seconds because every tool is a precompiled binary.</p>
<p>Source:
<a href="https://github.com/kylep/multi/tree/main/infra/ai-lint-toolkit">GitHub</a></p>
<h1 id="asking-ai-agents-to-lint">Asking AI agents to lint</h1>
<p>Same approach as the
<a href="/ai-security-toolkit.html">security toolkit</a>. A <a href="/ruler-cross-tool-ai-rules.html">Ruler</a>
file provides the commands, then <code>ruler apply</code> injects them into CLAUDE.md and any
other tool config.</p>
<p>Note that this is nondetermistic and such not dependable.</p>
<pre><code class="language-markdown"># Linting

The Docker image `kpericak/ai-lint-toolkit:0.1` bundles
ruff, biome, hadolint, and tflint in one Alpine container.

Run from the repo root. Mount the project directory
as /workspace.

## Python (ruff)
docker run --rm -v "$(pwd):/workspace:ro" \
  kpericak/ai-lint-toolkit:0.1 \
  -c "ruff check /workspace --no-cache"

## JavaScript / TypeScript (biome)
docker run --rm -v "$(pwd):/workspace:ro" \
  kpericak/ai-lint-toolkit:0.1 \
  -c "biome lint /workspace/path/to/src"

## Dockerfiles (hadolint)
docker run --rm -v "$(pwd):/workspace:ro" \
  kpericak/ai-lint-toolkit:0.1 \
  -c "find /workspace -name 'Dockerfile*' \
  -not -path '*/node_modules/*' | xargs hadolint"

## Terraform (tflint)
docker run --rm -v "$(pwd):/workspace:ro" \
  kpericak/ai-lint-toolkit:0.1 \
  -c "cd /workspace/path/to/tf &#x26;&#x26; tflint"
</code></pre>
<p>The volume is mounted read-only. Linters don't need to write
to your source tree. Ruff needs <code>--no-cache</code> to skip writing
a cache directory since the mount is read-only.</p>
<p>For biome, point it at specific source directories rather
than the repo root. Otherwise it crawls <code>node_modules</code> and
takes forever.</p>
<h1 id="running-the-linters">Running the linters</h1>
<p>Here's what each tool found on the first scan of this
monorepo.</p>
<h2 id="ruff">ruff</h2>
<pre><code>46  F401  [*] unused-import
13  F841  [-] unused-variable
11  F541  [*] f-string-missing-placeholders
 1  F821  [ ] undefined-name
Found 71 errors.
[*] 59 fixable with the `--fix` option.
</code></pre>
<p>71 findings across all the Python in the monorepo. Most are
in older projects (kytrade, mods) that haven't been touched
in a while. The <code>[*]</code> markers mean ruff can auto-fix them.
Unused imports and f-string placeholders are the bulk of it.</p>
<p>Ruff scanned the entire repo in 0.5 seconds.</p>
<h2 id="biome">biome</h2>
<pre><code>7 lint/suspicious/noDoubleEquals
6 lint/style/noNonNullAssertion
4 lint/style/useConst
1 lint/correctness/useParseIntRadix
1 lint/correctness/noUnusedImports
</code></pre>
<p>19 findings. The double-equals warnings are in the blog's
route handler (<code>==</code> instead of <code>===</code>). The non-null
assertions are in test files for a game project. All fixable.</p>
<p>Biome scanned the JS/TS source in 0.7 seconds.</p>
<h2 id="hadolint">hadolint</h2>
<p>Hadolint found 14 findings across 5 Dockerfiles. The
interesting ones:</p>
<ul>
<li><strong>DL3020</strong>: Use COPY instead of ADD (2 errors in kytrade)</li>
<li><strong>DL3018</strong>: Pin versions in <code>apk add</code></li>
<li><strong>DL3013</strong>: Pin versions in <code>pip install</code></li>
<li><strong>DL4006</strong>: Set <code>SHELL</code> with <code>-o pipefail</code> before piped RUN</li>
</ul>
<p>The security toolkit's own Dockerfile got flagged for the
pipefail issue in its <code>wget | tar</code> pipe. Fair catch.</p>
<h2 id="tflint">tflint</h2>
<pre><code>Warning: terraform "required_version" attribute is required
Warning: Missing version constraint for provider "google"
Warning: [Fixable] data "aws_caller_identity" "current"
  is declared but not used
</code></pre>
<p>4 warnings across 2 Terraform directories. Missing version
constraints and an unused data source. Standard Terraform
hygiene stuff.</p>
<h1 id="size-comparison">Size comparison</h1>
<table>
<thead>
<tr>
<th>Image</th>
<th>Size on disk</th>
<th>Run time</th>
</tr>
</thead>
<tbody>
<tr>
<td>MegaLinter (full)</td>
<td>17 GB</td>
<td>5+ min</td>
</tr>
<tr>
<td>MegaLinter (cupcake)</td>
<td>10 GB</td>
<td>untested</td>
</tr>
<tr>
<td>MegaLinter (javascript)</td>
<td>5 GB</td>
<td>untested</td>
</tr>
<tr>
<td>ai-lint-toolkit</td>
<td>282 MB</td>
<td>&#x3C; 5 sec</td>
</tr>
</tbody>
</table>
<p>The custom image is 60x smaller than MegaLinter's full image
and runs in seconds. The tradeoff is that it only covers four
languages. But those are the four I need, and adding more is
one <code>wget</code> or <code>COPY</code> away.</p>
<h1 id="pre-commit-hooks-as-lazy-ci">Pre-commit hooks as lazy CI</h1>
<p>I already had semgrep and gitleaks running as pre-commit
hooks from the
<a href="/ai-security-toolkit.html">security toolkit</a>. Adding
ruff and biome follows the same pattern.</p>
<pre><code class="language-yaml">repos:
- repo: local
  hooks:
    - id: ruff
      name: Ruff
      entry: >-
        bash -c 'docker run
        -v "$(pwd):/workspace:ro" --rm
        kpericak/ai-lint-toolkit:0.1
        -c "ruff check /workspace --no-cache"'
      language: system
      stages: ["pre-commit"]
    - id: biome
      name: Biome
      entry: >-
        bash -c 'docker run
        -v "$(pwd):/workspace:ro" --rm
        kpericak/ai-lint-toolkit:0.1
        -c "biome lint /workspace/apps/blog/blog/pages
        /workspace/apps/blog/blog/components
        /workspace/apps/blog/blog/utils"'
      language: system
      stages: ["pre-commit"]
    - id: semgrep
      name: Semgrep
      entry: >-
        bash -c 'docker run
        -v "$(pwd):/workspace:ro" --rm
        kpericak/ai-security-toolkit-1:0.2
        -c "semgrep scan --config auto
        --error /workspace"'
      language: system
      stages: ["pre-commit", "pre-push"]
- repo: https://github.com/gitleaks/gitleaks
  rev: v8.30.0
  hooks:
    - id: gitleaks
      stages: ["pre-commit", "pre-push"]
</code></pre>
<p>Every commit now gets linted for Python and JS/TS issues,
scanned for security bugs by semgrep, and checked for
leaked secrets by gitleaks. Four tools, no CI server
required.</p>
<p>Hadolint and tflint aren't in the hooks. Dockerfiles and
Terraform configs change rarely enough that running them
on demand through the AI agent is fine.</p>


<p>AI coding agents can write code, review PRs, and run tests. They
can't run security scans unless you give them the tools. I built a
Docker image that bundles three scanners into one container, then
wired it into my repo so any AI tool can use them.</p>
<h1 id="whats-in-the-image">What's in the image</h1>
<p>The image <code>kpericak/ai-security-toolkit-1</code> has 3 tools:</p>
<table>
<thead>
<tr>
<th>Category</th>
<th>Tool</th>
</tr>
</thead>
<tbody>
<tr>
<td>SAST (static analysis)</td>
<td><a href="https://semgrep.dev/">semgrep</a></td>
</tr>
<tr>
<td>SCA (dependency vulns)</td>
<td><a href="https://trivy.dev/">trivy</a></td>
</tr>
<tr>
<td>Secrets (files on disk)</td>
<td><a href="https://trivy.dev/">trivy</a></td>
</tr>
<tr>
<td>Secrets (git history)</td>
<td><a href="https://gitleaks.io/">gitleaks</a></td>
</tr>
<tr>
<td>Misconfig (Dockerfile, Terraform)</td>
<td><a href="https://trivy.dev/">trivy</a></td>
</tr>
<tr>
<td>Container image scanning</td>
<td><a href="https://trivy.dev/">trivy</a></td>
</tr>
</tbody>
</table>
<h1 id="the-dockerfile">The Dockerfile</h1>
<p>Multi-stage build. Copy the Go binaries from the official images,
install semgrep via pip on Alpine.</p>
<pre><code class="language-dockerfile">FROM aquasec/trivy:0.69.3 AS trivy
FROM zricethezav/gitleaks:v8.30.0 AS gitleaks

FROM python:3.12.13-alpine

RUN apk upgrade --no-cache &#x26;&#x26; apk add --no-cache nodejs git gcc musl-dev

COPY --from=trivy /usr/local/bin/trivy /usr/local/bin/trivy
COPY --from=gitleaks /usr/bin/gitleaks /usr/local/bin/gitleaks

RUN pip install --no-cache-dir semgrep

COPY .trivyignore /workspace/.trivyignore

RUN addgroup -S scanner &#x26;&#x26; adduser -S scanner -G scanner
RUN mkdir -p /workspace &#x26;&#x26; chown scanner:scanner /workspace

WORKDIR /workspace
USER scanner
ENTRYPOINT ["/bin/sh"]
</code></pre>
<p>Trivy and gitleaks are single Go binaries, so the COPY stages are all they need.
Semgrep needs Python and a C compiler for its native
extensions, which is why <code>gcc</code> and <code>musl-dev</code> are there. The base
images are pinned to specific versions for reproducible builds. A
non-root <code>scanner</code> user runs the tools so the container doesn't
operate as root. The image ends up around 800MB. Not small, but
it's a tooling image, not a production service.</p>
<p>Source:
<a href="https://github.com/kylep/multi/tree/main/infra/ai-security-toolkit-1">GitHub</a></p>
<h1 id="teaching-ai-agents-to-scan">Teaching AI agents to scan</h1>
<p>The scans are just shell commands. The objective is getting robot to run them.
I use <a href="/ruler-cross-tool-ai-rules.html">Ruler</a> to maintain a single
<code>.ruler/security.md</code> file that gets injected into CLAUDE.md,
AGENTS.md, and any other tool-specific config.</p>
<p>Here's the ruler file:</p>
<pre><code class="language-markdown"># Security Scanning

The Docker image `kpericak/ai-security-toolkit-1:0.2` bundles
semgrep, trivy, and gitleaks in one Alpine container.

Run from the repo root. Mount the project directory as /workspace.

## Static analysis (semgrep)
docker run --rm -v "$(pwd):/workspace:ro" \
  kpericak/ai-security-toolkit-1:0.2 \
  -c "semgrep scan --config auto /workspace"

## Vulnerability scanning (trivy)
docker run --rm -v "$(pwd):/workspace:ro" \
  kpericak/ai-security-toolkit-1:0.2 \
  -c "trivy fs --scanners vuln,secret,misconfig /workspace"

## Container image scanning (trivy)
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  kpericak/ai-security-toolkit-1:0.2 \
  -c "trivy image &#x3C;image:tag>"

## Secret scanning (gitleaks)
docker run --rm -v "$(pwd):/workspace:ro" \
  kpericak/ai-security-toolkit-1:0.2 \
  -c "cd /workspace &#x26;&#x26; gitleaks detect --source ."
</code></pre>
<p>After running <code>ruler apply</code>, every AI tool in the repo knows how to
run security scans. I can tell Claude Code "scan this repo for
vulnerabilities" and it has the commands ready.</p>
<h1 id="pre-commit-hooks">Pre-commit hooks</h1>
<p>Both semgrep and gitleaks run as
<a href="https://pre-commit.com/">pre-commit</a> hooks. Every commit gets
a static analysis scan and a secret scan before it lands.</p>
<h2 id="installing-pre-commit">Installing pre-commit</h2>
<p>You need <a href="https://pre-commit.com/">pre-commit</a> installed, plus
Docker for the scanner container.</p>
<pre><code class="language-bash"># macOS
brew install pre-commit

# Linux (pip)
pip install pre-commit

# Then activate hooks in the repo
cd your-repo
pre-commit install
</code></pre>
<p>That wires <code>.pre-commit-config.yaml</code> into <code>.git/hooks/pre-commit</code>
so the hooks run automatically on every commit.</p>
<h2 id="the-hook-config">The hook config</h2>
<pre><code class="language-yaml">- id: semgrep
  name: Semgrep
  description: Static analysis scan using the security toolkit image.
  entry: bash -c 'docker run -v "$(pwd):/workspace:ro" --rm
    kpericak/ai-security-toolkit-1:0.2
    -c "semgrep scan --config auto --error /workspace"'
  language: system
  stages: ["pre-commit", "pre-push"]
- repo: https://github.com/gitleaks/gitleaks
  rev: v8.30.0
  hooks:
    - id: gitleaks
      stages: ["pre-commit", "pre-push"]
</code></pre>
<p>The <code>--error</code> flag on semgrep makes it exit non-zero on findings,
which blocks the commit. Gitleaks uses its official pre-commit
hook, which pre-commit installs via Go. It scans staged files
directly. Use <code>gitleaks detect</code> for full repo scans.</p>
<h1 id="running-the-scans">Running the scans</h1>
<p>Here's what each scanner produces when pointed at this monorepo.</p>
<h2 id="semgrep">semgrep</h2>
<p>The first scan found 43 findings. Most were false positives:
<code>dangerouslySetInnerHTML</code> in the blog's SSG rendering (the HTML
comes from my own markdown), <code>path.join</code> with internal filenames,
K8s manifests in old sample projects, and vendored Prism.js.</p>
<p>Two changes got it to zero:</p>
<ol>
<li>A <code>.semgrepignore</code> file to skip directories that aren't active
code: <code>samples/</code>, old infra, vendored JS, and a legacy project.</li>
<li>Inline <code>// nosemgrep</code> comments on the few remaining lines where
the finding is a known false positive, like the SSG innerHTML.</li>
</ol>
<pre><code>┌──────────────┐
│ Scan Summary │
└──────────────┘
Ran 717 rules on 485 files: 0 findings.
</code></pre>
<p>Zero findings means semgrep can run as a pre-commit hook with
<code>--error</code> and block on any new issue. No triage fatigue.</p>
<h2 id="trivy">trivy</h2>
<p>Trivy's default scanners are <code>vuln</code> and <code>secret</code>. It also has
<code>misconfig</code> and <code>license</code> scanners. Adding <code>--scanners vuln,secret,misconfig</code> enables Dockerfile and Terraform
misconfiguration checks on top of the dependency and secret
scanning.</p>
<p>The first scan found 7 npm vulnerabilities. 3 HIGH in Next.js
14 (DoS in server components), plus medium/low hits in
dompurify, lodash-es, and diff. I bumped Next.js from 14 to 15
and ran <code>npm audit fix</code> for the transitive deps. The upgrade
required no code changes. Pages Router, <code>output: 'export'</code>, and
React 18 all still work on Next.js 15.</p>
<p>With misconfig enabled, trivy also flagged Dockerfile issues:
no non-root USER, <code>cd</code> instead of <code>WORKDIR</code>, missing
HEALTHCHECK. The kind of things you'd catch in a code review
but might miss if nobody's looking.</p>
<pre><code>Report Summary
┌────────────────────────────────────────┬────────────┬───────┬─────────┬───────────────────┐
│                 Target                 │    Type    │ Vulns │ Secrets │ Misconfigurations │
├────────────────────────────────────────┼────────────┼───────┼─────────┼───────────────────┤
│ apps/blog/blog/package-lock.json       │    npm     │   0   │    -    │         -         │
├────────────────────────────────────────┼────────────┼───────┼─────────┼───────────────────┤
│ apps/blog/Dockerfile                   │ dockerfile │   -   │    -    │         3         │
├────────────────────────────────────────┼────────────┼───────┼─────────┼───────────────────┤
│ apps/blog/tf                           │ terraform  │   -   │    -    │         0         │
├────────────────────────────────────────┼────────────┼───────┼─────────┼───────────────────┤
│ infra/ai-security-toolkit-1/Dockerfile │ dockerfile │   -   │    -    │         1         │
└────────────────────────────────────────┴────────────┴───────┴─────────┴───────────────────┘
</code></pre>
<p>Zero dependency vulns. The Dockerfile misconfigs are real
findings to fix next. The policy going forward: keep SCA vulns
at 0 in active projects. Major package upgrades are acceptable
to get there. Playwright tests catch regressions from the
upgrades.</p>
<h2 id="trivy-image">trivy image</h2>
<p><code>trivy fs</code> scans source code and lock files. <code>trivy image</code>
scans a built Docker image, catching OS-level CVEs in the base
image and vulnerabilities in installed packages that don't show
up in any lock file.</p>
<p>Running it against the first version of the toolkit image found
25 vulnerabilities that <code>trivy fs</code> never saw: Alpine OS
packages, Python dependencies, and Go stdlib CVEs baked into
the trivy and gitleaks binaries.</p>
<p>Fixes for v0.2:</p>
<ol>
<li>Pinned <code>python:3.12.13-alpine</code> and added <code>apk upgrade</code> to
get the latest Alpine packages. Fixed the CRITICAL zlib CVE.</li>
<li>The Go stdlib CVEs live inside the gitleaks binary, compiled
with Go 1.25.4. No newer gitleaks release exists. Added a
<code>.trivyignore</code> with comments explaining each suppression.</li>
</ol>
<p>The policy: no HIGH or CRITICAL findings. MEDIUM and below from
upstream binaries we don't compile are accepted and documented.</p>
<h2 id="gitleaks">gitleaks</h2>
<pre><code>144 commits scanned.
no leaks found.
</code></pre>
<p>Clean. Gitleaks scans git history by default, so it catches
secrets that were committed and later deleted. Trivy also has
a secret scanner, but it only checks files on disk. If someone
committed an API key and removed it in the next commit, trivy
wouldn't see it. Gitleaks would, because the key is still in
the git log.</p>
<p>That's why both are in the image. Trivy covers dependency vulns
and current-file secrets. Gitleaks covers the git history angle.
I originally had <code>npm audit</code> in the image too, but dropped it
since trivy already scans <code>package-lock.json</code> for the same CVEs.</p>
<h1 id="the-workflow">The workflow</h1>
<p>With all this wired up, security scanning happens at three levels:</p>
<ol>
<li><strong>Every commit</strong>: semgrep and gitleaks run as pre-commit hooks.
Any new static analysis finding or leaked secret blocks the
commit.</li>
<li><strong>Scheduled</strong>: a security agent runs <code>trivy image</code> against
built container images on a schedule, triages the results,
and files issues in
<a href="/linear-mcp.html">Linear</a> for anything that needs attention.
Image scanning is too slow for pre-commit hooks but catches
OS-level CVEs that filesystem scans miss.</li>
<li><strong>On demand</strong>: I tell the AI agent "run security scans" or
include it in task instructions. The agent runs the docker
commands from its CLAUDE.md context and triages the output.</li>
</ol>
<p>The AI agent is good at triaging scan results. It can reason about
which dependency vulnerabilities actually matter for a static
export vs a running server. That's the real value of combining
scanners with AI agents: the agent reads the output instead of
just dumping a report.</p>


<p>Two things in this post. First, wiring up GA4 on this blog, which turns out to
be pretty straightforward on Next.js. Second, connecting the official GA4 MCP
server so Claude Code can query the analytics data directly in natural language.</p>
<p>Once the MCP is connected, you can ask
Claude things like "which posts got the most traffic last month" or "what are
my top referral sources" and it queries GA4 and tells you. No dashboard required.</p>
<h1 id="setting-up-ga4">Setting Up GA4</h1>
<h2 id="create-the-property">Create the Property</h2>
<p>Go to <a href="https://analytics.google.com">analytics.google.com</a>. Hit Create →
Property, fill in a name and your timezone, click through the business details
screens (mostly irrelevant for a personal blog), then choose Web as the
platform and enter your domain. GA4 creates the property and a web data stream
in one flow.</p>
<p>Once the stream is created, click it to open the stream details. The
measurement ID is right there. It looks like <code>G-XXXXXXXXXX</code>.</p>
<h2 id="add-tracking-to-nextjs">Add Tracking to Next.js</h2>
<p>This blog is statically exported Next.js. The right place to add the tracking
script is <code>_app.js</code>, using <code>next/script</code> with <code>afterInteractive</code> so it doesn't
block rendering:</p>
<pre><code class="language-jsx">// pages/_app.js
import Script from 'next/script';

export default function MyApp({ Component, pageProps }) {
  return (
    &#x3C;>
      &#x3C;Script
        src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"
        strategy="afterInteractive"
      />
      &#x3C;Script id="google-analytics" strategy="afterInteractive">
        {`
          window.dataLayer = window.dataLayer || [];
          function gtag(){dataLayer.push(arguments);}
          gtag('js', new Date());
          gtag('config', 'G-XXXXXXXXXX');
        `}
      &#x3C;/Script>
      {/* rest of your app */}
    &#x3C;/>
  );
}
</code></pre>
<p>Replace <code>G-XXXXXXXXXX</code> with your actual measurement ID. Deploy, open the GA4
realtime report, and visit your site to confirm hits are coming in. Takes a
couple minutes to show up.</p>
<p>Note: if you're serving via a CDN with aggressive caching (this blog uses GCS),
make sure the HTML is being revalidated, not served stale. The script tag needs
to actually make it into the page.</p>
<h1 id="the-ga4-mcp-server">The GA4 MCP Server</h1>
<p>Google ships an <a href="https://github.com/googleanalytics/google-analytics-mcp">official MCP server</a>
for GA4. It's read-only, which is fine for querying data. It wraps the GA4
Admin API and Data API and exposes a handful of tools Claude can call.</p>
<h2 id="auth-setup">Auth Setup</h2>
<p>The server uses Google Application Default Credentials. Before you can log in,
you need to enable two APIs in your GCP project. Check which project your
gcloud CLI is using:</p>
<pre><code class="language-bash">gcloud config get-value project
</code></pre>
<p>Then enable the APIs:</p>
<pre><code class="language-bash"># Required for get_account_summaries, get_property_details
gcloud services enable analyticsadmin.googleapis.com

# Required for run_report, run_realtime_report
gcloud services enable analyticsdata.googleapis.com
</code></pre>
<p>Then log in:</p>
<pre><code class="language-bash">gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform
</code></pre>
<p>The <code>cloud-platform</code> scope is required alongside <code>analytics.readonly</code>. Without
it you get a deprecation error and the auth fails.</p>
<p>That stores credentials at
<code>~/.config/gcloud/application_default_credentials.json</code>. No service account
file needed.</p>
<p>If you'd rather use a service account (better for shared environments), create
one in Google Cloud Console, grant it Viewer access on your GA4 property, and
download the JSON key. Set <code>GOOGLE_APPLICATION_CREDENTIALS</code> to point at it.</p>
<h2 id="add-to-claude-code">Add to Claude Code</h2>
<p>Add it to <code>.mcp.json</code> at the project root to share it with the team:</p>
<pre><code class="language-json">{
  "mcpServers": {
    "analytics-mcp": {
      "command": "pipx",
      "args": ["run", "analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/Users/you/.config/gcloud/application_default_credentials.json"
      }
    }
  }
}
</code></pre>
<p>Or add it for yourself only:</p>
<pre><code class="language-bash">claude mcp add analytics-mcp --env GOOGLE_APPLICATION_CREDENTIALS=~/.config/gcloud/application_default_credentials.json -- pipx run analytics-mcp
</code></pre>
<p>Restart Claude Code and run <code>/mcp</code> to confirm <code>analytics-mcp</code> is listed.</p>
<h2 id="what-it-exposes">What It Exposes</h2>
<p>Five tools:</p>
<ul>
<li><code>get_account_summaries</code>: lists your GA4 accounts and properties. Good first
call to confirm auth is working and grab your property ID.</li>
<li><code>get_property_details</code>: details for a specific property.</li>
<li><code>run_report</code>: the main one. Queries the GA4 Data API with dimensions and
metrics of your choice.</li>
<li><code>run_realtime_report</code>: same thing but against the realtime endpoint.</li>
<li><code>get_custom_dimensions_and_metrics</code>: lists any custom dimensions you've
defined on the property.</li>
</ul>
<p>The server is read-only. It can't modify your GA4 configuration.</p>
<h1 id="querying-data">Querying Data</h1>
<p>Once connected, you can ask in plain English. Claude figures out which dimensions and
metrics to use and calls <code>run_report</code> for you.</p>
<p>Some things I've asked it:</p>
<p><strong>Traffic overview:</strong></p>
<blockquote>
<p>What were my total users and sessions last week, broken down by day?</p>
</blockquote>
<p><strong>Top content:</strong></p>
<blockquote>
<p>Which pages got the most views in the last 30 days?</p>
</blockquote>
<p><strong>Referrals:</strong></p>
<blockquote>
<p>What are my top traffic sources this month?</p>
</blockquote>
<p><strong>Realtime:</strong></p>
<blockquote>
<p>How many people are on the site right now and what pages are they on?</p>
</blockquote>
<p>For anything beyond basic questions, it helps to know a few GA4 concepts.
"Sessions" and "users" mean what you'd expect. "Engaged sessions" are ones
where the user spent more than 10 seconds, viewed more than one page, or
triggered a conversion. The distinction matters when you're trying to tell real
readers from bots.</p>
<p>Claude will sometimes ask for your property ID before running a report. Either
give it the <code>G-XXXXXXXXXX</code> measurement ID or the numeric property ID from the
GA4 UI. If you add the property ID to your <code>CLAUDE.md</code> or project context,
it'll stop asking.</p>
<h1 id="what-its-actually-good-for">What It's Actually Good For</h1>
<p>The dashboard is fine for browsing. The MCP is better for specific questions,
comparing time periods, and anything you'd normally have to build a custom
report for.</p>
<p>The bigger thing I have in mind though is eventually having like OpenClaw or similar
using it in an ideation loop. Some sort of PM agent that adds potential tickets to a
Jira or Linear board and uses this data as an input.</p>
<p>I'm also just starting to love being back in tmux and not having to operate websites
as much. I set up the <a href="/cloudflare-mcp.html">Cloudflare MCP server</a>
next for the same reason.</p>
<p>Lastly I figure I can hook this up to voice commands somehow for a really custom voice
assistant.</p>


<p>I use Cursor and Claude Code, sometimes Codex, and I'm about to try OpenCode.
Each tool has its own rules format, and I've been maintaining them separately.
<a href="https://github.com/intellectronica/ruler">Ruler</a> generates each tool's native
config from a single source. Worth setting up.</p>
<h1 id="tool-agnosticism-with-common-rules">Tool agnosticism with common rules</h1>
<p>I'm trying to keep up. There are too many tools. I don't want to migrate things around.
We're using this at work too, since different devs use different tools. Here's how I
set up Ruler to consolidate my Cursor and Claude rules together.</p>
<p>I had this rule in Cursor:</p>
<pre><code class="language-markdown"># Monorepo rules

This git repo is a monorepo. It contains multiple sub-projects.
Do not look for context or cross-reference calls between sub-projects.
Each directory within apps/ and games/ is a sub-project. They shouldn't
share code.
</code></pre>
<p>Claude Code has CLAUDE.md files scattered through the tree:</p>
<table>
<thead>
<tr>
<th>File</th>
<th>Contents</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>CLAUDE.md</code> (root)</td>
<td>Branching: never commit to main, always PR</td>
</tr>
<tr>
<td><code>apps/games/sillyapp/CLAUDE.md</code></td>
<td>iOS build and test commands, simulator lifecycle</td>
</tr>
<tr>
<td><code>apps/blog/.../posts/CLAUDE.md</code></td>
<td>Blog writing voice, formatting rules, structure</td>
</tr>
<tr>
<td><code>apps/games/kid-bot-battle-sim/features/CLAUDE.md</code></td>
<td>Interface details for that feature set</td>
</tr>
</tbody>
</table>
<h1 id="ruler-setup">Ruler Setup</h1>
<pre><code class="language-bash">npm install -g @intellectronica/ruler
</code></pre>
<p>Initialize at the repo root:</p>
<pre><code class="language-bash">ruler init
</code></pre>
<p>This creates a <code>.ruler/</code> directory and a <code>ruler.toml</code> config. Drop your
instructions as Markdown files inside <code>.ruler/</code>, then:</p>
<pre><code class="language-bash">ruler apply
</code></pre>
<h2 id="what-happens-when-you-run-it">What happens when you run it</h2>
<p>Claude Code gets <code>CLAUDE.md</code>. Everything else (Cursor, OpenCode, Codex,
Copilot, 30+ others) gets <code>AGENTS.md</code>. Generated files go into <code>.gitignore</code>
automatically, so only the <code>.ruler/</code> source is committed.</p>
<p>Ruler supports nested directories. A <code>.ruler/</code> at the repo root applies
globally. A <code>.ruler/</code> inside a sub-project applies when an agent is working
there. That matches how Claude Code already loads CLAUDE.md files walking up
the directory tree.</p>
<pre class="mermaid">
graph TD
    A[".ruler/ at repo root\nbranching, monorepo"] --> B[Claude Code]
    A --> C[Everyone Else\nCursor, OpenCode, Codex...]
    E[".ruler/ in sillyapp/\nbuild, test"] --> B
    E --> C
    F[".ruler/ in posts/\nblog style"] --> B
    F --> C
    B --> G[CLAUDE.md]
    C --> H[AGENTS.md]
</pre>
<p>You can symlink ~/.ruler to your dir too if you want global Claude rules.</p>
<h1 id="note-consider-just-using-agentsmd">Note: Consider just using AGENTS.md</h1>
<p>Most tools read <code>AGENTS.md</code>: Cursor, OpenCode, Codex, <del>others</del>. If all you have is
rules, it's not a bad idea to skip all of this and just use that format. I think it
might win. That doesn't help with Skills, though.</p>
<h2 id="skills">Skills</h2>
<p>Rules are basically just fancy prompt context that are always loaded.
Skills are just fancy prompt context loaded on-demand, maybe with some extra files
sometimes. Different tools implement them in different ways:</p>
<ul>
<li>Claude Code: <code>.claude/skills/</code></li>
<li>Cursor: <code>.cursor/skills/</code></li>
<li>Other tools follow the same pattern under their own config directories</li>
</ul>
<p>Ruler figures it out and distributes them for you. Could this all just be a bash
script? Yes. Does it do a bunch of stuff I don't understand too? Also, probably, yes.</p>
<p>Enabled by default. Pass <code>--no-skills</code> to skip it:</p>
<pre><code class="language-bash">ruler apply           # distributes rules + skills
ruler apply --no-skills  # rules only
</code></pre>
<hr>
<h1 id="consolidating-rules-migration-steps">Consolidating rules: Migration steps</h1>
<p>The <code>ruler.toml</code> at the root lists the agents to target:</p>
<pre><code class="language-toml">default_agents = ["claude", "cursor"]
</code></pre>
<p>Content moves from existing config files into <code>.ruler/</code> source files:</p>
<pre><code>.ruler/
  branching.md        # from root CLAUDE.md
  monorepo.md         # from .cursor/rules/monorepo.md (Claude never saw this)
apps/games/sillyapp/
  .ruler/
    build.md          # from sillyapp/CLAUDE.md
apps/blog/blog/markdown/posts/
  .ruler/
    style.md          # from posts/CLAUDE.md
apps/games/kid-bot-battle-sim/features/
  .ruler/
    interfaces.md     # from features/CLAUDE.md
</code></pre>
<p>Root <code>.ruler/branching.md</code> (was only in Claude Code):</p>
<pre><code class="language-markdown"># Branching

Never commit directly to `main`. Always create a branch and open a PR
against main for review.
</code></pre>
<p>Root <code>.ruler/monorepo.md</code> (was only in Cursor):</p>
<pre><code class="language-markdown"># Monorepo

This repo contains multiple independent sub-projects under `apps/` and
`games/`. Do not cross-reference or import code between sub-projects.
Each directory in those folders is its own isolated project.
</code></pre>
<p>The project-specific files (sillyapp build commands, blog style guide)
move into <code>.ruler/</code> inside their directories unchanged. Content stays the
same, location shifts.</p>
<p>Note: the existing hand-written CLAUDE.md files get replaced by generated
versions after <code>ruler apply</code>. Edit the <code>.ruler/</code> source, not the output.</p>


<p>CodeRabbit is an AI code review tool. It can review your PRs on GitHub / MRs on GitLab
after you push. You can also hook it into Claude Code to get the review and fix up the
nits with your agent prior to opening the PR.</p>
<h1 id="install-the-cli">Install the CLI</h1>
<pre><code class="language-bash">curl -fsSL https://cli.coderabbit.ai/install.sh | sh
</code></pre>
<p>Then authenticate:</p>
<pre><code class="language-bash">coderabbit auth login
</code></pre>
<p>This opens a browser. Log in with GitHub, copy the token, paste it in the
terminal. The token lasts 90 days.</p>
<p>Verify it worked:</p>
<pre><code class="language-bash">coderabbit --version
</code></pre>
<h1 id="install-the-claude-code-plugin">Install the Claude Code Plugin</h1>
<p>From any terminal:</p>
<pre><code class="language-bash">claude plugin install coderabbit
</code></pre>
<p>Or from inside a Claude Code session:</p>
<pre><code class="language-text">/plugin install coderabbit
</code></pre>
<p>The plugin wraps the CLI and exposes review commands you can run directly in
your Claude Code session. It also lets you trigger a review with plain English,
which Claude Code routes to the plugin automatically.</p>
<h1 id="the-workflow">The Workflow</h1>
<p>With both the CLI and plugin installed, the loop before any PR looks like this:</p>
<pre class="mermaid">
graph TD
    A[Make changes with Claude Code] --> B[Run coderabbit review]
    B --> C{Issues?}
    C -->|Yes| D[Ask Claude Code to fix them]
    D --> A
    C -->|No| E[Create PR]
</pre>
<p>Inside a Claude Code session, after you've made changes:</p>
<pre><code class="language-text">/coderabbit:review uncommitted
</code></pre>
<p>This reviews everything not yet committed. You can also review committed-but-
not-pushed changes:</p>
<pre><code class="language-text">/coderabbit:review committed
</code></pre>
<p>Or compare against a specific branch:</p>
<pre><code class="language-text">/coderabbit:review --base main
</code></pre>
<p>The review comes back as inline comments. You can ask Claude Code to fix specific
issues, re-run the review, and iterate until it's clean. Then push and open the
PR knowing CodeRabbit's automated review will be quiet.</p>
<p>It's kind of slow, but so is the PR review.</p>
<h1 id="claudemd-integration">CLAUDE.md integration</h1>
<p>CodeRabbit reads your <code>CLAUDE.md</code> files automatically. It treats them as code
guidelines and applies them during review.</p>
<p>That means that because my <code>CLAUDE.md</code> says "no em-dashes" and "never commit directly to
main",  CodeRabbit enforces those same rules when it reviews your PR. You don't need to
configure anything extra.</p>
<h1 id="config-with-coderabbityaml">Config with <code>.coderabbit.yaml</code></h1>
<p><code>.coderabbit.yaml</code> at the root gives control over what gets reviewed, how aggressively,
and with what focus per directory.</p>
<p>Notably:</p>
<ul>
<li><code>path_filters</code>: glob patterns for files to skip entirely (lock files, build
artifacts, node_modules, etc)</li>
<li><code>path_instructions</code>: per-path AI instructions</li>
</ul>
<p>Don't put <code>CLAUDE.md</code> in <code>path_instructions</code>. That makes CodeRabbit try
to review the file rather than use it as guidelines. The auto-detection handles
it correctly without any config.</p>
<h2 id="setup-for-this-repo">Setup for this repo</h2>
<p>Here's <a href="https://github.com/kylep/multi/blob/main/.coderabbit.yaml">the <code>.coderabbit.yaml</code> for this repo</a>.</p>
<p><strong><code>profile: chill</code></strong> is the most significant setting. CodeRabbit's default
profile generates a lot of comments. I'm actually on the fence still about this though,
once I can get the AI agents to run the code review and fix up in a ralf-style-loop I
may go back to aggressive.</p>
<p><strong><code>poem: false</code></strong> turns off CodeRabbit's cute poems, I'm not reading them like this.</p>
<p><strong>Path filters</strong> drop lock files, build artifacts, and generated directories.
There's no value in reviewing a <code>package-lock.json</code> diff.</p>
<p><strong><code>infra/</code> and <code>apps/kytrade/</code></strong> get security-focused instructions with
everything else deprioritized. Terraform style is not worth a comment.
A misconfigured IAM policy is.</p>
<p><strong><code>apps/blog/blog/markdown/posts/</code></strong> gets a specific instruction to ignore
grammar, phrasing, and tone entirely. I'm specifically spending effort to not write
like a robot, I can't stand the writing style. CodeRabbit shouldn't fight it.</p>
<p><strong><code>samples/</code></strong> is tutorial code I used to save examples of projects along the way.</p>
<p><strong><code>**/tests/**</code></strong> is told to focus on whether tests actually assert something,
not on style. A test that always passes is a real problem. Variable naming is
not.</p>
<h2 id="update-teaching-it-about-false-positives-2026-03-11">Update: teaching it about false positives (2026-03-11)</h2>
<p>CodeRabbit kept flagging my blog frontmatter tags as needing YAML
list format. The blog parser handles comma-separated tags on one
line, so this was a false positive on every post.</p>
<p>The fix is <code>path_instructions</code> in <code>.coderabbit.yaml</code>. I added a
note to the blog posts path telling it not to suggest converting
frontmatter tags to list format. CodeRabbit applies these
instructions on every review, so the false positive should stop
recurring.</p>
<p>You can also reply <code>@coderabbitai</code> on a PR comment to teach it
inline. It stores those as "learnings" and applies them to future
reviews. The <code>.coderabbit.yaml</code> approach is more durable since
it's checked into the repo.</p>


Kyle Pericak

"It works in my environment"

Categories

Tags