DEV Community: John Attebury

Skillpress, open source plumbing for Agent guidance

John Attebury — Thu, 02 Jul 2026 15:38:30 +0000

I open sourced Skillpress

It came out of a very practical irritation.

I’m working on a cluster of CLI tools that consume each other. Runlane needs Remogram. Skillpress needs to understand how those tools publish agent guidance. The whole thing only works if the agents operating inside the codebase are reading the right instructions.

At the same time, I’m developing in both Codex and Cursor. Each surface has its own place for guidance, its own format assumptions, and its own way of going stale.

That sounds like a small problem until you’re debugging behavior that came from an old skill file in one agent root while another agent is following the newer rule somewhere else.

That’s the kind of bug that doesn’t look like a bug at first. It looks like judgment drift.
Skillpress is my answer to that.

Canonical skill source lives in the repo.

Installed provider roots are caches. sync puts the right guidance where each agent can actually load it. status and doctor tell you when things have drifted. The manifest records what was installed, from where, and at what hash.

It supports Agent Skills directories, Codex skill roots, Claude Code skill roots, agent-local roots, and Cursor project rules.

This isn’t orchestration. It isn’t proof. It isn’t trying to become the center of the toolchain.

It’s plumbing for agent guidance.

But if the tools are going to consume each other, and the agents are going to help operate those tools, then the guidance layer has to be boring, explicit, and current.

That’s what Skillpress is for.

Repo: https://github.com/attebury/skillpress

Remogram Beta 0.1.9

John Attebury — Mon, 22 Jun 2026 04:55:55 +0000

Remogram Beta 0.1.9 has been released and improves agent ergonomics on real forge workflows:

opt-in merge_policy when checks are missing or still pending
cursor pagination on cr inventory and forge changes
issue open on Gitea
idempotency keys on cr_open / status_set
doctor now spells out write readiness per command and can run --live reachability probes
merge plan also surfaces clearer check context when something blocks merge

Still beta. Still read/plan by default. Writes stay behind write_commands.

Remogram 0.1.0-beta.5: forge facts agents can actually use

John Attebury — Tue, 16 Jun 2026 00:44:50 +0000

Give agents the same small set of trustworthy forge facts on every host, so they spend tokens on the work instead of recovering from wrong assumptions.

Agents working on real repos hit the same wall over and over. Forge CLIs dump huge JSON. Web UI text isn't machine-safe. “Just run gh” breaks as soon as you switch to Gitea or GitLab. Humans feel this as wrong summaries and missed blockers. Agents feel it as conflicting instructions and invented merge readiness.

Remogram 0.1.0-beta.5 is built around a simple job: give an agent the same small set of trustworthy facts, every time, on any supported forge, so it can decide what to do next without improvising from prose.

Remogram was developed by and for Topogram. You don't need Topogram to use it. Install: github.com/attebury/remogram.

npm install -g @remogram/cli@beta @remogram/mcp@beta

The problem we were solving

An agent reviewing or implementing a change usually needs answers like:

Who am I on this forge, and can this token write?
What branch rules apply?
What files did this PR actually touch?
What did reviewers say, as data rather than HTML?
What changed on the forge since we last looked?
Are checks real, missing, or failed? Is merge planning blocked for reasons git cleanliness hides?
If I need to post a status or open a PR, can I do it through the same packet model I use to read?

Before beta.5, Remogram helped with PR state and checks. After beta.5, those questions have first-class commands with the same envelope on Gitea, GitHub, and GitLab, in both CLI and MCP.

What got easier for agents (and the humans behind them)

Less guessing about identity and permissions

whoami answers “who is this token?” and “does the forge think I can write?” in one packet. Agents stop inferring auth from error messages mid-task.

branch protection answers “what contexts or rules matter for this branch?” without scraping settings pages.

Benefit: fewer dead-end tool chains and fewer “try merge and see what happens” loops.

Review with evidence, not vibes

cr files returns changed paths from the forge (bounded, truncated honestly), so an agent knows what the PR touches, not what a local branch happens to contain.

cr comments returns review threads as structured records. Titles and bodies stay semantically untrusted; envelope fields and enums are what you gate on.

Benefit: review classifications bind to what changed and what was said, not to a PR title paraphrase.

Memory of the forge since last tick

forge changes --since … gives a time-bounded slice of lifecycle events: opens, closes, merges, head moves, check conclusions observed.

Benefit: observer-style routing and “what happened while I was implementing?” stop depending on chat history or manual git fetch storytelling.

Merge readiness agents can fail closed on

merge plan already exposed blockers beyond mergeability: clean. Beta.5 ties it to cr files: pass --allowed-path globs and get path_scope_violation or changed_paths_unavailable as normalized blockers, not a skill author's memory of repo layout.

Benefit: autonomous review/merge can stop on scope the same way it stops on failed checks, with a field in JSON instead of an essay.

Writes that behave like reads

Agents shouldn't special-case “read commands” vs “suddenly use curl.”

cr open (Gitea, opt-in) opens or reuses a change request; reused_existing when the forge already has one.
status set (all three API providers, opt-in) posts commit statuses with the same idempotency discipline: scan limits, idempotency_scan_incomplete when proof is impossible, reused_existing when nothing new is needed.

Both require explicit write_commands in .remogram.json. Otherwise you get write_not_configured: use forge/CI on your system. pr checks still tells you what landed.

Benefit: agents get a single contract for “I tried to act on the forge” instead of one packet world for reads and a separate undocumented shell world for writes.

Safety that respects how agents copy output

GitHub ghs_ tokens get redacted in normalization paths so forge blobs don't become accidental secrets in logs or the next prompt.

Benefit: less risk that an agent treats tool output as safe to repeat.

One surface, not a scavenger hunt

Beta.5 completes a coherent agent toolkit:

When the agent needs…	It can ask Remogram…
Config / health	`doctor`, `provider capabilities`, `repo status`
Inventory	`refs inventory`, `cr inventory`
This PR	`pr view`, `pr checks`, `cr files`, `cr comments`
Can we merge?	`merge plan` (+ optional path allowlist)
What changed lately?	`forge changes --since …`
Who am I / what rules apply?	`whoami`, `branch protection`
Post status / open CR (if opted in)	`status set`, `cr open`

17 MCP tools, same JSON as CLI. No workflow keys in packets. Agents orchestrate elsewhere; Remogram stays forge-shaped.

Merge execute is still not Remogram's job. That boundary is intentional: agents plan and prove; humans or forge policy merge.

When you want Remogram to post, opt in once in .remogram.json:

"write_commands": ["cr_open", "status_set"]

Skills: npx skills add attebury/remogram --skill remogram-consumer -g -a cursor,codex -y

MCP: see examples/mcp/ in the Remogram repo.

In one line

Beta.5 treats agents as users who need predictable forge facts and explicit gates, so they spend tokens on the work instead of recovering from wrong assumptions about what Remogram can see, say, or do.

Introducing beta Remogram: forge facts for agents, without the workflow baggage

John Attebury — Mon, 15 Jun 2026 02:15:32 +0000

If you've ever pointed an AI coding agent at a pull request and watched it confidently merge based on a stale title, a truncated API response, or prose that looked like instructions, you've hit a boundary problem. Git hosts know a lot. Agents need small, typed, trustworthy facts, not raw forge dumps and not your team's SDLC vocabulary mixed into SCM output.

Remogram is a generic SCM/forge boundary: a CLI and MCP server that turns GitHub, GitLab, and Gitea into provider-attributed JSON packets agents can reason about safely.

Remogram was developed by and for Topogram, but you don't need Topogram to use it. It stands on its own as open-source tooling for any repo that wants better agent–forge hygiene.

The problem

Modern agent workflows need answers to boring but critical questions:

Is this PR mergeable, or only technically mergeable?
What do CI checks actually say?
Does the forge's head_sha still match what git has locally?
How far is my branch behind integration?

You can answer these with gh, glab, tea, or REST calls, but each path has tradeoffs:

CLI output varies by tool version and is hard to cap reliably.
Raw API responses are huge and easy to over-ingest into an agent context window.
Forge strings are untrusted. PR titles, check descriptions, and error bodies can contain adversarial prose.
Workflow tools leak semantics. Goal branches, lanes, and task IDs belong in planning layers, not in SCM facts.

Agents need a thin, opinionated layer that says: here are the forge facts, here's what you can trust in the envelope, here's what you must treat as untrusted prose.

That layer is Remogram.

What Remogram does

Remogram reads your repo's .remogram.json and speaks to your forge over HTTP APIs. You don't need to install official forge CLIs.

Core read/plan commands include:

remogram doctor --json
remogram repo status --json
remogram pr view --number 42 --json
remogram pr checks --number 42 --json
remogram merge plan --number 42 --json
remogram refs compare --base main --head feature/x --json

The same packets are available through MCP tools, so Cursor, Codex, and other MCP clients get identical JSON whether they call the CLI or the server.

Every packet shares a trusted envelope: type, schema_version, provider_id, remote_name, repo_id, observed_at, and ok. That consistency matters. An agent (or orchestrator) can gate on structure instead of parsing ad hoc CLI text.

Designed for agent trust, not just convenience

Remogram makes a few deliberate choices:

Bounded ingest. Forge responses are capped (default 8192 bytes) and fields are selected explicitly, not dumped wholesale into agent context.

Sanitized strings. Error messages and forge-sourced text go through structural sanitization; secrets like ghp_, gho_, and ghs_ tokens are redacted before they reach packets.

Stale head detection. When you ask about a PR by number, Remogram compares the forge-reported head_sha to what git resolves locally. If they diverge, you get ok: false with stale_head. That's a signal to git fetch, not to merge.

No workflow metadata in output. Remogram emits SCM/forge facts only. Goal branches, lanes, SDLC tasks, and proof semantics stay in external planning tools that consume Remogram, not inside Remogram itself.

Multi-forge from one shape. github-api, gitlab-api, and gitea-api providers normalize into the same packet types, so tooling built on Remogram isn't locked to a single host.

Why it's useful

For agent authors and skill maintainers

You get a stable contract instead of re-implementing forge adapters in every skill. Install the consumer skill, configure .remogram.json, run remogram doctor, and teach agents to read packets, not web UI prose.

For teams on self-hosted forges

Gitea and self-managed GitLab are first-class. Remogram was dogfooded on a private Gitea integration branch before export to public GitHub main. If your forge isn't GitHub.com, you still get the same typed facts.

For review and merge guardrails

merge plan exposes blockers, not just mergeability. "Clean merge" and "safe to merge" are different things; Remogram is explicit about which checks are pending, missing, or failed. That's the difference between an agent that can merge and one that should wait.

For CI and headless environments

API providers need a token env var (GITHUB_TOKEN, GITLAB_TOKEN, GITEA_TOKEN), not an interactive CLI login. That fits servers, sandboxes, and lane worktrees cleanly.

Beta today, intentional scope

Remogram is in 0.1.0-beta: read/plan commands are mature; writes (starting with Gitea cr open) are opt-in via write_commands in config. Merge execute remains out of scope. Remogram informs decisions; humans and separate merge lanes still own the button.

Install:

npm install -g @remogram/cli@beta @remogram/mcp@beta

Copy .remogram.json.example, run remogram doctor --json, and try remogram pr view on an open change request. For a safe sandbox, use the remogram-smoke fixture repos mirrored on GitHub, GitLab, and Gitea.

The idea in one sentence

Remogram is the forge boundary layer agents should talk to: small packets, explicit trust, multi-forge parity, so your planning workflow, review policy, and merge authority can sit above SCM facts instead of leaking into them.

When Software Work Gets Shopified

John Attebury — Fri, 29 May 2026 00:30:12 +0000

AI may not be a break from software history. It may be the next step in a long pattern: software compressing roles.

We used to pay separate people to design websites, code them, publish content, run hosting, and manage commerce. Blogs, CMS tools, Shopify, and hosted platforms absorbed much of that work.

The work didn’t disappear. It moved into platforms.

AI may do something similar to software development. Smaller teams may cover more surface area, but they’ll need stronger structure around intent, boundaries, ownership, and proof.

That’s where tools like Topogram may matter: not as another agent harness, but as a durable app map for compressed teams.

Full article

AX: A Design Discipline for the AI Agent Era

John Attebury — Sun, 15 Mar 2026 23:42:10 +0000

If you've built an MCP server, exposed tools for an AI agent, or crafted tool descriptions so the AI would call the right endpoint, you've been practicing Agent Experience — AX, a term Mathias Biilmann coined in early 2025. The current AX conversation tells you it matters. But knowing it matters and knowing how to evaluate it are different things. UX became a discipline when practitioners connected it to User-Centered Design and gave it testable principles and evaluation methods. AX needs the same grounding.

UX, DX, CX... AX

Every era of software recognizes that a particular consumer deserves intentional design. UX (end users), DX (developers), CX (customers) — each started informally, then someone named the discipline, principles emerged, and quality went up. AX — Agent Experience — follows the same arc. The new consumer is an AI agent: an LLM that reads your tool definitions, decides which to call, and orchestrates workflows. Biilmann and Netlify named it and showed why it matters. What's missing is a methodological foundation: a way to reason about why designs work and how to evaluate quality. This post grounds AX in the design traditions it inherits.

User-Centered Design

Every experience discipline rests on the same foundation: you're designing for a consumer you're not. That's User-Centered Design — refined over forty years. UX, DX, and CX are specializations of it. AX is the next one. It doesn't require a new methodology; it applies UCD to a new consumer: the agent.

In UX, you're not the user. You do research, test, iterate. In AX, you're not the agent. You can't assume the AI will "figure it out" because you know what you meant. The AI has no prior relationship with your system. It sees tool names, descriptions, and parameter schemas — and from that alone must decide what to call, when, and with what inputs. That's the entire interface. A developer has docs, tutorials, and time to learn. An AI agent has your tool signature and a few seconds of inference. The bar for clarity and self-description is dramatically higher.

Whether you use MCP, OpenAI function calling, or a custom framework, you're building an AX surface. Your tool definitions are the AI's entire interface to your system.

Four Design Pressures That Shift

AX is to API design what UX was to graphic design — not new principles, but applying them for a specific consumer under specific constraints. Four pressures shift when the consumer is an agent:

Context budget. With REST APIs, 500 endpoints cost the developer cognitive load; they find the three they need and ignore the rest. With AI tools, every definition consumes tokens from a finite context window. Too many or too verbose, and you degrade the AI's reasoning about all of them. Bloated surfaces are a performance problem, not just ergonomics.

Probabilistic selection. A developer writes fetch('/api/animals/4521') — explicit. An AI matches "check on that animal" to get_animal_info through semantic inference. Similar descriptions → wrong tool. Naming is a correctness concern.

Starts from zero every time. A developer learns your API over time. An AI has no memory. Every conversation is fresh. Rename a tool and there's no migration path. Stability and naming consistency matter far more.

Emergent composition. In APIs you design orchestration explicitly. With AI, the agent decides the sequence at runtime. You provide building blocks; the AI assembles them. Convenience endpoints that chain workflows remove the agent's ability to handle partial flows. The design pressure runs the opposite direction.

The AX Discipline Map

AX needs a structure for evaluation — like Nielsen's heuristics for UX. Six concerns we've found useful:

Orchestration Design — Can the agent assemble your tools into coherent workflows, or are there gaps?
Tool Contract Design — Can the agent figure out what a tool does, when to use it, and how to call it from the signature alone?
Context Economics — Are you spending the agent's context budget wisely, or drowning it in noise?
Domain Legibility — Does the agent understand your business after reading your tool definitions?
Safety & Trust Design — Can the agent investigate freely without accidentally breaking things?
Error & Recovery Design — When something goes wrong, can the agent figure out what to try next?

How do you know if AX is working? Test it. Run twenty representative user prompts. Measure tool selection accuracy, task completion, and recovery rate. That's the AX equivalent of a usability study.

Principles You Already Know

You don't need new principles — you need to apply existing ones with a different consumer in mind.

Single Responsibility. A tool should do one thing. A kitchen-sink tool with action: move | treat | ship | lookup forces the AI to reason combinatorially. Focused tools like get_animal_info, save_cattle_treatment, save_cattle_moves map cleanly to user intent.

Ubiquitous Language. The AI's only path to your domain is through tool and parameter names. In a feedlot system, operators say "calling feed" — so save_call_per_head with callPerHead in lbs matches naturally. Name it create_feed_record and the AI bridges a vocabulary gap that didn't need to exist. The AX surface is the documentation.

Composition over monoliths. Don't build performFullTreatmentWorkflow. Expose atomic steps: validate_treatment_tag, get_treatment_setup, save_cattle_treatment. The AI sequences them. Bury it in one tool and you lose partial workflows ("just check if 4521 is eligible") and graceful failure handling.

Safety boundaries. The AI needs to know which tools are safe to explore versus which have side effects. get_animal_info and get_open_lots — read-safe. save_cattle_treatment and save_cattle_moves — the agent should confirm before calling. Make the read/write boundary visible in the tool contract.

What AX Gets You

Netlify reports over 1,000 sites deploying daily from ChatGPT through agent-optimized infrastructure — measurable business impact from AX investment. Our experience building an POC MCP server for a feedlot system: applying AX principles (consistent get_/save_ naming, domain vocabulary, single-responsibility tools) eliminated compensatory system prompts. The AI selected the correct tool on first attempt for the vast majority of prompts — no few-shot examples, no elaborate tuning. One team's experience, not a controlled study, but the results were immediate.

Teams that treat AX as a discipline gain: better AI integrations with less prompt engineering, agent portability across Claude/GPT/Gemini, faster capability onboarding, lower token costs, and compounding returns as quality builds trust.

From Ad Hoc to Discipline

Most teams building tool servers today do it ad hoc — smart decisions without a shared framework. Start here: look at your tool definitions through the six concerns. Ask the litmus questions. The principles are the same ones you've practiced. They just have a new consumer.

AX will evolve as constraints shift — persistent memory, larger context windows. But the core challenge — making your systems legible for a reasoning consumer — persists whether the AI calls a tool, generates HTTP, or writes code. The mechanism is an implementation detail. The discipline is about the consumer.

In UX, you're not the user. In AX, you're not the agent. The craft of designing for someone else — that's the same skill it's always been.