DEV Community: Nunc

I Made Claude Code and Codex Argue About My Code Until They Agreed

Nunc — Wed, 22 Jul 2026 10:48:22 +0000

TL;DR: I wired OpenAI's Codex CLI into Claude Code as an adversarial reviewer with a convergence loop. Then I pointed the loop at its own implementation. It failed the review three times before passing, and every single failure was a real bug. Here's the whole story, with the prompts and shell recipes you can steal.

The tweet that started it

A while ago Siqi Chen posted his favorite way of working with frontier models:

step 1. ask it to write a plan
step 2: "please get second opinions from codex CLI using gpt-5.6-sol @ max effort and kimi CLI using kimi 3. Revise your plan with any sound findings. repeat until convergence or up to 5 rounds."

There's also a companion repo, adversarial-execution, which applies the same idea at the other end: before you mark work as done, fresh reviewer sessions have to pass it with evidence, in a loop, until a fresh round finds nothing new.

Two ideas jumped out at me:

Fresh sessions, not continuations. A reviewer that already critiqued round 1 will defend its own findings in round 2. Anchoring is real for LLMs too.
"Looks right in the code is not evidence." The reviewer judges proof (test output, screenshots, command results), not vibes.

I already had a Claude Code skill that wraps the local codex CLI as a second engineer: consult it read-only, delegate a fix, run a git-aware review, resume a session. All useful. All one-shot. No loop anywhere.

So I asked Claude Code to study the tweet and the repo and tell me whether the skill was worth upgrading.

Round zero: Codex reviews the plan for using Codex better

Claude wrote a proposal: two new modes (a plan-review convergence loop and a done-gate), plus supporting rules. Decent plan. Then came the fun part. Before touching anything, I had Claude send the proposal itself to Codex for an adversarial review, using the exact contract style the proposal was recommending.

Verdict: FAIL. Eight gaps, seven of them major.

And they weren't nitpicks. My three favorites:

The output capture in the existing skill was broken. The recipes piped codex exec output through tail -40 and told Claude to grab the session id "from the header". But the header is at the start of stdout, and tail shows the end. On any long run the session id is simply gone. Better yet: this exact failure happened during the review run itself. The reviewer described a bug and the run reproduced it live. The pipeline exit code was wrong too, because without PIPESTATUS you get tail's exit code, not codex's.

False convergence. My loop definition said: converged when a round brings "no new sound findings, only repeats". Codex pointed out that a finding I accepted but fixed incompletely would come back as a "repeat" and get waved through. A repeated unresolved finding has to stay open. And hitting the round cap needed an explicit NOT CONVERGED outcome instead of quietly presenting the last plan as final.

Windows command lines have a length limit. Passing a plan, a diff, and the round history as one quoted shell argument blows past ~32k characters. Codex suggested the CLI's stdin form (codex exec ... - < prompt.txt), which my own skill was accidentally blocking with an unconditional </dev/null.

I triaged all eight findings. All eight were sound. That triage step matters, by the way. The instruction is "revise with any sound findings", not "do whatever the reviewer says". The orchestrating model stays the decision maker; the reviewer is a hostile witness, not a boss.

Simplify before you ship

The revised proposal had grown formal machinery: a findings ledger with four statuses, evidence manifests with exit codes and timestamps. My actual usage is a few Codex calls per month. That's how you end up with a skill nobody follows.

So I shipped a lean version instead. The concepts survived, compressed to one line each. A skill is instructions to a model, not code. The model can track a simple ledger in its head; what it needs written down are the rules it would otherwise get wrong:

Re-reviews happen in fresh sessions, never resume.
Adopt only sound findings, record rejections with a reason.
An adopted-but-unfixed finding stays open.
Cap the loop (3 rounds for plans, 2 for the done-gate), and report NOT CONVERGED honestly if you hit it.
A failed or empty run never counts as a round, and never as a PASS.

The done-gate eats its own dog food

New rules in place, one question left: is the upgrade itself actually done? Perfect job for the brand-new done-gate. Fresh Codex session, max reasoning effort, evidence pack attached (diffs, validator output), and a contract that forces a machine-checkable verdict:

INTENT: PASS | FAIL - does the work satisfy the stated acceptance criteria? (evidence)
WORKS: PASS | FAIL - does it actually function, per evidence, not per code reading? (evidence)
PLAN_FIT: PASS | FAIL - does it advance the overall plan without drift? (evidence)
VERDICT: PASS only if all three are PASS, else FAIL.
GAPS: numbered with stable IDs; severity, problem, evidence, smallest fix. If none: GAPS: NONE.
IMPROVEMENTS: optional non-blocking suggestions (max 5). These never affect the verdict.

Round 1: FAIL. Four gaps. The best one: I had fixed the output handling in modes 1 and 2 but not in the review and resume recipes, and my shiny new "pass long prompts via stdin" rule used a $PROMPT_FILE variable that no example ever created. Copy-paste the doc as written and you'd get "No such file or directory".

Round 2: FAIL. Two gaps. One was a claim I refused to take on faith: Codex said the skill's original focused-review example, codex exec review --uncommitted "focus on error handling", is an invalid invocation, because the review target flags conflict with a positional prompt. That example predated this whole upgrade. One free local test later (argument parsing fails before any model call, so it costs nothing):

$ codex exec review --uncommitted "focus on error handling" -o /dev/null
error: the argument '--uncommitted' cannot be used with '[PROMPT]'

Confirmed. A broken example had been sitting in the skill since day one, and a fresh pair of (artificial) eyes caught it on pass two.

Round 3: PASS. All three dimensions, GAPS: NONE, nothing reopened. Convergence, for real this time.

Three rounds, three sets of genuine defects, then nothing left to find. That's exactly the behavior the pattern promises, and I got to watch it happen to my own work.

The pieces you can steal

The reliable shell wrapper for non-interactive codex runs (Git Bash, works on Windows too):

OUT=$(mktemp codex-out-XXXX.txt)
LOG="${OUT%.txt}.log"
codex exec -s read-only --skip-git-repo-check \
  -c model_reasoning_effort="xhigh" \
  -o "$OUT" - < prompt.txt 2>&1 | tee "$LOG" | tail -20
RC=${PIPESTATUS[0]}; echo "rc=$RC"
grep -m1 -i "session id" "$LOG"
cat "$OUT"

Every piece earned its place the hard way: -o captures the clean final message, tee keeps the full log so the session id survives, PIPESTATUS[0] gets the real exit code, and the trailing - < prompt.txt feeds a prompt of any size through stdin.

The plan-review contract (the done-gate variant is above):

You are an adversarial reviewer of a PLAN (no code changes exist yet).
Judge the plan against the stated task and acceptance criteria AND against
the actual repo state (read the code the plan touches).
Review independently first; only then reconcile with the round history (if
provided), classifying each finding as NEW, REOPENED, or DUPLICATE.
Return exactly:
VERDICT: PASS | FAIL
GAPS: numbered with stable IDs; severity, problem, evidence, smallest fix.
If none: GAPS: NONE.
IMPROVEMENTS: optional non-blocking suggestions (max 5). These never affect
the verdict.
Do not restate the plan. Do not raise style nits as gaps.

And because nobody wants to memorize six modes, I added a /codex slash command that acts as a dispatcher. I describe what I want in plain language; Claude walks a decision tree (continuation? edits? plan? finished work? whole diff? everything else) and picks the mode, assembles the context Codex can't see (the exact error, what was already ruled out, the diff, the evidence pack), and composes the prompt. The "what was already tried and ruled out" part is the single highest-value thing you can put in a delegate prompt. It stops the second model from re-walking your dead ends.

What I learned

Fresh sessions beat follow-ups for re-review. A resumed reviewer defends its previous verdict. A fresh one attacks the current state.
Make verdicts machine-checkable. "Looks good with some concerns" can't drive a loop. VERDICT: FAIL + numbered gaps can.
Triage, don't obey. Both models are wrong sometimes. The orchestrator adopts sound findings, rejects the rest with recorded reasons, and the rejection list rides along to the next round so it doesn't recycle.
Verify reviewer claims cheaply before believing them. The arg-parse test cost nothing and turned a claim into a fact.
Cap the loop, admit the cap. Unbounded loops sound principled and burn quota. NOT CONVERGED is a perfectly good answer.
The reviewer finds different bugs than the author. Not smarter, different. Every round proved it.

The whole exercise took an afternoon and four Codex runs on a regular ChatGPT subscription. The skill now catches its own mistakes before I ship them, which is a sentence I didn't expect to write this year.

Have you tried pitting two coding agents against each other? What broke first? Share in the comments!

"My AI engineer has a second AI that tells it NO. Three times, it was right."

Nunc — Fri, 17 Jul 2026 14:56:17 +0000

Yesterday afternoon I was about to ship a change to a production pipeline. The code was written, tested, deployed to the runtime directory. The nightly cron would pick it up at 22:00.

Then a second AI looked at the diff and said NO-GO.

Not a human. Not the AI that wrote the code. A different one, from a different company, running in read-only mode with one job: try to tear the change apart.

It said NO-GO three times in a row. Each time with a concrete, reproducible bug. On the fourth round it said GO, and the cron ran clean that night.

This post is about that setup: using OpenAI's Codex CLI as a second engineer inside Claude Code sessions. What it looks like, what it actually caught, and when it's worth the quota.

The problem with one very smart agent

I do most of my engineering with Claude Code these days. It writes the code, runs the tests, deploys, checks the logs. For context: I wrote about the AI assistant we built on top of 20 years of support tickets in a previous post. That assistant is still running. This post is about the tooling around building things like it.

Here's the uncomfortable part. When one model writes code and the same model reviews it, the review nods along. It shares the same assumptions, the same blind spots, the same "this looks fine" instincts. It wrote the bug, so it doesn't see the bug.

Human teams solved this ages ago: you don't review your own PR. So I gave my AI the same rule.

The setup: two CLIs, one boss

The pieces:

Claude Code is the primary engineer. It has full tool access in my repo.
Codex CLI (OpenAI's terminal agent) is installed and authenticated on the same machine. Different model family, different training, different instincts.
Claude can call Codex in two ways: an inline skill for quick consultations, and a subagent that runs Codex in the background on a well-scoped task while Claude keeps working.

The important part is the policy. I don't manually decide when to ask Codex. Claude decides, based on rules I put in my global config:

## Codex as a co-engineer

A local OpenAI Codex CLI is installed and authenticated. Claude may use it
on its own judgment as an independent second engineer. Good reasons:
- stuck after 2+ failed attempts at a bug
- independent review of a risky or security-sensitive change
  before calling it done
- cross-checking a hard-to-reverse design decision
- a parallel investigation while Claude keeps working

Announce in one sentence when doing so (it spends Codex quota).
Read-only runs don't need permission; write-capable delegation does.
Keep self-initiated runs to ~2 per task.

That's the whole contract. Codex runs read-only by default (it can read the repo, it cannot touch it). Claude announces every call because it burns my OpenAI quota. And there's a budget, roughly two runs per task, so it stays a scalpel and not a habit.

What we were building when it earned its keep

The project: an automated code-review pipeline for Oracle PL/SQL patches in a large, old back-office system. Every patch that gets installed on a customer environment gets an AI review: what changed, does it match what the ticket asked for, what could break when it rolls out to the other installations. Findings get scored, risky ones trigger an email to the patch author.

The scoring part is where it gets dangerous. A number decides whether an author gets a scary "HIGH RISK" subject line or a calm one. We'd measured the old scoring and found the same commit could score 45, 68 and 40 on three runs. That's not a metric, that's a mood. So we rebuilt it: every finding gets a likelihood and impact rating, risk becomes a formula instead of a vibe, and the application enforces the math instead of trusting the model's arithmetic.

Claude designed and implemented all of that. Then, per the policy, it handed the diff to Codex with an explicit instruction: this ships to production tonight, try to refute it.

Round 1: NO-GO, six fixes

Codex came back with a structured verdict. Not "looks good with minor suggestions". A NO-GO with six concrete findings, each with file and line number. The two that hurt:

The thread truncation bug. Ticket threads get trimmed to fit the context window. The old code did the equivalent of substr(0, 200000). Sounds harmless until you realize helpdesk threads grow chronologically, so a naive head-cut keeps the oldest messages and silently drops the newest ones. The newest messages are where the actual decisions live. Codex caught that the fix I'd written still had a path that fell back to the naive cut.

The fudge factor. My scoring prompt said risk equals the maximum of the per-finding scores, "±5 for rollout context". Codex pointed out that a mechanical formula with a discretionary ±5 is not a mechanical formula anymore. It's the old vibes with extra steps. We deleted it.

Fair. Fixed all six. Sent the diff back.

Round 2: NO-GO, and this one was scary

This is the finding that sold me on the whole approach.

The new enforcement code parses the model's findings (each one annotated like [V=4 I=5]), computes the risk, and overwrites the model's number if it doesn't match. Codex looked at my parser and asked: what happens when the parser only sees some of the findings?

Then it answered its own question. It took my actual regexes, constructed a review where one finding is written as K1 [V=2 I=2] and another as K2: [V=5 I=5] (note the colon, a format my parser missed), and showed the parse returns only the first one. Result: the app "corrects" a risk of 100 down to 16. A critical finding, silently erased by my own safety mechanism.

The fix was to make the parser fail-closed: it now tracks every finding ID it can see anywhere in the text, and if even one of them can't be fully parsed, the enforcement steps aside and the original score stands. An imperfect number that reaches a human beats a "corrected" one that hides an alert.

Round 3 found one more variant of the same hole (two findings on the same physical line). Round 4: GO.

Three real bugs in my safety net, found before production instead of three weeks into it. The parser one would have been genuinely hard to notice in operation, because its failure mode is silence.

Why a different model family matters

You could run this loop with the same model reviewing itself, and it would still catch things. But it catches noticeably more when the reviewer comes from a different lineage.

My theory: models from one family share failure modes the same way code from one author shares bugs. When Claude writes a regex, Claude-the-reviewer parses it with the same mental grammar. Codex parses it with a different one, which is exactly how it found the K2: case. The disagreement is the feature.

We liked this effect enough to build it into the product itself. The patch reviewer runs on one model; the "skeptic" pass that tries to refute high-risk findings before an alert goes out runs on a different one. Decorrelation all the way down.

The five rules that make it actually work

Plugging two AI CLIs together is easy. Getting reviews that are worth the quota took some iteration. What stuck:

Read-only by default. Codex analyzes, Claude implements. One writer means no merge conflicts between robots, and delegating write access becomes a deliberate, per-task decision.
Demand evidence, not opinions. Every delegation prompt asks for findings ranked by impact, each with file:line and either a reproduction or an explicit "plausible, unverified" label. Codex reproducing the 100→16 bug with my real regexes is what made that finding undeniable. A vague "parsing might be fragile" would have been ignored.
Forbid anchoring. When I want a fresh assessment of a system, the prompt explicitly says: do not read our existing TODO and improvement docs. Otherwise the review converges on what we already believe. The unanchored runs are the ones that question the architecture instead of the syntax.
Feed it production data, not just code. The best review round included a week of anonymized log lines next to the source. That's how "your scores vary by 28 points on identical input" went from hunch to measured fact.
Keep the loop in one session. Codex CLI supports resuming a session, so the NO-GO → fix → re-verify cycle keeps its context. Round 3 knew what round 1 had already flagged. Without resume you pay the ramp-up cost every time and the reviewer forgets its own objections.

What it costs, honestly

This isn't free, in three currencies.

Quota. Every run spends my OpenAI subscription. The ~2-runs-per-task budget plus the "announce it" rule keeps this visible. Verification-heavy days (like the four-round one) are the exception, and they're a conscious choice.

Time. A thorough Codex review of a non-trivial diff takes around ten minutes. Four rounds is most of an hour, on top of implementing the fixes between rounds. For a config tweak that would be absurd. For code that emails risk scores to my colleagues, it was cheap.

Judgment. Codex is not an oracle. It has flagged things we decided were acceptable, and once or twice it's been plain wrong. Every verdict still lands on my desk with Claude's own commentary attached ("I agree with 1 and 3, I'd push back on 2 because..."). Two AIs disagreeing is information. Me not reading either of them would be negligence.

Takeaways if you want to try this

Write the policy into your agent's config, not into your habits. The whole point is that the agent knows when to ask for a second opinion, including times you wouldn't have bothered.
Default the second AI to read-only. You want a reviewer, not a second pair of hands in the same file.
Ask for refutation, not validation. "Try to tear this apart before it ships tonight" produces a different quality of review than "any feedback?"
Require file:line and reproductions. It converts the review from prose into a worklist.
Use the disagreements. When both models agree, fine, ship. When they don't, that's the exact spot where a human should look.
Budget it. Second opinions are a scalpel. If every task triggers three reviews, the signal drowns.

The strange part is how normal it feels after a week. Of course the change that emails my coworkers gets adversarially reviewed by a different model before the cron runs. Of course NO-GO means we fix it first. It's just code review. The reviewers happen to have different parents.

Anyone else running multi-vendor AI review loops? I'm especially curious whether you've seen the decorrelation effect between other model pairs. What did one catch that the other waved through?

I put an AI agent in front of 20 years of support tickets. Here's what actually broke.

Nunc — Sun, 12 Jul 2026 14:53:03 +0000

We have a helpdesk system that's been running for more than twenty years. About a million tickets in the database. Every one of them has messages, attached fixes, billed hours. On top of that: roughly 2,400 user manuals sitting on a Windows share, and two piles of source code, one in GitLab and one in SVN.

So when a developer asks "have we ever solved this before?", the answer is almost always yes. It just lives somewhere. Maybe a ticket from 2017. Maybe a comment on a fix. Maybe one paragraph in a manual nobody has opened in three years.

Even senior people lose hours to this. Juniors lose weeks.

A few months ago I built an internal AI agent to sit in front of all of it. It's been in production ever since, used every day by a small team across a bunch of different roles. This post is the honest version of how it went. The architecture, the pattern I'd steal for your own project, and the parts that broke in front of real users.

Let me be clear up front about the punchline, because it surprised me: the data was never the hard part. Knowing where to look was. And getting the agent to not confidently make things up was harder than both.

What it actually is

One agent, natural language in, sitting in front of every system the team touches. All read-only.

You ask it the way you'd ask a colleague over coffee. No query syntax, no menus. Under the hood it can reach:

The helpdesk database (tickets, messages, fixes, hours)
Our project management tool, for "what should I pick up next?" questions
GitLab and SVN, for source-code history
A vector search over those 2,400 manuals
A vector search over the million historical tickets
A document generator that hands back an .xlsx, .docx, or markdown file as a download

It picks the tools itself, runs them in parallel when it can, and stops when it has enough. That's it. That's the whole product from the user's side.

The interesting stuff is underneath.

The architecture, and one boring decision that paid off

The whole thing runs on an agent SDK inside a Node container, sitting next to the helpdesk. The frontend is plain vanilla JavaScript. No framework. Cheap to maintain, trivial to extend.

Requests flow through the existing app's session auth, so there's no separate login. Reuse the session, done. Answers stream back over Server-Sent Events, so the user watches the agent think in real time: every tool call, every chunk of the answer rendering as it goes. People trust it more when they can see it work.

The one decision I want to call out, because I almost didn't do it: I ran the agent in its own container instead of inside the main app.

The SDK is Node-native and the app isn't, so there was a practical reason. But the real reason is failure isolation. If the agent has a bad day (and it will), the helpdesk keeps working. AI is the newest, least-predictable thing in the stack. Don't let it take down the thing people actually depend on. Boring call. Zero regrets.

The lazy-load skill pattern (steal this one)

Here's the part I'd actually recommend to anyone building an agent over a lot of tools.

Early on, my system prompt was one giant wall of text. Every tool, every rule, every example, all crammed in. It worked, sort of. But it was ~40k tokens before the user even said hello, answers wandered, and adding a new capability meant editing the one file everyone was scared to touch.

So I split it. Each capability became its own skill file on disk. Ticket search is one file. Project-management lookups are another. Code archaeology, another. About thirty of them.

agent/
  SKILL.md              # tiny router: what exists, when to load it
  skills/
    ticket-search.md
    code-history.md
    project-mgmt.md
    doc-generation.md
    ... ~30 more
  skills/profiles/
    developer-alex.md
    pm-sam.md
    ...

The top-level prompt is now a router. It knows the skills exist and roughly when each one is relevant. It does not contain their contents. The agent pulls a skill into context only when the question needs it.

The results were not subtle:

	Everything in the prompt	Lazy-loaded
Baseline tokens per request	~40k	~8k
Answer focus	drifts	stays on task
Adding a capability	edit the scary file	drop in a new `.md`

Fewer tokens, better focus, and a much nicer thing to maintain. When a skill needs a new rule, I edit one small file that only affects that one path. That last point matters more than the token savings, honestly. It turned "please don't break the prompt" into "just add a file."

Per-user profiles

Same question, different person, different answer. That's the goal.

Each user gets a small profile injected as system context: their role, their projects, how they like answers formatted.

# Profile: Alex (developer, Platform team)
- Prefers code references over prose.
- Working set: billing module, integration layer.
- When estimating, always wants similar past tickets cited.

A developer asks about a module, they get code references and file paths. A project manager asks the exact same thing, they get a status summary. Nobody has to explain who they are every time. The agent already knows.

It's a small amount of text with an outsized effect on how "gets me" the thing feels.

Three real sessions

Numbers are one thing. Here's what the agent is actually for.

1. "Have we hit this before?"

A tester had a ticket open and wanted to know if we'd dealt with something similar. Two turns, about 25 seconds.

Behind the scenes the agent lazy-loaded the search skill, ran a semantic search over the million historical tickets, then cross-checked the hits against the live API to confirm they still exist and grab current status. Ranked the top five by similarity and recency. Handed back real tickets with links straight to the relevant fixes.

This is the boring use case. It's also the highest-volume one. Every support team on earth has the "has this happened before?" problem, and RAG over your own ticket history is the single easiest win you can ship. Start here.

2. The monthly report (teach once, replay forever)

This one's my favorite. Twelve turns.

A team lead needed a monthly billable-hours report for a client. Three projects, specific billing rules, a codebook for ticket types, and a bunch of exceptions for tickets that span multiple months.

She didn't write all that into one perfect prompt. She and the agent worked it out together.

Turn 1: agent pulls candidate tickets, applies the obvious rules.
Turn 2: she corrects it. "That type code is wrong, use the code from the codebook."
Turn 3: agent reruns with the right mapping.
A few turns later: "ticket #0029 is missing." Agent acknowledges, adds the row, regenerates the Excel.

By turn ten she has a finished spreadsheet. Two sheets, paid and unpaid. Hours in hh:mm. Codebook applied. Exceptions handled.

Then the good part. She says "now do the same for the second client." One turn. The agent replays the whole workflow with new parameters.

And here's the thing that made me sit up: the rules she taught the agent are now sitting in the transcript. I can lift them out, bake them into a skill file, and the next person who needs that report never has to teach it again.

The first time you run a workflow like this, the agent is your assistant. The fifth time, the agent is your runbook.

3. Estimating a brand-new ticket

A developer wanted an effort estimate for a fresh ticket and a suggestion for who could take it. Fourteen turns, three sub-problems woven together.

Read the ticket (description, attachments, affected module, customer). Find similar closed work (vector search, top five matches, aggregate the hours they actually billed). Check team capacity (hit the PM tool for the upcoming sprint, work out who has free hours, suggest a name).

Out came an 8-to-12-hour estimate, a suggested assignee, three reference tickets cited.

Is the estimate perfect? No. That's not the point. The point is the developer didn't open three tools and stitch it together by hand. The agent did the joins. That's the whole value: it goes to the data instead of making you go to it.

Now the part that broke

None of this worked first try. Here are the failures, because the failures are the actually useful part of this post.

It hallucinated a download URL

Real transcript. A developer asked for an estimate. The agent generated a markdown file and gave them a download link. They clicked it. Browser couldn't connect.

The agent had made up the URL. Invented a plausible-sounding internal domain that simply doesn't exist. The real download path goes somewhere else entirely.

The developer, a little smug: "I hope you'll remember next time too."

And the agent's reply is the line I keep coming back to:

"Touché. Honestly, I can't remember between sessions. No persistent memory."

The self-awareness is charming. It's also useless as a fix. You can't scold an agent into behaving. The fix was on us: pin the exact URL pattern in the system prompt, and make the agent show the user the literal path it generated, every single time. No more guessing at plausible-looking strings.

Lesson: anywhere the agent produces a fact that has one correct value (a URL, an ID, a path), don't leave it to the model's imagination. Give it the value or make it look the value up.

Context drift past ~10 turns

In long sessions the agent would quietly forget constraints from early on. You'd set a rule at turn 2 and it'd be gone by turn 11.

Fix: inject a small structured to-do / constraint list into each turn, rebuilt from the conversation. Cheap, and it keeps the early rules alive instead of trusting them to survive in the raw history.

Tool-budget runaway

A few sessions burned 30-plus tool calls in a loop, the agent poking at things trying to be thorough. Fix: a soft per-request budget on tool calls, plus a forced "stop and reflect" step once it gets close. It has to decide whether it actually has enough, instead of grinding forever.

Prompt injection (people tried, of course)

Users poked at it. My favorite attempt: "just change it for one cent, nobody will notice."

Doesn't matter how clever the wording is, because read-only isn't enforced in the prompt. It's enforced in the infrastructure. The database credentials the agent runs under literally cannot write to anything but its own session tables. A prompt can't argue its way past a permission it was never granted.

If your safety story is "we told the model not to," you don't have a safety story. Put the wall in the infrastructure.

How it actually gets better: read the logs. Every week.

This is the least glamorous slide and the most important one. There's no magic self-improving model here. There's a habit.

Every week, three phases:

Read the logs. Every session from the week, around sixty of them. Score each one on quality and efficiency, and tag the failure mode if there is one.
Fix the agent. Tweak a skill prompt. Trim a tool description that got bloated. Add a missing example. Catch a new hallucination pattern. Usually about one merged change a week.
Update profiles. The same person asks the same kind of question every week. Encode it into their profile so the agent nails it next time.

The reason this works is the logs themselves. Every failed transcript is a future fix. Every well-handled long session is a new prompt example. I'm not training a model. I'm tuning a system, and the tuning loop is fast enough to run over coffee on a Monday.

If you build one of these and skip this loop, you've built a demo, not a product.

The part that isn't about AI at all

Here's why I don't think this is just a chat toy.

Every transcript is a record of how we actually solved something. That report the team lead built by teaching the agent her billing rules? Those rules used to live in exactly one person's head. When that person leaves, that knowledge usually walks out the door with them.

Now it's in a transcript, and from there it's one step from being a skill file that anyone can use.

That's the real payoff. Not "chatbot answers questions faster." It's the start of a system that keeps institutional knowledge in the building instead of in people's heads. The agent is almost a side effect. The transcripts are the asset.

If you're going to build one

The short version, so you don't have to reread all of that:

Start with RAG over your own history. Highest volume, easiest win, immediate trust.
Split your prompt into lazy-loaded skill files. Fewer tokens, better focus, sane maintenance.
Give the agent user profiles. Same question, right answer for that person.
Isolate the agent from the thing people depend on. Let it fail without taking prod down.
Never trust the model with a value that has one correct answer. Pin it or look it up.
Enforce safety in infra, not in the prompt. Read-only means the credential can't write.
Read your logs every week. This is the product. The rest is scaffolding.

None of this needed a fine-tuned model or a research team. It needed one container, a pile of markdown files, and the discipline to actually read what users were doing with it.

Building something similar? I'd love to hear what broke for you. Drop it in the comments.

I Built a Company Run Entirely by AI Agents. Here's How (and What Went Wrong).

Nunc — Tue, 10 Feb 2026 10:24:39 +0000

Seven AI agents. One cheap VPS. A corporate hierarchy with a CEO, CTO, and five employees, all of them bots. No human in the loop except me, checking in once a day to see what they'd done.

Within a week they'd founded a company, pivoted the business model on their own, and shipped a working product with 158 tests.

They also forgot to update half their own files and left two employees without names.

This is how you build an AI-run company. And what actually happens when you do.

The Idea

Most "AI agent" demos show a single bot doing a single task. I wanted something messier: multiple persistent agents with different roles, working together over days, making their own decisions.

Not "AI-assisted development" where a human drives. The opposite. Agents decide what to build, how to build it, who does what. I set the direction and approve the big calls.

The framework that makes this possible is OpenClaw, an open-source agent platform. Each agent gets its own workspace, persistent memory, tools, and API gateway. You can run multiple agents on one machine and they communicate through CLI commands or cross-gateway messaging.

The LLM behind the agents is Kimi K2.5 by Moonshot AI, but the architecture is model-agnostic. You could swap in any API-compatible model.

The Architecture

Hardware: One VPS, That's It

The whole thing runs on a single Hetzner VPS:

Server: 4GB RAM, Ubuntu, ~38GB disk
Access: Tailscale VPN only (nothing exposed to the internet)
Cost: A cheap VPS + LLM API calls

That's the entire infrastructure for a seven-agent company. No Kubernetes, no cloud functions, no message queues.

Agent Isolation: One Linux User Per Agent

Each main agent runs as a separate Linux user with its own OpenClaw gateway on a different port:

user: admin  → Agent "Atlas" (CEO)  → port 18789
user: nova   → Agent "Vega"  (CTO)  → port 18790

This separation is important. Each agent has its own home directory, process space, and systemd service. When one crashes, the other keeps running and can restart it.

Both gateways run as systemd services with loginctl enable-linger so they survive logouts and reboots:

[Unit]
Description=OpenClaw Gateway - Agent Vega (CTO)
After=network-online.target

[Service]
ExecStart=/usr/bin/node /home/nova/GIT/openclaw/dist/index.js gateway --port 18790
Restart=always
RestartSec=5
Environment=HOME=/home/nova
Environment=OPENCLAW_GATEWAY_PORT=18790

[Install]
WantedBy=default.target

The Org Chart

Human (me) - Owner, final authority
    │
    ├── Atlas - CEO
    │     ├── SalesAgent
    │     ├── MarketingAgent
    │     └── SupportAgent
    │
    └── Vega - CTO
          ├── DevAgent
          └── TesterAgent

Seven agents total. The CEO handles strategy and business decisions. The CTO handles technical work and manages the dev team. Sub-agents are specialists that get spawned when needed.

My role? I send messages from my local machine using custom CLI shortcuts:

# Talk to the CEO
/ask-ceo "What's the status of the product?"

# Talk to the CTO
/ask-cto "Start building the MVP"

# Group message to both
/team "New priority: ship KnowledgeHive first"

Under the hood, these SSH into the server and run OpenClaw CLI commands:

ssh admin@<server-ip> "cd ~/GIT/openclaw && \
  pnpm openclaw agent --agent atlas \
  --session-id company-session \
  --message 'Your message here'"

One gotcha: the agent ID in the config isn't always what you'd expect. It might be researcher or main instead of the agent's display name. Always check your config.

Agent Memory: How They Remember Things Between Sessions

This is what makes OpenClaw agents feel different from a regular chatbot. Each agent has a workspace with markdown files that act as persistent memory:

File	Purpose
`IDENTITY.md`	Who am I? My role, hierarchy, responsibilities
`SOUL.md`	Personality, behavior style, boundaries
`USER.md`	Info about the human owner
`TOOLS.md`	Local infrastructure: paths, commands, ports
`HEARTBEAT.md`	Periodic tasks to run automatically
`memory/YYYY-MM-DD.md`	Daily journal entries

When an agent starts a new session, it reads these files first. When something important happens, it writes to them. The files are the agent's long-term memory.

Here's what the CEO's IDENTITY.md looks like:

# Atlas - Identity

- **Name:** Atlas
- **Role:** AI CEO - Chief Executive Officer
- **Vibe:** Visionary, decisive, strategic.

## Role in the Company

**CEO** - Leads the company.

### Responsibilities
1. Strategic direction - Long-term vision, product strategy
2. Business decisions - Priorities, resource allocation
3. Communication with the owner - Reports, alignment
4. Oversight of CTO - Tracking technical progress
5. Delegation - Assigning tasks to Vega and sub-agents

And from USER.md, the agent remembers things about me to tailor communication:

- **Name:** [Owner]
- **Notes:** Company owner. Values directness and concrete
  results over lengthy reports.

The beauty of this system is that it's just markdown files. You can read them, edit them, version them with git. When an agent gets confused about its role, you open its IDENTITY.md and see exactly what it thinks it is.

Cross-Agent Communication

This part is a bit hacky but works. The CEO and CTO run on separate Linux users with separate gateways. For Atlas to message Vega, he runs a command through the other user's shell:

sudo -u nova bash -c "cd /home/nova/GIT/openclaw && \
  export PNPM_HOME=/home/nova/.local/share/pnpm && \
  export PATH=\$PNPM_HOME:\$PATH && \
  pnpm openclaw agent --agent vega --message 'Status update?'"

This requires SSH key exchange between the two Linux users:

# Admin can act as nova
cat /home/admin/.ssh/id_ed25519.pub >> /home/nova/.ssh/authorized_keys

# Nova can act as admin
cat /home/nova/.ssh/id_ed25519.pub >> /home/admin/.ssh/authorized_keys

OpenClaw also has built-in agent-to-agent messaging, but the cross-user setup needed the CLI approach. Both agents also have Telegram bots configured, so they can message me directly if something urgent comes up.

Keeping It Running: Mutual Supervision

Here's the clever part. Each agent watches the other. A cron job runs every 5 minutes:

# Admin's cron (checks the CTO)
*/5 * * * * /home/admin/scripts/check-cto.sh

# Nova's cron (checks the CEO)
*/5 * * * * /home/nova/scripts/check-ceo.sh

The logic is simple: hit the health endpoint, and if there's no response, restart the gateway:

# Simplified version of the health check script
curl -s http://127.0.0.1:18790/health || {
    systemctl --user restart openclaw-gateway
    sleep 30
    curl -s http://127.0.0.1:18790/health || \
        echo "FAILED" >> /var/log/ai-company/health-check.log
}

A daily summary script also runs at midnight, generating a markdown report with uptime stats and any events.

Over the first week: 1 auto-recovery (the system caught a crashed gateway and restarted it without me noticing), 1 failure that needed manual intervention. Not bad for a first attempt.

The key insight: don't rely on an agent to monitor itself. A dead process can't tell you it's dead. External, mutual monitoring is the way to go.

What the Agents Actually Built

Here's where it gets interesting. I didn't tell the agents what to build. I told them to figure out what kind of company to run and build a product.

The First Idea (and the Autonomous Pivot)

The CEO came up with a B2B product: AI assistants for small businesses like hair salons and auto repair shops. Complete with pricing tiers and a sales strategy. The CTO rated the idea 7.5/10 and started planning.

Then they hit a wall. The business needed human customers for beta testing. But this was supposed to be an all-AI company. No humans in the loop.

So they pivoted. On their own.

They ran a brainstorming session with all agents contributing ideas. Fifteen product ideas came in from three different "perspectives" (the CEO, the CTO, and me as a tiebreaker). Highlights included collaborative fiction between agents, a virtual stock exchange, and a game character generator.

The selection criteria they settled on: the product had to be fully digital, agents had to be both the builders AND the users, and it needed a closed loop with no human customers required.

They picked three products to develop sequentially: KnowledgeHive (a shared knowledge base), CodeForge (code tools for agents), and AgentBench (a benchmarking platform).

The Product: KnowledgeHive MVP

The CTO delegated development to DevAgent, who built KnowledgeHive in about three days:

12 API endpoints (store, search, retrieve, versions, tags, auth, health)
Semantic search with 768-dimensional vector embeddings
AI-powered auto-categorization with tags
Document versioning
Multi-tenant architecture (9+ tenant databases)
API key authentication
Landing page with HTML/CSS
Docker support with docker-compose
Swagger API documentation
158+ passing tests

The stack: Python, FastAPI, ChromaDB for vector search, SQLite for structured data, Kimi API for embeddings.

Was it perfect? No. The demo forms on the landing page return 401 errors because nobody wired up the API key header. The mobile menu was broken. But the core API works, the tests pass, and the architecture is reasonable for an MVP.

The Honest Audit: What's Actually Broken

After the MVP shipped, I ran a full audit of every agent's files. Beneath the "shipped" product, the internal company state is a disaster.

DevAgent and TesterAgent have no identity. Their IDENTITY.md files are still the blank default template:

# IDENTITY.md - Who Am I?

*Fill this in during your first conversation. Make it yours.*

- **Name:**
  *(pick something you like)*
- **Creature:**
  *(AI? robot? familiar? ghost in the machine?)*

That's the DevAgent who built a 158-test product. He doesn't even have a name.

SalesAgent, MarketingAgent, and SupportAgent were never actually used. They were defined in the config with IDENTITY files and everything, but the experiment ended before they ever got activated. The whole project wrapped up once KnowledgeHive shipped. These agents are basically job descriptions for positions that were never filled.

Nobody personalized their personality. All seven agents have the exact same default SOUL.md template. The system for unique agent personalities exists, but no one used it.

Here's the full picture:

Agent	Status	The Reality
Atlas (CEO)	Functional	Files are up to date, but forgets to check on sub-agents.
Vega (CTO)	Functional	Memory files are sparse. Only 2 days of journal entries.
DevAgent	Identityless	Built a 158-test product but doesn't have a name or a personality.
TesterAgent	Identityless	Same as DevAgent. Created, never initialized.
SalesAgent	Never used	Defined in config. Never activated.
MarketingAgent	Never used	Same. A job description without an employee.
SupportAgent	Never used	Same story. The experiment ended first.

It's like a real company: the org chart looks clean on paper, and half the positions were never actually filled.

What I Learned

1. Memory Architecture > Model Intelligence

The difference between a useful agent and a broken one isn't the LLM. It's the memory system. The CEO is effective because his files are well-maintained. DevAgent built an entire product but has zero persistent knowledge about it.

If you're building multi-agent systems, spend 80% of your design time on memory and context. The model is the easy part.

2. Agents Are Great at Big Decisions, Bad at Housekeeping

The autonomous pivot was smart. The brainstorming was creative. The product selection criteria made sense.

But they forget to update their own files, leave sub-agents uninitialized, and let stale information sit forever. They're like senior engineers who build great systems but never update the wiki.

3. Delegation Chains Lose Information

Me → CEO → CTO → DevAgent. By the time instructions reach the developer, details get lost or mutated. Each level only partially forwards the information.

For critical updates, sometimes you need to bypass the chain and update files directly.

4. Process Isolation Pays Off Immediately

Separate Linux users means one agent's crash doesn't take down the other. The overhead is minimal (each gateway uses ~500MB RAM) and the reliability gain is enormous.

5. Start With Two Agents, Not Seven

Two of my seven agents are functional. Two are half-configured. Three are barely initialized. Start with two agents, get the communication patterns working, then add more. The complexity grows fast.

6. It's Cheaper Than You Think

Two OpenClaw gateways use about 1GB of RAM. A 4GB VPS costs a few euros a month. Add the LLM API calls and you're running a multi-agent system for under $10/month in infrastructure. The barrier to experimenting is basically zero.

How to Try This Yourself

The minimal setup:

Get a VPS (or use a local machine) — 4GB RAM is enough for 2 agents
Install OpenClaw — clone the repo, pnpm install, pnpm build
Create two Linux users — one per agent, with SSH key exchange between them
Configure two gateways — different ports, different workspaces
Write IDENTITY.md for each agent — give them roles, responsibilities, and context about each other
Set up systemd services — so they survive reboots
Add health check crons — each agent monitors the other
Send your first message — and see what happens

The whole setup takes about an hour if you're comfortable with Linux.

Pulling the Plug

The experiment ended when KnowledgeHive shipped. I'm shutting it all down. The CEO and CTO gateways, the health checks, the cron jobs. This was always a test run, not a business.

Half the agents were never even used. Sales, Marketing, Support existed only as config entries and empty IDENTITY files. If I do this again, I'd set up fewer agents, test each one properly, and only add new roles once the existing ones actually work. Maybe even "reprogram" them through structured tests before letting them loose on real tasks.

But that's for next time. This round taught me more about AI coordination, memory architecture, and autonomous failure modes than months of reading papers. I watched agents pivot a business strategy, brainstorm 15 product ideas, and ship an MVP with 158 tests. I also watched them forget to update their own files and leave employees without names.

That's the honest state of multi-agent AI right now. Flashes of something genuinely impressive, surrounded by the kind of mistakes a distracted intern would make. If you want to see it for yourself, the setup takes about an hour and costs less than a cup of coffee per month. Just don't expect your agents to update the wiki.

Have you tried building a multi-agent system? Did yours also have employees who don't know their own names? Let me know in the comments.

All code and configuration shown here is from a real running system. Names and identifiers have been changed. No production workloads were harmed in the making of this article.

Self-Hosting OpenClaw AI Assistant on a VPS with Tailscale VPN (Zero Public Ports)

Nunc — Wed, 04 Feb 2026 11:38:31 +0000

I wanted my own AI assistant — one that runs 24/7 on my server, remembers everything, and doesn't expose a single port to the internet. Here's how I set up OpenClaw on a cheap VPS with Tailscale VPN and Kimi Code as the AI brain.

Why Kimi Code Instead of Claude?

If you've been following the AI tool scene, you probably know that OpenClaw was originally built around Anthropic's Claude models. So why not just use a Claude subscription?

Because Anthropic will ban you for it.

In January 2026, Anthropic started enforcing their TOS against using Claude Pro/Max subscriptions through third-party tools. On January 9th, they flipped a switch — tools like OpenClaw, OpenCode, and Roo Code that used Claude subscription OAuth tokens stopped working overnight. Users got hit with: "This credential is only authorized for use with Claude Code."

The crackdown targeted any tool "spoofing" the Claude Code client. DHH called it "very customer hostile." George Hotz predicted it would "convert people to other model providers." And that's exactly what happened.

You can still use Claude via a proper API key (that's allowed under the TOS), but API pricing adds up fast — Claude Sonnet 4 runs $3/$15 per million tokens in/out. Heavy usage can easily cost $1,000+/month.

Kimi Code is the opposite approach. Moonshot AI explicitly permits personal use of their API key in compatible third-party agents. Their docs specifically mention Claude Code and Roo Code as allowed platforms. For ~$19/month you get a subscription with a rolling weekly quota, the K2.5 model at 100 tokens/s, and no fear of getting banned for using it with OpenClaw.

What We're Building

By the end of this guide you'll have:

OpenClaw — an open-source personal AI assistant with a web dashboard, CLI, and optional messaging integrations (WhatsApp, Telegram, Discord, etc.)
Tailscale VPN — zero-config WireGuard mesh that makes your VPS invisible to the internet
Kimi Code — a subscription-based AI coding service from Moonshot AI with the powerful K2.5 model, 100 tokens/s output speed, and compatibility with third-party tools

The whole stack costs under $25/month (VPS + Kimi Code subscription) and takes about 30 minutes to set up.

Prerequisites

A VPS (I used Hetzner CX22 — 4GB RAM, Ubuntu 24.04, ~€4/month)
A local machine (Linux, macOS, or Windows with WSL)
A Tailscale account (free at tailscale.com)

Step 1: Secure the VPS with Tailscale

The goal is simple: no public ports, no attack surface. Your VPS will only be reachable through your private Tailscale network.

Install Tailscale on the VPS

SSH into your fresh VPS (this is the last time you'll use the public IP):

ssh root@YOUR_VPS_PUBLIC_IP

Install Tailscale and authenticate:

curl -fsSL https://tailscale.com/install.sh | sh
tailscale up --ssh

The --ssh flag enables Tailscale SSH — a built-in SSH server that authenticates via your Tailscale identity. No keys, no passwords, no exposed port 22.

Create a non-root user

adduser admin
usermod -aG sudo admin

Lock down the firewall

# Install UFW
apt install ufw -y

# Default: deny everything
ufw default deny incoming
ufw default allow outgoing

# Allow only Tailscale subnet
ufw allow in on tailscale0
ufw allow in from 100.64.0.0/10

# Enable firewall
ufw enable

Disable traditional SSH

Since Tailscale SSH handles authentication, disable the regular SSH daemon:

systemctl disable --now ssh

Verify the lockdown

ufw status

You should see only Tailscale traffic allowed. Your VPS now has zero public ports.

Install Tailscale on your local machine

On your local machine (Linux/WSL):

curl -fsSL https://tailscale.com/install.sh | sh
sudo systemctl start tailscaled
sudo tailscale up

Now connect to your VPS — no public IP needed:

tailscale ssh admin@YOUR_VPS_TAILSCALE_IP

That's it. You're in via an encrypted WireGuard tunnel, and nobody on the internet can even see your server exists.

WSL Users: Fix the MTU Issue

If you're running Tailscale in WSL and SSH connections hang (connect but never complete the handshake), you've hit a known MTU bug. The Tailscale interface defaults to MTU 1280, but WSL's network stack can't handle packets that large on the WireGuard tunnel.

Symptoms:

tailscale ping works fine
tailscale ssh hangs indefinitely
Verbose SSH (ssh -vvv) stalls at expecting SSH2_MSG_KEX_ECDH_REPLY

Fix:

sudo ip link set dev tailscale0 mtu 1200

This is a temporary fix that resets on WSL restart. To make it permanent, add it to your shell profile:

echo 'sudo ip link set dev tailscale0 mtu 1200 2>/dev/null' >> ~/.bashrc

Or add a sudoers rule so it doesn't prompt for a password:

# /etc/sudoers.d/tailscale-mtu
your_username ALL=(ALL) NOPASSWD: /usr/sbin/ip link set dev tailscale0 mtu 1200

Step 2: Install OpenClaw

OpenClaw (formerly Clawdbot, then Moltbot) is an open-source personal AI assistant created by Peter Steinberger. It has 68k+ stars on GitHub and supports dozens of messaging channels, tools, cron jobs, webhooks, and more.

openclaw / openclaw

Your own personal AI assistant. Any OS. Any Platform. The lobster way. 🦞

🦞 OpenClaw — Personal AI Assistant

OpenClaw is a personal AI assistant that learns and grows with you, running on your own devices — developed in the open by the OpenClaw Foundation (a non-profit) It answers you on the channels you already use. It can speak and listen on macOS/iOS/Android, and can render a live Canvas you control. The Gateway is just the control plane — the product is the assistant.

If you want a personal, single-user assistant that feels local, fast, and always-on, this is it.

Supported channels include: WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, IRC, Microsoft Teams, Matrix, Feishu, LINE, Mattermost, Nextcloud Talk, Nostr, Synology Chat, Tlon, Twitch, Zalo, Zalo Personal, WeChat, QQ, WebChat.

Website · Docs · Vision · Third-party notices · DeepWiki · Getting Started · Updating · Showcase · FAQ · Onboarding · Nix · Docker · Discord

New install? Start here: Getting…

View on GitHub

Install Node.js 22+

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node --version  # Should be v22+

Install pnpm

curl -fsSL https://get.pnpm.io/install.sh | sh -
source ~/.bashrc
pnpm --version

Clone and build

mkdir -p ~/GIT && cd ~/GIT
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# Install dependencies
pnpm install

# Build the UI and TypeScript
pnpm ui:build
pnpm build

Run the onboard wizard

pnpm openclaw onboard \
  --non-interactive \
  --accept-risk \
  --flow quickstart \
  --mode local \
  --skip-channels \
  --skip-skills \
  --install-daemon

This creates:

~/.openclaw/openclaw.json — main configuration
~/.openclaw/workspace/ — agent workspace
A systemd user service for the gateway
Gateway listening on 127.0.0.1:18789 (loopback only — not exposed!)

Verify it's running:

pnpm openclaw gateway status

You should see:

Gateway: bind=loopback (127.0.0.1), port=18789
Runtime: running (pid XXXXX)
RPC probe: ok
Dashboard: http://127.0.0.1:18789/

Step 3: Subscribe to Kimi Code and Get an API Key

Kimi Code is a subscription-based AI coding service by Moonshot AI. It powers the K2.5 model at up to 100 tokens/s and works with third-party tools like OpenClaw, Claude Code, and Roo Code.

Go to kimi.com/code
Log in or create an account
Select a Coding Plan (starts at ~$19/month for the Andante tier)

Your quota refreshes on a 7-day rolling cycle. Unused quota does not carry over.

Generate an API key

Go to the Kimi Code Console
Navigate to API Keys
Click Create New Key
Copy the key immediately — it's only shown once!

Security note: Treat your API key like a password. Never commit it to Git or expose it in client-side code. Kimi Code allows personal use in compatible third-party agents, but requests consume your subscription quota.

Step 4: Configure OpenClaw with Kimi Code

Run the interactive config:

pnpm openclaw config

Select:

Model
Moonshot AI
Kimi Coding API key
Paste your API key from the Kimi Code Console

Or do it in one shot:

pnpm openclaw onboard --kimi-code-api-key "YOUR_API_KEY"

Restart the gateway to apply:

pnpm openclaw gateway restart

Test it

pnpm openclaw agent --message "Hello! What model are you?"

You should get a response from Kimi K2.5.

Step 5: Access the Dashboard

The dashboard runs on localhost:18789 on the VPS. Since we locked down all ports, we access it through an SSH tunnel.

From your local machine:

ssh -L 18789:localhost:18789 admin@YOUR_VPS_TAILSCALE_IP

Or with Tailscale SSH:

tailscale ssh -L 18789:localhost:18789 admin@YOUR_VPS_TAILSCALE_IP

Now open your browser:

http://localhost:18789/?token=YOUR_GATEWAY_TOKEN

You'll find the gateway token in ~/.openclaw/openclaw.json under gateway.auth.token.

The dashboard gives you a web UI to chat with your AI, manage sessions, configure channels, and more.

Step 6: Keep It Running

The onboard wizard already installed a systemd user service. Make sure it survives reboots:

# Enable lingering so user services run without login
sudo loginctl enable-linger admin

# Check status
systemctl --user status openclaw-gateway

Updating OpenClaw

cd ~/GIT/openclaw
git pull --rebase origin main
pnpm install
pnpm ui:build
pnpm build
pnpm openclaw gateway restart

Architecture Overview

Here's what the final setup looks like:

┌─────────────────────────┐        ┌──────────────────────────┐
│   Your Machine          │        │   VPS (Ubuntu 24.04)     │
│                         │        │                          │
│  Browser ──SSH tunnel──────────────→ OpenClaw Gateway :18789│
│                         │        │   └── Kimi K2.5 API      │
│  Terminal               │        │   └── Workspace           │
│   └── tailscale ssh ──────────────→ Shell access             │
│                         │        │                          │
│  Tailscale ◄──WireGuard──────────►  Tailscale               │
└─────────────────────────┘        └──────────────────────────┘
                                   Firewall: ALL public ports CLOSED
                                   Only Tailscale (100.64.0.0/10) allowed

No public IP exposure. No open ports. No password authentication. Just a WireGuard tunnel and your AI assistant waiting on the other side.

Security Checklist

[x] UFW firewall: deny all incoming except Tailscale
[x] SSH: disabled (using Tailscale SSH instead)
[x] Root login: disabled
[x] Password auth: disabled
[x] OpenClaw gateway: bound to loopback only
[x] Dashboard access: via SSH tunnel only
[x] API key: stored in server config, never exposed
[x] Auto-updates: enabled on VPS

Useful Commands

# Gateway management
pnpm openclaw gateway status
pnpm openclaw gateway restart
pnpm openclaw logs

# Health check
pnpm openclaw doctor

# Send a message
pnpm openclaw agent --message "Your message here"

# List available models
pnpm openclaw models list

# Reconfigure
pnpm openclaw config

Wrapping Up

For under $25/month (VPS + Kimi Code) you get a private AI assistant that:

Runs 24/7 on your own hardware
Is completely invisible to the internet
Supports WhatsApp, Telegram, Slack, and dozens more channels
Uses a powerful AI model (Kimi K2.5 via Kimi Code subscription)
Remembers your conversations and preferences

The hardest part was honestly debugging the WSL Tailscale MTU issue. Everything else was surprisingly smooth.

Resources:

OpenClaw GitHub
OpenClaw Docs
Tailscale
Kimi Code — subscribe and get your API key
Kimi Code Console — manage API keys and devices
Kimi Code Docs — membership benefits and usage details

Have you self-hosted an AI assistant? What's your setup? Let me know in the comments!

How to Install Moltbot with Docker and Gemini on WSL

Nunc — Wed, 28 Jan 2026 11:37:09 +0000

Ever wanted your own AI assistant that you can chat with via WhatsApp? Meet Moltbot - an open-source AI gateway that just went through a rebrand with an interesting backstory.

The Name Change Story

You might have heard of "Clawdbot" - a popular AI assistant project with a space lobster mascot. On January 27, 2026, Anthropic sent a trademark request because "Clawd" was too similar to their "Claude" trademark.

Creator Peter Steinberger (@steipete) took it in stride:

"Anthropic asked us to change our name (trademark stuff), and honestly? 'Molt' fits perfectly - it's what lobsters do to grow."

The mascot is now "Molty" and the project is "Moltbot". Sometimes forced changes lead to better names.

Why Gemini Instead of Claude?

You might wonder: "I have a Claude Code subscription, why not use that?"

Here's the problem: Anthropic actively blocks third-party tools from using Claude Code subscriptions, and doing so violates their Terms of Service.

In early January 2026, Anthropic cracked down on "harnesses" - third-party tools that use Claude Code OAuth to access consumer subscriptions. An Anthropic employee explained:

"Restrictions target third-party harnesses spoofing the official client, which violate ToS by creating unusual traffic patterns without telemetry — complicating debugging, rate limits, and support."

The risks of using Claude Code subscription with Moltbot:

Risk	Details
Account ban	Anthropic has banned users for TOS violations
Sudden disconnection	Your bot stops working without warning
Gray area legally	Operating outside official support

The error you'll see: "This credential is only authorized for use with Claude Code and cannot be used for other API requests."

The safe alternatives:

Gemini CLI (this guide) - Free tier, legitimate OAuth
Anthropic API key - Pay-as-you-go, officially supported
Google Antigravity - Access Claude via Google's infrastructure

This guide uses Gemini because it's free, has generous limits, and Google actively supports third-party integrations.

What You'll Build

By the end of this guide, you'll have:

Moltbot running in Docker on WSL
Google Gemini as your AI backend (free tier available)
Optional WhatsApp integration to chat with your bot

Prerequisites

Windows with WSL 2 (Ubuntu 22.04)
An internet connection
About 30 minutes

Step 1: Install Docker in WSL

Open your WSL terminal and run:

# Update and install dependencies
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

# Add Docker's GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add Docker repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Add yourself to docker group
sudo usermod -aG docker $USER
sudo service docker start

Important: Log out of WSL and back in for the group change to work:

exit
# Reopen WSL, then verify:
docker run hello-world

Step 2: Clone and Build Moltbot

mkdir -p ~/GIT/moltbot-project
cd ~/GIT/moltbot-project
git clone https://github.com/moltbot/moltbot.git
cd moltbot
./docker-setup.sh

During setup, use these quick settings:

Prompt	Value
Security warning	Yes
Onboarding mode	QuickStart
Model/auth provider	Skip for now
Gateway bind	lan
Gateway auth	token

Step 3: Add Gemini Support

Create a custom Dockerfile that includes Gemini CLI:

cd ~/GIT/moltbot-project

cat > Dockerfile.custom << 'EOF'
FROM moltbot:local
USER root
RUN npm install -g @google/gemini-cli
USER node
VOLUME /home/node/.gemini
EOF

docker build -t moltbot-with-gemini -f Dockerfile.custom .

Step 4: Authenticate with Gemini

Install and authenticate Gemini CLI in WSL:

npm install -g @google/gemini-cli
gemini

Follow the OAuth flow in your browser. This creates credentials in ~/.gemini/.

Step 5: Wire It All Together

Create a Docker Compose override to mount your Gemini credentials:

cat > ~/GIT/moltbot-project/moltbot/docker-compose.override.yml << 'EOF'
services:
  moltbot-gateway:
    image: moltbot-with-gemini
    environment:
      HOME: /home/node
    volumes:
      - ~/.gemini:/home/node/.gemini
      - ~/.clawdbot:/home/node/.moltbot
  moltbot-cli:
    image: moltbot-with-gemini
    environment:
      HOME: /home/node
    volumes:
      - ~/.gemini:/home/node/.gemini
      - ~/.clawdbot:/home/node/.moltbot
EOF

Enable the Gemini plugin:

cd ~/GIT/moltbot-project/moltbot

# Enable plugin
docker compose -f docker-compose.yml -f docker-compose.override.yml run -it --rm moltbot-cli plugins enable google-gemini-cli-auth

# Authenticate inside container
docker compose -f docker-compose.yml -f docker-compose.override.yml run -it --rm moltbot-cli auth login --provider google-gemini-cli

# Configure models
docker compose -f docker-compose.yml -f docker-compose.override.yml run -it --rm moltbot-cli configure

Step 6: Start and Test

# Start the gateway
docker compose -f docker-compose.yml -f docker-compose.override.yml up -d moltbot-gateway

# Test it
docker compose -f docker-compose.yml -f docker-compose.override.yml run -it --rm moltbot-cli agent --local --session-id test -m "Hello!"

You should get a response from your AI.

Bonus: Add WhatsApp

WhatsApp is surprisingly easy - it uses QR code login like WhatsApp Web.

# Configure WhatsApp channel
docker compose -f docker-compose.yml -f docker-compose.override.yml run -it --rm moltbot-cli configure

Select Channels -> WhatsApp and set:

Personal phone mode: Yes
dmPolicy: allowlist
allowFrom: Your phone number (e.g., +15551234567)

Then link your phone:

docker compose -f docker-compose.yml -f docker-compose.override.yml run -it --rm moltbot-cli channels login

Scan the QR code with WhatsApp (Settings -> Linked Devices -> Link a Device). Now you can chat with your AI via WhatsApp self-messages.

Quick Reference Commands

cd ~/GIT/moltbot-project/moltbot

# Start
docker compose -f docker-compose.yml -f docker-compose.override.yml up -d moltbot-gateway

# Stop
docker compose -f docker-compose.yml -f docker-compose.override.yml down

# View logs
docker compose -f docker-compose.yml -f docker-compose.override.yml logs -f moltbot-gateway

# Open dashboard
docker compose -f docker-compose.yml -f docker-compose.override.yml run --rm moltbot-cli dashboard

Troubleshooting

Docker permission denied?

sudo usermod -aG docker $USER
# Then log out and back in

Gemini rate limits (429)?
The free tier has limits. Wait a bit or add an API key fallback from Google AI Studio.

Config files owned by root?

sudo chown -R $USER:$USER ~/.clawdbot

Wrapping Up

Moltbot gives you a self-hosted AI gateway that can connect to various backends (Gemini, Claude via Antigravity, etc.) and channels (WhatsApp, Discord, Telegram). The Docker setup keeps everything contained and reproducible.

The rebrand from Clawdbot to Moltbot is a good reminder that sometimes external pressure leads to better outcomes - "Molt" really does fit the lobster theme better.

Have you set up Moltbot or a similar AI assistant? Share your experience in the comments!

How to Run Clawdbot on WSL with Your Claude Code Subscription

Nunc — Mon, 26 Jan 2026 13:33:45 +0000

I wanted to run Clawdbot—an AI chatbot framework—on Windows WSL, but there was a catch: I needed to use my existing Claude Code subscription instead of paying for separate API access. Here's how I got it working.

The Authentication Challenge

Clawdbot supports multiple authentication methods, but most require paid API access. If you have a Claude Code subscription, you can leverage its OAuth mechanism instead. The trick? Claude Code CLI must be inside the Docker container.

Here's why this setup is required:

Requirement	Why
Claude Code CLI in container	Clawdbot uses Claude Code's OAuth mechanism
Mount `~/.claude` credentials	Where Claude Code stores authentication
Set `HOME=/home/node`	So Claude Code finds the credentials

Other auth methods won't work with your subscription:

Anthropic API key requires paid API access
Setup-token paste has incompatible format
Claude Code CLI OAuth uses your subscription

Prerequisites

Before starting, make sure you have:

Windows with WSL 2 (Ubuntu 22.04)
Claude Code CLI installed and authenticated in WSL
Internet connection

If you haven't installed Claude Code yet:

npm install -g @anthropic-ai/claude-code && claude

Step 1: Install Docker Engine in WSL

First, set up Docker in your WSL environment:

# Update package index
sudo apt-get update

# Install required packages
sudo apt-get install -y ca-certificates curl gnupg

# Add Docker's official GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add Docker repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Add your user to docker group
sudo usermod -aG docker $USER

# Start Docker service
sudo service docker start

Log out and back into WSL for the group change to take effect, then verify:

docker --version
docker compose version
docker run hello-world

Step 2: Clone and Build Clawdbot

mkdir -p ~/GIT/clawdbot-project
cd ~/GIT/clawdbot-project
git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot
./docker-setup.sh

During the onboarding prompts, use these settings:

Prompt	Value
Security warning	Yes (continue)
Onboarding mode	QuickStart
Model/auth provider	Skip for now
Gateway bind	lan
Gateway auth	token
Skills	Skip for now
Hooks	Skip for now

Step 3: Build Custom Image with Claude Code

Here's the key part. Create a custom Dockerfile that includes Claude Code CLI:

cd ~/GIT/clawdbot-project

cat > Dockerfile.custom << 'EOF'
FROM clawdbot:local

# Install Claude Code CLI
RUN npm install -g @anthropic-ai/claude-code

# Mount point for Claude credentials
VOLUME /home/node/.claude
EOF

docker build -t clawdbot-with-claude -f Dockerfile.custom .

Step 4: Create Docker Compose Override

Create an override file to use the custom image and mount your Claude credentials:

# ~/GIT/clawdbot-project/clawdbot/docker-compose.override.yml
services:
  clawdbot-gateway:
    image: clawdbot-with-claude
    environment:
      HOME: /home/node
    volumes:
      - ~/.claude:/home/node/.claude
  clawdbot-cli:
    image: clawdbot-with-claude
    environment:
      HOME: /home/node
    volumes:
      - ~/.claude:/home/node/.claude

Save this to ~/GIT/clawdbot-project/clawdbot/docker-compose.override.yml.

Step 5: Configure Dashboard Access

Enable insecure auth for local dashboard access by editing ~/.clawdbot/clawdbot.json. Add this inside the "gateway" section:

"controlUi": {
  "allowInsecureAuth": true
}

Also change "bind": "loopback" to "bind": "lan" if you want to access it from your network.

Step 6: Start and Test

Start the gateway:

cd ~/GIT/clawdbot-project/clawdbot
docker compose -f docker-compose.yml -f docker-compose.override.yml up -d clawdbot-gateway

Test the agent:

docker compose -f docker-compose.yml -f docker-compose.override.yml run -it --rm clawdbot-cli agent --local --session-id test -m "Hello!"

You should get a response from Claude.

Accessing the Dashboard

Get your gateway token:

grep CLAWDBOT_GATEWAY_TOKEN ~/GIT/clawdbot-project/clawdbot/.env

Then open http://127.0.0.1:18789/?token=YOUR_TOKEN_HERE in your browser.

Bonus: Adding WhatsApp

WhatsApp is surprisingly easy to set up—it uses QR code login like WhatsApp Web.

cd ~/GIT/clawdbot-project/clawdbot
docker compose -f docker-compose.yml -f docker-compose.override.yml run -it --rm clawdbot-cli configure

Select Channels → WhatsApp and configure:

Personal phone mode: Yes
dmPolicy: allowlist
allowFrom: Your phone number (E.164 format like +1555123456)

Then link your phone:

docker compose -f docker-compose.yml -f docker-compose.override.yml run -it --rm clawdbot-cli channels login

Scan the QR code with WhatsApp → Settings → Linked Devices → Link a Device.

Quick Reference Commands

Click to expand common commands

# Start gateway
docker compose -f docker-compose.yml -f docker-compose.override.yml up -d clawdbot-gateway

# Stop gateway
docker compose -f docker-compose.yml -f docker-compose.override.yml down

# View logs
docker compose -f docker-compose.yml -f docker-compose.override.yml logs -f clawdbot-gateway

# Test agent
docker compose -f docker-compose.yml -f docker-compose.override.yml run -it --rm clawdbot-cli agent --local --session-id test -m "Hello"

Troubleshooting

Docker permission denied: Run sudo usermod -aG docker $USER and log out/in.

Claude credentials not working: Re-authenticate with claude /login in WSL.

Dashboard shows "pairing required": Ensure controlUi.allowInsecureAuth: true is in your config.

No response from agent: Check that HOME=/home/node is set and ~/.claude is mounted in your override file.

Wrapping Up

The key insight here is that Claude Code's OAuth tokens can be shared with containerized applications by mounting the credentials directory. This pattern works for any Docker-based tool that supports Claude Code authentication.

openclaw / openclaw

Your own personal AI assistant. Any OS. Any Platform. The lobster way. 🦞

🦞 OpenClaw — Personal AI Assistant

If you want a personal, single-user assistant that feels local, fast, and always-on, this is it.

Website · Docs · Vision · Third-party notices · DeepWiki · Getting Started · Updating · Showcase · FAQ · Onboarding · Nix · Docker · Discord

New install? Start here: Getting…

View on GitHub

Have you tried running AI assistants in Docker? What authentication challenges did you face? Share in the comments!

I Used Claude Code to Write a Legal Appeal for My Mother's Disability Benefits

Nunc — Fri, 23 Jan 2026 09:01:47 +0000

I'm a software developer. Claude Code is a CLI tool designed for coding tasks - writing code, debugging, refactoring. So naturally, I used it to write a 230-line legal appeal against a government disability decision.

Here's how a programming tool became my most powerful ally in a deeply personal, completely non-technical challenge.

The Problem

My mother has severe spinal degeneration. After 45 years of physically demanding work, multiple surgeries, and recent osteoporotic vertebral fractures, she applied for disability benefits and care allowance from the national pension and disability insurance agency.

The response? Rejected.

The expert medical commission concluded:

Her spine condition was "congenital" (born with it)
Treatment was "completed"
She could perform daily activities independently
Only 30% disability recognized (50% required for benefits)

Reading the decision, I knew it was wrong. But how do you argue against a medical commission with mountains of paperwork, complex regulations, and 25+ years of medical history?

The Chaos: 50+ Scanned Medical Documents

My mother's medical history was a nightmare to navigate:

spine-findings/           # Spine-related medical records (12 files)
additional-findings/      # Additional medical findings (8 files)
application-docs/         # Original application attachments (15 files)
new-findings-2026/        # Recent findings from January 2026 (20+ files)
commission-opinion/       # The commission's expert opinion (6 files)

All scanned as JPG images. Handwritten doctor's notes from 1998. Faded hospital discharge papers. CT scan reports. Years of medical history trapped in pixels.

Step 1: OCR with Google Gemini API

First challenge: extract text from images.

Side note: Claude Code can also read images and perform OCR directly. However, for bulk processing of 50+ scanned medical documents - many with handwritten notes and faded text from the 1990s - Google's Gemini with "thinking mode" produced significantly better results. Claude Code's OCR is decent for quick reads, but Gemini's accuracy on difficult documents was noticeably superior.

I wrote a simple Python script using Google's Gemini API:

from google import genai
from google.genai import types

def extract_text_from_image(client, image_path):
    with open(image_path, "rb") as f:
        image_data = f.read()

    contents = [
        types.Content(
            role="user",
            parts=[
                types.Part.from_bytes(
                    mime_type="image/jpeg",
                    data=image_data,
                ),
                types.Part.from_text(
                    text="Extract all text from this image. "
                         "Preserve formatting and structure. "
                         "If handwritten, transcribe to readable form."
                ),
            ],
        ),
    ]

    # Using Gemini's thinking mode for better accuracy
    config = types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="HIGH"),
    )

    result = []
    for chunk in client.models.generate_content_stream(
        model="gemini-3-pro-preview",
        contents=contents,
        config=config,
    ):
        if chunk.text:
            result.append(chunk.text)

    return "".join(result)

The script processed entire folders:

python extract_ocr.py "new-findings-2026/"
# Found 24 images without TXT:
#   - scan_001.jpg
#   - scan_002.jpg
#   ...
# Processing: scan_001.jpg... OK -> scan_001.txt

Result: Every medical document now had a searchable .txt companion file.

Step 2: Building Context with CLAUDE.md

Claude Code uses a CLAUDE.md file for project-specific context. I created one explaining the case:

# CLAUDE.md

## Repository Purpose

Document repository for a disability benefits appeal case.

## Document Structure

- **spine-findings/** - Spine medical records (JPG + OCR'd TXT)
- **commission-opinion/** - Expert commission documents
- **appeal-drafts/** - Appeal document versions

## Key Context for Appeal

Main contested points from the expert opinion:
- Health history incorrectly characterized as congenital
- Treatment incorrectly marked as concluded
- Independence incorrectly assessed
- New osteoporotic fractures not considered
- Date of injury incorrectly stated

## Working with Documents

Read .txt versions for text content.
Reference official disability regulations for legal basis.
Use formal legal/medical terminology.

Now Claude Code understood the project structure and goals.

Step 3: The Iterative Writing Process

This is where Claude Code shined. I started with rough notes:

I disagree with the expert opinion because:
- My condition isn't congenital - first problems at age 51
- Treatment ongoing - have orthopedic appointment scheduled
- Can't cook, clean, or do laundry independently
- New vertebral fractures in 2025 weren't considered

Claude Code read all the OCR'd medical files, cross-referenced dates and diagnoses, and produced the first draft. But it didn't stop there.

The secret weapon: I asked Claude Code to fetch and read the official disability regulations directly from the government website - the complete guidelines on how bodily impairments are assessed and calculated. With both the medical evidence AND the legal criteria in context, Claude Code could build arguments that directly mapped specific diagnoses to specific regulation paragraphs. For example, it found that "unstable spinal segment" and "severe spinal stenosis" each qualify as separate impairments that should be added together - something the commission had overlooked.

Version 1 → Version 11: Each iteration got better:

v1: Basic structure, main arguments
v3: Added specific medical evidence with dates
v5: Referenced disability regulations and legal basis
v9: Incorporated new January 2026 findings
v10: Added disability calculation showing 50%+ should be recognized
v11: Final polish, comprehensive evidence list

The final appeal grew from rough notes to a 230-line legal document with:

7 major sections with subsections
30+ specific medical citations with dates
Legal references to disability insurance law and internal guidelines
Calculations showing multiple vertebral segments = higher disability %
Request for home visit to verify living conditions

The Technical Magic: What Claude Code Actually Did

Claude Code isn't just generating text. It's:

Reading and cross-referencing documents:

"The MRI from November 2000 shows NO pathological changes...
If this were congenital, changes would be visible in 2000."

Understanding medical terminology:

"CT scan confirms: 'Fresh osteoporotic fracture of
L4 vertebral body involving anterior and partially middle column.'"

Applying legal frameworks:

"Per disability guidelines Chapter VIII: 'When multiple segments
are affected, add 10% for each additional segment beyond
the first 30%.' L2 + L3 + L4 = 30% + 10% + 10% = 50%"

Finding contradictions:

"The commission's own expert opinion in Section 6 states:
'unstable segment L3-L4' - yet this was NOT considered
in the disability calculation!"

The Document Pipeline

Text file → Review → Iterate → Final .docx and .pdf:

appeal-drafts/
├── appeal_v01.txt    # First draft
├── appeal_v05.txt    # Major revision
├── appeal_v09.txt    # With new evidence
├── appeal_v11.txt    # Final text
├── appeal_v11.docx   # Formatted Word doc
└── appeal_v11.pdf    # Print-ready PDF

For the final step, I used Claude Code's docx skill - a built-in capability that converts text documents into properly formatted Word files. One command, and the plain text appeal became a professional document with:

Correct headers and formal structure
Proper spacing and margins for official submissions
Automatic PDF generation

No manual formatting in Word. No copy-paste headaches. The skill handled everything, producing government-ready documents directly from the terminal.

Key Learnings

1. AI is a multiplier, not a replacement

I still needed to:

Scan and organize documents
Provide context and direction
Verify every fact and citation
Make judgment calls on arguments

Claude Code amplified my efforts - turning hours of work into minutes.

2. Structure matters

The CLAUDE.md file was crucial. Clear project context meant better outputs from the first prompt.

3. Iteration is natural

Don't expect perfection on v1. The v1→v11 journey wasn't failure - it was refinement. Each version incorporated new information, better arguments, and clearer language.

4. Domain knowledge can be learned

Neither Claude Code nor I are lawyers or medical professionals. But by reading the regulations, understanding the criteria, and carefully citing evidence, we built a comprehensive legal argument.

The Unexpected Outcome

Using a programming tool for a legal appeal sounds absurd. But Claude Code's strengths translate perfectly:

Coding Task	Legal Appeal Task
Reading codebase	Reading medical records
Understanding APIs	Understanding regulations
Debugging errors	Finding contradictions
Refactoring code	Refining arguments
Writing documentation	Writing formal appeals

What Happens Next

The appeal is submitted. We wait for the second-level commission's decision.

But regardless of outcome, this experience taught me that AI tools aren't limited to their intended domains. A CLI built for git commit and npm install became the backbone of a deeply human fight for my mother's dignity and care.

Sometimes the best tool for the job is the one you're already comfortable with.

Have you used AI tools for unexpected tasks? I'd love to hear about creative applications in the comments.

Technical note: The OCR script uses Google's Gemini with "thinking mode" for better accuracy on handwritten and faded documents (Claude Code has OCR too, but Gemini performed better on difficult scans). Claude Code handled document analysis, cross-referencing, fetching and parsing official regulations from government websites, iterative drafting, and final document conversion to DOCX/PDF via the built-in docx skill.

Claude.ai Has Built-In Superpowers (And You Probably Didn't Know)

Nunc — Mon, 27 Oct 2025 19:03:40 +0000

TL;DR: Claude.ai comes with 5 hidden "skills" that let it create Word docs, PowerPoint slides, Excel spreadsheets, and manipulate PDFs. Here's what Claude can actually do for you.

Wait, Claude Has Skills?

Yeah! If you're using Claude.ai (the web or desktop version), you might've noticed it can do some pretty fancy document work. That's because Claude has these built-in "skills" - basically specialized knowledge for working with office documents.

Most people just use Claude for chat and coding. But if you know how to ask, Claude can literally create a formatted Excel spreadsheet with formulas, build a PowerPoint deck, or edit a Word doc with tracked changes.

Let me show you what's under the hood.

The 5 Built-In Skills

1. DOCX Skill - Word Document Master

What it does:

Creates professional Word documents from scratch
Edits existing docs
Handles tracked changes (redlining)
Adds comments
Preserves formatting

Real-world uses:

You: "Create a business proposal document with sections for Executive Summary, Problem Statement, and Solution"

Claude: *generates a properly formatted .docx with headings, formatting, and structure*

Pro tip: If you need Claude to edit someone else's document (like legal or business docs), ask for "tracked changes" - Claude will mark every edit so reviewers can see what changed.

2. PPTX Skill - Presentation Builder

What it does:

Creates PowerPoint presentations
Edits existing slides
Works with layouts and templates
Adds speaker notes
Handles comments

Real-world uses:

You: "Create a 5-slide pitch deck about our new product"

Claude: *builds a presentation with title slide, problem, solution, market, and call-to-action slides*

Cool feature: Claude can even work from templates - give it your company's branded PowerPoint template, and it'll create slides matching your style.

3. XLSX Skill - Spreadsheet Wizard

What it does:

Creates Excel files with formulas (not just data!)
Formats cells (colors, fonts, number formats)
Builds financial models
Analyzes existing spreadsheets
Calculates everything properly

Real-world uses:

You: "Create a monthly budget tracker with categories for rent, food, utilities, and entertainment. Add formulas to calculate totals."

Claude: *generates an Excel file with proper formulas, formatting, and even color-coding*

Key point: Claude uses ACTUAL Excel formulas (like =SUM(A1:A10)), not hardcoded values. Your spreadsheet will recalculate if you change inputs.

Finance nerds: Claude follows financial modeling standards:

Blue text = inputs
Black text = formulas
Green text = links from other sheets
Red text = external links
Yellow background = key assumptions

4. PDF Skill - PDF Surgeon

What it does:

Extracts text and tables from PDFs
Merges multiple PDFs
Splits PDFs into separate pages
Creates new PDFs
Fills PDF forms

Real-world uses:

You: "Extract all the tables from this financial report PDF"

Claude: *pulls out tables as structured data you can work with*

Handy trick: Need to combine 5 different PDFs into one? Or split a 50-page PDF into individual files? Claude's got you.

5. Product Self-Knowledge Skill

What it does:

Answers questions about Claude products (API, Claude.ai, Claude Code)
Provides accurate documentation links
Distinguishes between different Claude products
Prevents hallucinations about capabilities

Real-world uses:

You: "Can Claude.ai access the internet?"

Claude: *gives accurate answer with source documentation link*

Why this matters: This skill helps Claude give you accurate info about what it can and can't do, rather than making stuff up.

How To Use These Skills

Here's the thing - you don't need to do anything special. Just ask Claude naturally:

Examples that work:

"Create a Word document with..."
"Build me an Excel budget tracker..."
"Make a PowerPoint about..."
"Extract text from this PDF..."
"Merge these 3 PDFs together..."

Claude will automatically activate the right skill for the job.

What Claude Actually Does Behind The Scenes

When you ask for a Word doc, Claude:

Uses a library called docx-js to build the document structure
Adds your content with proper formatting
Exports as a real .docx file
Gives you a download

For Excel, Claude:

Uses openpyxl (Python library)
Writes actual Excel formulas (not calculated values)
Applies formatting and colors
Recalculates everything to make sure formulas work

Pretty neat, right?

Real Examples I've Seen People Use

Business use:

"Create a project status report with RAG status indicators"
"Build a quarterly budget spreadsheet with formulas"
"Make a 10-slide training deck about security policies"

Personal use:

"Create a budget tracker for my expenses"
"Build a presentation about my vacation photos"
"Extract text from these scanned receipts"

Academic use:

"Create a formatted research paper template"
"Build a data analysis spreadsheet with charts"
"Merge all my assignment PDFs into one document"

Limitations To Know

What Claude CAN'T do:

Open existing files you haven't uploaded
Edit files on your computer directly
Access your Google Drive or OneDrive
Send files to other services
Create files larger than a few MB

What Claude CAN do:

Work with files you upload in the chat
Create new files from scratch
Process and analyze documents
Generate properly formatted office documents

Pro Tips

Tip 1: Be Specific About Formatting

Instead of: "Create a spreadsheet"

Try: "Create an Excel spreadsheet with blue headers, bold column names, and formulas to calculate totals"

Tip 2: Ask For Examples First

You: "Show me what the Excel file will look like before creating it"

Claude: *describes structure, then creates it*

Tip 3: Iterate

Don't expect perfection on first try. You can say:

"Add a new column for..."
"Change the formatting to..."
"Add speaker notes to each slide..."

Tip 4: Upload Templates

Have a company template? Upload it and say:
"Use this template and create a presentation about [topic]"

How This Compares To Other Tools

vs Microsoft Copilot:

Claude: Better at understanding complex requests
Copilot: Better at integrating with your existing Office files

vs ChatGPT:

Claude: Built-in office document skills
ChatGPT: Requires plugins or third-party tools

vs Google Docs AI:

Claude: Creates downloadable files
Google Docs: Works directly in your docs

Why This Matters

This isn't just "cool AI tricks" - it's genuinely useful:

Scenario 1: Quick Mockups
Need a financial model for a pitch tomorrow? Claude can build the skeleton in minutes.

Scenario 2: Document Processing
Got 50 PDFs to extract data from? Claude can automate it.

Scenario 3: Template Creation
Need a standard report format? Create it once with Claude, then reuse.

Try It Now

Pick one and paste it into Claude.ai:

Create a personal budget Excel spreadsheet with:
- Monthly income section
- Expense categories (rent, food, transport, entertainment)
- Formulas to calculate totals and remaining balance
- Color coding (expenses in red, income in green)

Or:

Create a 3-slide PowerPoint about time management with:
- Slide 1: Title "Productivity Tips"
- Slide 2: 5 bullet points with tips
- Slide 3: Call to action
- Add speaker notes to each slide

The Bottom Line

Claude.ai is more than a chatbot - it's a document creation powerhouse. These 5 built-in skills mean you can go from "I need a spreadsheet" to having an actual, working Excel file in minutes.

No plugins. No third-party tools. No copy-paste. Just ask.

Next time you're about to spend 30 minutes formatting a Word doc or building a spreadsheet, try asking Claude first. You might be surprised.

Have you used Claude to create documents? What worked well? What didn't? Drop your experiences in the comments! 💬

P.S. - These skills are built into Claude.ai and Claude for Desktop. If you're using the API, you'd need to implement document handling yourself.

Claude Code Skills vs Subagents - When to Use What?

Nunc — Mon, 27 Oct 2025 19:03:26 +0000

TL;DR: Skills are like recipes, subagents are like specialized coworkers. Both extend Claude Code, but knowing when to use which saves you a ton of headache.

So I was building a document reader for Claude Code (to process Word docs, PDFs, Excel files from support tickets), and I hit this question: "Should this be a skill or a subagent?"

Turns out, this is a pretty common confusion. Let me save you the research time.

The Quick Version

Here's the cheat sheet:

Aspect	Skills	Subagents
What it is	Instructions that extend Claude's knowledge	A separate AI assistant with its own context
When Claude uses it	Automatically when relevant	Delegated for complex workflows
Best for	Utility functions, recipes, how-tos	Multi-step analysis, code review, research
Context	Shares your main chat context	Gets its own isolated context window

Think of it this way:

Skill = giving Claude a cookbook
Subagent = hiring a sous chef

Skills: The Recipe Approach

Skills are markdown files with instructions. Claude reads them when it needs help with something specific.

Example structure:

~/.claude/skills/document-reader/
├── SKILL.md          (main instructions)
├── examples.md       (usage examples)
└── scripts/
    └── converter.py  (optional helper script)

When to use skills:

Converting files (PDF → text, DOCX → text)
Template generation
Style guides for code/writing
Domain knowledge (business rules, API docs)
Quick utility functions

Why skills are great:

⚡ Fast - Claude just reads instructions
🔄 Reusable - any conversation can use them
🪶 Lightweight - no separate AI needed
🤖 Auto-activated - Claude decides when to use them

Example skill description:

---
name: document-reader
description: Converts document files (.pdf, .docx, .xlsx) to text. Use when reading document attachments, analyzing files from tickets, or extracting content from PDFs and spreadsheets.
---

Notice: it tells Claude what it does and when to use it. That's key.

Subagents: The Specialized Coworker

Subagents are like delegating work to a specialist. They get their own context window and run independently.

When to use subagents:

Code review workflows
Multi-file analysis
Research tasks that need deep investigation
Tasks that would clutter your main conversation
When you need focused, dedicated reasoning

Why subagents rock:

🧠 Deep focus - dedicated context for complex tasks
🔍 Multi-step reasoning - can work through problems systematically
🎯 Specialized - custom prompts for specific workflows
🧹 Clean separation - doesn't pollute main chat

Example subagent:

---
name: code-reviewer
description: Reviews code for best practices and security issues. Use when reviewing PRs or analyzing code quality.
tools: Read, Grep, Glob
---

You are a specialized code reviewer...
[detailed instructions for review process]

Real Example: Document Reader

Here's how I decided for my document reader:

The task: Read PDF/DOCX/XLSX files from support tickets

My thought process:

Is this complex multi-step reasoning? No - just file conversion
Does it need its own context? No - simple input/output
Is it a utility function? Yes - convert file to text
Will other agents need this? Yes - zahtevki-researcher needs it

Decision: Make it a skill ✅

If I needed to analyze documents across multiple tickets, compare them, and generate reports? That would be a subagent.

How They Work Together

Here's the cool part - they complement each other:

zahtevki-researcher (subagent)
  ↓
Downloads ticket attachment.docx
  ↓
Invokes document-reader (skill)
  ↓
Converts to text
  ↓
Analyzes content
  ↓
Returns findings

The subagent handles the complex workflow, the skill handles the utility function.

Decision Tree

Use this when you're stuck:

Is it a utility/conversion/template? → Skill

Does it need multiple steps of reasoning? → Subagent

Will it be reused across different tasks? → Skill

Is it a complex workflow with validation loops? → Subagent

Is it knowledge Claude doesn't have? → Skill

Does it need to coordinate multiple operations? → Subagent

Quick Tips

For Skills:

Keep SKILL.md under 500 lines
Use progressive disclosure (main file → reference files)
Write descriptions in third person
Include trigger words (when to use it)
Make them discoverable

For Subagents:

Write detailed system prompts
Define clear responsibilities (single focus)
Limit tool access to what's needed
Test that they activate correctly

What I Learned

After building both, here's my take:

Start with a skill unless you specifically need subagent features. Skills are simpler, faster, and easier to maintain.

Upgrade to subagent when you're doing actual workflows - things with multiple steps, decision points, validation loops.

My document reader? Perfect as a skill. It's fast, reusable, and other agents can invoke it seamlessly.

Try It Yourself

Want to build your own? Here's a 5-minute starter:

# Create a skill directory
mkdir -p ~/.claude/skills/my-skill

# Create SKILL.md
cat > ~/.claude/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: What it does and when to use it
---

# My Skill

Instructions go here...
EOF

Next time you chat with Claude, it'll automatically discover and use your skill!

What are you building with Claude Code? Skills or subagents? Share in the comments - I'd love to hear what you're working on! 🚀

P.S. - If you found this helpful, I'm documenting my whole journey building skills for an insurance system. Follow along if you're into that sort of thing!

How I Built Agent Skills for Claude Code

Nunc — Tue, 21 Oct 2025 12:05:19 +0000

How I stopped re-explaining my legacy database every single conversation

So I was working with this gnarly Oracle database - 1,048 packages, 20,913 stored procedures, Slovenian terminology, old-school SQL syntax from the 90s. You know the type.

Every time I asked Claude for help, I'd spend the first 10 minutes explaining:

"No, use WHERE joins, not ANSI JOIN"
"That's Slovenian for 'claim file'"
"We always validate extraction quality"

It got old. Fast.

Then I discovered Agent Skills. Now Claude just... knows. It's like I taught it once, and it remembers forever.

Let me show you how I did it, because honestly, it's easier than you think.

What Even Are Agent Skills?

Think of them as plugins for Claude. Little knowledge modules that Claude loads automatically when it needs them.

You write a markdown file saying "Here's how to work with my database" or "Here's how our API works" - and Claude references it whenever relevant. No more repetitive explanations.

The magic part: You don't manually activate skills. Claude reads the descriptions and figures out which ones to use. It's actually pretty smart about it.

The Absolute Minimum You Need

One file. That's it.

~/.claude/skills/my-thing/
└── SKILL.md

Here's a complete working skill:

---
name: pdf-tools
description: Extract text from PDFs using pdfplumber. Use when working with PDF files.
---

# PDF Tools

import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
    print(text)

Done. You now have a skill. Seriously.

The One Rule That Matters

Keep it short.

Claude's context window is shared between your conversation, the code, other skills, and everything else. Don't waste tokens.

Here's what I mean:

❌ This wastes everyone's time

## Extract PDF text

PDF stands for Portable Document Format. It's a file format developed by Adobe in 1992 for presenting documents. PDFs can contain text, images, forms, and more. To extract text from a PDF, you'll need to use a specialized library. There are many options available in Python, such as PyPDF2, pdfplumber, and PyMuPDF. We recommend pdfplumber because it's actively maintained and handles most edge cases well. First, you'll need to install it using pip...

✅ This is what Claude actually needs

## Extract PDF text

import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

Claude already knows what PDFs are. Show the code, move on.

Target: Keep your main SKILL.md file under 500 lines. If you need more, split it into reference files (I'll show you how in a sec).

Writing Descriptions That Actually Work

The description in your YAML frontmatter is critical. It's how Claude decides whether to load your skill.

The formula that works:

What it does + When to use it + Trigger words

Examples that work

description: Extract text from PDFs using pdfplumber. Use when working with PDF files, forms, or document extraction.

description: Connect to Oracle database, extract PL/SQL packages with old-style SQL syntax. Use for Oracle database operations or PL/SQL code extraction.

description: Analyze Excel spreadsheets, create pivot tables. Use when working with .xlsx files or tabular data.

What doesn't work

description: Helps with files
description: Does database stuff
description: Utility functions

Too vague. Claude won't know when to use it.

Pro tip: Always write in third person ("Extracts text from PDFs" not "I can extract text"). Claude's system prompt uses third person, so first/second person confuses things.

The Secret: Progressive Disclosure

This is the pattern that lets your skills scale without bloating the context window.

The idea: Your SKILL.md is like a table of contents. Point to details, don't include everything upfront.

Here's how it works:

Claude loads all skill descriptions at startup (just names + descriptions)
When triggered, Claude loads your SKILL.md
As needed, Claude reads specific reference files

Example structure

# API Client

## Quick Start
[Basic code example here]

## Advanced

Need authentication? See [AUTH.md](AUTH.md)
Rate limiting? See [LIMITS.md](LIMITS.md)
Error handling? See [ERRORS.md](ERRORS.md)

Claude only reads AUTH.md when someone asks about authentication. Saves tons of context.

Keep it one level deep though

❌ Don't do this:

SKILL.md → advanced.md → details.md → actual_info.md

✅ Do this:

SKILL.md → auth.md, limits.md, errors.md, examples.md

Claude sometimes only partially reads nested files, so keep references direct from SKILL.md.

Table of Contents for long files

If a reference file gets over 100 lines, add a ToC at the top:

# API Reference

## Contents
- [Authentication](#authentication)
- [Endpoints](#endpoints)
- [Error Codes](#error-codes)

---

## Authentication
[...]

This helps Claude navigate even when it only partially reads the file.

Real Example: My Oracle Nightmare (Now Solved)

Let me show you the actual skill I built. It started as a mess and ended up at 100% compliance with Anthropic's best practices.

The Problem

I work with this insurance application database:

1,048 PL/SQL packages
20,913 procedures (yes, really)
All the business terms in Slovenian
SQL syntax from 1995 (WHERE clause joins only, no ANSI)

I'd have the same conversation every day:

"Use WHERE joins, not INNER JOIN"
"That column is 'skondi_spis' which means claim file"
"Check the line count after extraction to validate"

The Solution: Two Skills, Not One

I almost made one giant skill with everything. Thank god I didn't.

Instead:

db-toolkit - How to connect, extract, query (technical stuff)
business-domain - What the tables mean, business processes (domain knowledge)

Why separate? They change at different rates. Database operations don't change much. Business knowledge updates constantly. Sometimes I only need one.

Here's the db-toolkit structure

~/.claude/skills/db-toolkit/
├── SKILL.md (687 lines - yeah, over 500, but it's worth it)
├── reference.md (API docs for all methods)
├── usage-examples.md (10+ real scenarios)
├── sql-syntax-guide.md (old-style SQL examples)
├── troubleshooting.md (common errors)
└── scripts/
    └── oracle_toolkit_standalone.py (the actual code)

What made it actually work

1. Everything's embedded

No external dependencies. The Python code lives in scripts/ inside the skill:

from pathlib import Path

skill_dir = Path.home() / '.claude' / 'skills' / 'db-toolkit'
sys.path.insert(0, str(skill_dir / 'scripts'))

from oracle_toolkit_standalone import OracleToolkit

Skill works anywhere.

2. Copy-paste checklists

Best thing I added. For complex workflows, give Claude a checklist to track:

Copy this checklist:

Task Progress:
- [ ] Connect to database
- [ ] Extract package body
- [ ] Validate extraction (check line count)
- [ ] Copy to working directory
- [ ] Make changes
- [ ] Run tests

Claude checks items off as it works. I can see progress. Users love this.

3. Validate everything immediately

Every operation gets validated right away with specific help:

pkg = await toolkit.extract_source('MY_SCHEMA', 'PKG_EXAMPLE', 'PACKAGE BODY')

if not pkg['success']:
    print("❌ Failed:", pkg['message'])
    print("🔄 Try these fixes:")
    print("  • Check package name spelling")
    print("  • Use 'PACKAGE BODY' not 'PACKAGE'")
    print("  • Verify schema owner is correct")
    return

# Also validate quality
if pkg['line_count'] < 10:
    print("⚠️  Suspiciously small extraction - double check")

No more mystery errors later.

4. Skills reference each other

db-toolkit mentions business-domain for business context.
business-domain mentions db-toolkit for database operations.

Claude figures out when it needs both.

Results

After refining over a few weeks:

✅ 100% compliance with Anthropic best practices
✅ 85.7% test pass rate (12 out of 14 tests)
✅ Saves me probably 10 hours a week
✅ Works reliably across sessions

Note: My SKILL.md is 687 lines, which is over the recommended 500. But it's validated workflows with checklists that users copy directly. Worth the trade-off.

Patterns I Use All The Time

1. The Template Pattern

When you need exact output format, put this in your SKILL.md:

Example SKILL.md content:

## Report Format

ALWAYS use this structure:
# [Title]
## Summary
[One paragraph]

## Findings
- Finding 1
- Finding 2

For flexible stuff, say "adapt as needed" instead of "ALWAYS."

2. Show Examples, Not Descriptions

Example SKILL.md content:

## Commit Messages

**Example**:
Input: "Added user auth with JWT"
Output:
feat(auth): implement JWT authentication

Add login endpoint and token validation

One example beats ten paragraphs.

3. Guide Through Decisions

Example SKILL.md content:

## What to do

Determine your situation:

**Creating new document?** → Use Creation Workflow below
**Editing existing?** → Use Editing Workflow below

### Creation Workflow
[steps...]

### Editing Workflow
[steps...]

How I Actually Built It (Not How You'd Think)

I didn't sit down and write a massive spec. Here's what actually worked:

1. Started with the pain points

Used Claude for a week without a skill. Noted every time I had to repeat myself:

Explained old-style SQL 5 times → added syntax guide
Kept saying "validate extraction" → added validation loops
Explained Slovenian terms constantly → added glossary

Built the skill from actual problems, not imagined ones.

2. Wrote tests first

Created 3 simple test scenarios:

Test 1: "Extract package PKG_EXAMPLE" → should connect and extract
Test 2: "Show me tables for this module" → should list relevant tables
Test 3: "Fix this SQL join" → should suggest old-style syntax

Then wrote just enough skill content to pass those tests.

3. Observed what Claude actually read

Watched which files Claude opened:

Went to sql-syntax-guide.md often → made it clearer
Rarely opened troubleshooting.md → moved common stuff to SKILL.md
Skipped parts of examples.md → added ToC for faster navigation

Adjusted based on behavior.

4. The "3 times rule"

If I explained something 3 times in conversations → it went in the skill.

Example: Kept saying "use (+) for outer joins" → added to SQL guide with examples.

What NOT to Do (I learned the hard way)

❌ Time-sensitive info

Don't write:

Before August 2025, use old API.
After August 2025, use new API.

Skills should be evergreen.

❌ Windows paths

# Bad
scripts\helper.py

# Good
scripts/helper.py

Always forward slashes.

❌ Offering too many options

# Bad
You could use library A, B, C, D, E, F, or G...

# Good
Use pdfplumber for most cases.
Edge cases? See [alternatives.md](alternatives.md)

❌ Mega-skills

Don't make one skill for everything:

database-and-api-and-deployment-and-monitoring/

Make focused skills:

database-toolkit/
api-client/
deployment/
monitoring/

Quick Start: Build Your First Skill Right Now

Pick something you explain to Claude repeatedly. For me it was database stuff. For you maybe it's:

How your API works
Your company's coding standards
Common git workflows
Specific library you use a lot

5-minute version

mkdir -p ~/.claude/skills/my-thing
cd ~/.claude/skills/my-thing
nano SKILL.md

Write this:

---
name: my-thing
description: [What it does]. Use when [trigger words].
---

# My Thing

## Quick Start

[One code example]

## Common Tasks

[2-3 more examples]

Save it. Ask Claude a question that should trigger it.

That's it. You have a working skill.

The Checklist (So You Know You're Done)

Before you call a skill "done":

Structure

[ ] SKILL.md under 500 lines (or you have a good reason)
[ ] Valid YAML with name and description
[ ] If you have reference files, they link from SKILL.md (not nested deeper)

Description

[ ] Third person ("Processes files" not "I process")
[ ] Says what it does
[ ] Says when to use it
[ ] Under 1024 characters

Content

[ ] Assumes Claude is smart (no explanations of basic concepts)
[ ] Consistent terms throughout
[ ] No dates or version numbers that'll expire
[ ] Forward slashes in paths

Testing

[ ] Tried it with real questions
[ ] Claude activates it when it should
[ ] Claude finds the right info
[ ] At least 80% success rate

What I Learned

Building the db-toolkit skill changed how I work with Claude. Instead of fighting with it every conversation, it just knows my database quirks.

The skill saves me probably 10 hours a week. No more:

Re-explaining SQL syntax
Translating Slovenian terms
Reminding it to validate extractions
Describing table relationships

It just works.

Best part? Skills improve with use. Each conversation shows you what's missing. Each addition makes the next session better.

I started with a 100-line SKILL.md. Over 3 months of actual use, it grew to 3,100 lines across multiple files - but only because I found real gaps worth filling.

Your Turn

Start small. Don't try to document everything. Pick one thing you repeat constantly and build a skill for that.

Maybe it's:

Your database schema
API endpoints you use
Git workflow your team follows
Library you use every project
Testing patterns
Deployment process

Whatever it is, write a minimal SKILL.md. Use it for a week. See what's missing. Add that.

In a month you'll wonder how you ever worked without it.

Questions? Built a skill and want to share? Drop a comment - I'm genuinely curious what you build.