DEV Community: Ben Greenberg

From First-Run Drop-Off to First Useful Agent Run

Ben Greenberg — Thu, 16 Jul 2026 22:16:16 +0000

I keep coming back to the same onboarding question: what happens in the first 10 minutes?

For agent tools, that window is brutal. A developer opens a repo, starts the agent, asks for a change, and waits to see if the tool understands the project. If the agent guesses the package manager, misses the test path, edits generated files, or asks the developer to explain the repo from scratch, trust drops fast.

That isn't an agent model problem every time. A lot of it is repo readiness.

The Agentic AI Foundation, hosted by the Linux Foundation, is building an open home for projects like MCP, goose, AGENTS.md, and agentgateway. That work can sound big and infrastructural, but one of the most useful entry points is small: make your repo easier for an agent to understand on the first run.

AGENTS.md is the repo-side context. goose is a practical runtime path. Together, they give you a way to move from "the agent is poking around" to "the agent made a useful first pass."

Start With The First Useful Run

Don't begin by asking, "What should our agent docs say?"

Ask this instead: what should a developer be able to ask an agent to do in this repo within 10 minutes?

Pick one task. Not the whole system. One useful first run.

For example:

Find the right entry point for a small bug
Add a focused test around an existing function
Update a docs page with a known source file nearby
Explain how a specific package or module is wired

That first run gives your AGENTS.md a job. It isn't a policy dump. It's the context an agent needs to avoid wasting the developer's first session.

Put Repo Truth Where Agents Can Find It

AGENTS.md is a simple open format for guiding coding agents, and the project site says it's already used by over 60k open-source projects: https://agents.md.

The reason it works is plain: agents need a predictable place for repo instructions. README files are written for humans. CI files are written for automation. AGENTS.md gives agents the details that usually live in maintainer heads.

Your first version should answer:

What kind of project is this?
Where does source code live?
Where do tests live?
Which files should agents avoid editing?
What style or architecture choices should agents preserve?
What should the agent do before claiming a task is done?

Keep it short enough that someone would maintain it. Stale agent instructions are worse than missing ones because they create confident mistakes.

Write Instructions Like Maintainer Notes

An AGENTS.md file doesn't need brand language. It needs maintainer notes.

Say things like:

# AGENTS.md

## Project Shape

This repo contains a web app and supporting packages. App code lives in `apps/web`. Shared code lives in `packages`.

## Working Rules

Prefer small changes that match nearby patterns. Do not rewrite public APIs unless the task asks for it.

## Tests

When changing behavior, add or update the closest existing test. If you can't run the test locally, say what you inspected and why the test wasn't run.

## Files To Avoid

Do not edit generated files, lockfiles, or vendored code unless the task is specifically about dependency updates.

Notice what's missing: fake certainty.

Don't say "run the full test suite" unless that's realistic. Don't list commands you haven't checked. Don't tell the agent to use a package manager you don't use. Your agent instructions should be as true as your README.

Design The Goose Path

goose is an open-source AI agent runtime under AAIF. Its project page describes it as an agent that can install, execute, edit, and test with any LLM: https://aaif.io/projects/goose.

For onboarding, think of goose as the first-run path you can test against your repo instructions.

A good first-run path has three pieces:

A clear starting task
A repo-level AGENTS.md
A visible stopping point

The stopping point matters. If the agent changes code, how does the developer know whether it did the right thing? Maybe the agent should point to the files it changed. Maybe it should explain the test it would run. Maybe it should stop before touching a migration, generated file, or public API.

That belongs in AGENTS.md.

Make The Agent Ask Better Questions

A useful agent doesn't need to know everything. It needs to know when to stop guessing.

Add guidance for uncertainty:

## When Unsure

If the requested change touches auth, billing, data deletion, or production configuration, ask before editing.

If there are multiple plausible implementations, describe the tradeoff and choose the smallest local change unless the user tells you otherwise.

Why does that help? Because first-run drop-off often comes from surprise. The agent edits the wrong layer, takes a broad refactor path, or treats a risky area like ordinary code.

Good instructions narrow the blast radius.

Treat Docs As Product Surface

Developer onboarding isn't separate from product. The docs shape what users try, where they get stuck, and whether they come back.

For agent-ready repos, AGENTS.md is part of that product surface. So review it the same way you'd review a quickstart:

Is the first task obvious?
Are repo boundaries named?
Are setup assumptions current?
Are risky areas called out?
Can a new contributor tell what "done" means?

This is where AAIF's open ecosystem angle becomes practical. If agent tools are going to work across projects, maintainers need shared conventions that don't depend on one vendor, one editor, or one model. AGENTS.md gives repos a portable instruction layer. goose gives developers an open way to run agent workflows against it.

Small file. Real leverage.

A Practical Checklist

Use this before you point an agent at your repo:

Pick one first-run task a new developer would value.
Add or update AGENTS.md with project shape, test expectations, and files to avoid.
Remove commands you haven't verified.
Tell the agent how to behave around risky code paths.
Run the first task through goose or your agent runtime of choice.
Edit AGENTS.md based on where the agent guessed wrong.
Repeat until the first run produces something you would review seriously.

The goal isn't to make the agent perfect. The goal is to make the first session legible.

A developer should be able to open the repo, start the agent, ask for one scoped task, and understand the result without becoming the repo tour guide.

I built my first Robinhood Chain app as an index basket

Ben Greenberg — Sun, 12 Jul 2026 15:51:24 +0000

I built a small index basket app on Robinhood Chain because I wanted to understand the developer path from the first contract deploy all the way to a working frontend.

The app is intentionally plain: a user deposits Stock Tokens, which are blockchain tokens that represent real equity exposure, and receives an ERC-20 basket share. ERC-20 is Ethereum's standard token interface, so a compatible token exposes familiar methods like balanceOf, transfer, and approve. The basket share is priced from live price feeds, and the user can redeem it back into the underlying Stock Tokens.

That's the part that made this interesting to me. The chain is custom, but the app path is not. I still wrote Solidity, deployed with Foundry, read contract state with viem, and wrote transactions from React with wagmi.

If you've built normal web apps, think of the chain's RPC endpoint as the API base URL. A wallet is login plus a signing key. A smart contract is backend code you deploy to the chain, except you should treat it like immutable infrastructure because you don't get to hot-patch it casually later.

The demo and source are here:

The custom chain still feels like the EVM

Robinhood Chain is a custom Arbitrum Chain, which means it runs as a dedicated chain on the stack of Arbitrum, an Ethereum scaling system. It is also EVM-compatible. EVM means Ethereum Virtual Machine, the runtime that executes Solidity contracts, so the tooling surface looks like the Ethereum developer flow many tutorials already teach.

An L2, or rollup, is a chain that executes transactions separately and then posts compressed proof or transaction data back to Ethereum. Robinhood Chain uses Ethereum blobs for data availability, which is a cheaper Ethereum data lane for rollups to publish the data needed to reconstruct chain state. Gas, the metered compute fee you pay to run transactions, is paid in ETH.

The first deploy looks like this:

export PRIVATE_KEY=0x<your_private_key>
export RH_RPC_URL=https://rpc.testnet.chain.robinhood.com

forge create src/MyContract.sol:MyContract \
  --rpc-url $RH_RPC_URL \
  --private-key $PRIVATE_KEY \
  --broadcast

Foundry is the contract build, test, and deploy CLI. forge create compiles the contract, sends the deployment transaction, and broadcasts it to the RPC endpoint.

This is the part I appreciate as a developer. Robinhood gets its own chain configuration, infrastructure, pricing, and product controls. I still get the contract model I know how to reason about.

Stock Tokens are ERC-20s with display accounting

Stock Tokens are ERC-20s that represent real market assets. That means contracts can read balances, request approvals, and transfer them using the same functions they would use for any other ERC-20.

IERC20 nvda = IERC20(NVDA_TOKEN_ADDRESS);

uint256 balance = nvda.balanceOf(user);
nvda.approve(spender, amount);
nvda.transfer(recipient, amount);

The wrinkle is corporate actions. Stocks split. Dividends happen. The economic relationship between one token and one underlying share can change.

Stock Tokens implement ERC-8056, the Scaled UI Amount extension. Raw token balances stay stable for contracts. A UI multiplier is how wallets and apps display the share-equivalent amount.

interface IScaledUIAmount {
    function uiMultiplier() external view returns (uint256);
    function balanceOfUI(address account) external view returns (uint256);
    function totalSupplyUI() external view returns (uint256);
    function newUIMultiplier() external view returns (uint256);
    function effectiveAt() external view returns (uint256);
}

The display conversion is:

underlyingShares = rawBalance * uiMultiplier / 1e18;

Why not just mutate balances after a split?

Because contracts depend on stable accounting. If my basket contract holds a raw token balance, I don't want a display-level corporate action to unexpectedly rewrite the reserve math inside the contract. The UI can show share-equivalent amounts, and the protocol can keep using raw ERC-20 units.

The basket contract does only a few things

The sample app has two contracts and no owner.

Contract	Role	Control surface
`BasketFactory`	Deploys and records baskets	Permissionless
`BasketToken`	Holds components, mints, redeems, prices shares	No owner or upgrade path

The factory does not custody user funds. It deploys a basket and records the address.

function createBasket(
    string calldata name,
    string calldata symbol,
    BasketToken.Component[] calldata components,
    uint256 maxPriceAge
) external returns (address basket) {
    basket = address(new BasketToken(name, symbol, components, maxPriceAge));
    _baskets.push(basket);
    isBasket[basket] = true;
    emit BasketCreated(basket, msg.sender, name, symbol);
}

Each basket stores a fixed list of components. A component is a token, a price feed, and the amount of that token backing one basket share.

struct Component {
    address token;
    address feed;
    uint256 unitsPerShare;
}

A price feed is an external data source a contract or app can read. In this app, the feeds come from Chainlink, an oracle network that publishes market data onchain. An oracle is the bridge between offchain facts, like a stock price, and onchain code.

On mainnet, the production chain where real assets move, the demo basket uses TSLA, NVDA, and AAPL Stock Tokens with their Chainlink feeds:

function _mainnetComponents()
    internal
    pure
    returns (BasketToken.Component[] memory c)
{
    c = new BasketToken.Component[](3);
    c[0] = BasketToken.Component(MAINNET_TSLA, MAINNET_TSLA_FEED, 0.4e18);
    c[1] = BasketToken.Component(MAINNET_NVDA, MAINNET_NVDA_FEED, 0.3e18);
    c[2] = BasketToken.Component(MAINNET_AAPL, MAINNET_AAPL_FEED, 0.3e18);
}

One TRIO share is backed by 0.4 TSLA, 0.3 NVDA, and 0.3 AAPL.

On testnet, which is a staging chain with no real funds at risk, the demo uses faucet Stock Tokens for TSLA, AMZN, and NFLX with mock feeds. A faucet is a service that gives you test tokens so you can build without spending real money.

Minting follows the ERC-20 approval pattern

From the frontend, minting is two steps: approve each component token, then call the basket.

await writeContract({
  address: stockTokenAddress,
  abi: erc20Abi,
  functionName: "approve",
  args: [basketAddress, amount],
});

await writeContract({
  address: basketAddress,
  abi: basketTokenAbi,
  functionName: "mint",
  args: [shares, account],
});

That writeContract call is from wagmi, a React library for wallet connections and contract writes. viem is the TypeScript Ethereum client underneath it for typed reads, writes, and transaction handling.

Onchain, the basket pulls the required component amounts and mints shares in the same transaction.

function mint(uint256 shares, address to) external nonReentrant {
    if (shares == 0) revert ZeroShares();

    uint256 count = _components.length;
    for (uint256 i = 0; i < count; i++) {
        Component memory c = _components[i];
        uint256 amount = Math.mulDiv(
            c.unitsPerShare,
            shares,
            SHARE_UNIT,
            Math.Rounding.Ceil
        );

        IERC20(c.token).safeTransferFrom(msg.sender, address(this), amount);
    }

    _mint(to, shares);
    emit Minted(msg.sender, to, shares);
}

The rounding direction matters. Mint rounds up so a user cannot underpay the basket reserves by tiny decimal leftovers.

Redeem is the mirror image. Burn first, transfer components out, and round down so the reserves cannot be overdrawn.

function redeem(uint256 shares, address to) external nonReentrant {
    if (shares == 0) revert ZeroShares();
    if (to == address(0)) revert ZeroAddress();

    _burn(msg.sender, shares);

    uint256 count = _components.length;
    for (uint256 i = 0; i < count; i++) {
        Component memory c = _components[i];
        uint256 amount = Math.mulDiv(
            c.unitsPerShare,
            shares,
            SHARE_UNIT,
            Math.Rounding.Floor
        );

        IERC20(c.token).safeTransfer(to, amount);
    }

    emit Redeemed(msg.sender, to, shares);
}

Redeem skips the price feed and the factory. It burns shares and returns the component tokens the contract already holds.

I keep pricing and redemption apart on purpose. You use the price for the UI. Redeem returns the collateral.

Local to mainnet is the path I want rehearsed

The repo gives you the whole loop.

git clone --recurse-submodules https://github.com/hummusonrails/robinhood-chain-dapp-example.git
cd robinhood-chain-dapp-example

pnpm install
anvil
pnpm run deploy:local
pnpm run smoke
pnpm run dev

anvil is Foundry's local development chain. Think of it as a throwaway local server for contracts. The local deploy creates mock Stock Tokens, mock Chainlink feeds, the factory, and a demo Tech Trio basket. It also writes apps/frontend/.env.local, so the frontend knows which addresses to call.

For Robinhood Chain testnet:

PRIVATE_KEY=$YOUR_TESTNET_KEY pnpm run deploy:testnet

One Foundry script handles local, testnet, and mainnet by checking the chainid, which is the chain's network identifier.

function run() external {
    vm.startBroadcast();

    BasketFactory factory = new BasketFactory();
    console2.log("FACTORY=%s", address(factory));

    BasketToken.Component[] memory components;
    if (block.chainid == 4663) {
        components = _mainnetComponents();
    } else if (block.chainid == 46630) {
        components = _testnetComponents();
    } else {
        components = _localComponents();
    }

    address basket =
        factory.createBasket("Tech Trio", "TRIO", components, MAX_PRICE_AGE);

    console2.log("DEMO_BASKET=%s", basket);
    console2.log("CHAIN_ID=%s", block.chainid);

    vm.stopBroadcast();
}

The testnet deployment behind the live walkthrough is:

Contract	Address
`BasketFactory`	`0xC1940D5fd58ce735A44a53f910852B12250F6a14`
`BasketToken` (`TRIO`)	`0x7633e0920Ea46A8Ec54F61C95adECD391c01Edd4`

Before spending mainnet gas, I want fork tests. A fork test runs tests against a local copy of live chain state, so you can check integration assumptions without sending real transactions.

pnpm run test:contracts
pnpm run test:fork

Here is the shape of the fork test:

function test_mintAndRedeem_withRealStockTokens() public {
    deal(TSLA, alice, 1e18);
    deal(NVDA, alice, 1e18);
    deal(AAPL, alice, 1e18);

    vm.startPrank(alice);
    IERC20Metadata(TSLA).approve(address(basket), type(uint256).max);
    IERC20Metadata(NVDA).approve(address(basket), type(uint256).max);
    IERC20Metadata(AAPL).approve(address(basket), type(uint256).max);

    basket.mint(2e18, alice);
    assertEq(basket.balanceOf(alice), 2e18);
    assertEq(IERC20Metadata(TSLA).balanceOf(address(basket)), 0.8e18);

    basket.redeem(2e18, alice);
    assertEq(basket.totalSupply(), 0);
    assertEq(IERC20Metadata(TSLA).balanceOf(alice), 1e18);
    vm.stopPrank();
}

That is the development loop I want for this kind of app: mocks for speed, testnet for wallet flow, fork tests for live integration assumptions, and mainnet only after the path is rehearsed.

A block explorer, which is basically hosted request logs for a chain, then gives you a way to inspect deployed contracts and transactions. The testnet contracts are verified on Blockscout, so you can read the source and calls after deployment.

Stock Tokens change the app assumptions

Stock Tokens still fit the ERC-20 interface, but the surrounding assumptions are different from a generic token.

For user balances, don't blindly show balanceOf. Use balanceOfUI or apply uiMultiplier so the user sees the share-equivalent amount.

For prices, read the per-token Chainlink feed on mainnet. For corporate actions, track multiplier updates and pending effective times. For valuation, remember that the feed price already includes the multiplier.

Stock market hours matter too. Crypto feeds may update around the clock. Stock feeds follow market sessions, so stale data checks need to reflect that.

The exit path is the one I care about most. If a user wants to redeem their basket share, I don't want that flow blocked because an oracle read is stale. The contract already holds the component tokens. Redemption should return the collateral.

Learn the chain later; start with the app

Robinhood Chain runs on Arbitrum Nitro, the same underlying technology as Arbitrum One, deployed as a dedicated chain. Arbitrum One is the public shared L2. A custom Arbitrum Chain gives a team its own execution environment while keeping the Ethereum-style contract model.

The mechanics under the hood are also why the fees are small. Transactions hit a sequencer, which is the service that orders transactions for the rollup, land in fast blocks, get batched, and settle back to Ethereum using blob data. The fee combines L2 execution gas with the data cost on L1, which is Ethereum itself.

That's useful context, but I wouldn't start by trying to absorb the whole chain architecture.

Start with the working system. Read a Stock Token balance. Approve a token. Mint a share. Redeem it. Check the price feed. Run the fork test. Look at the transaction in a block explorer.

Plenty of apps can live on Robinhood Chain. This basket is a good first build because it touches the surfaces most apps using market assets will need: token reads, approvals, ERC-8056 display logic, Chainlink feeds, local mocks, testnet deployment, verified contracts, fork tests, and a Next.js frontend using wagmi and viem.

What I learned from building it is where the real work sits: deciding where accounting belongs, where pricing belongs, and which assumptions deserve a test before real users and real assets touch the contract. The app stack itself is familiar.

The MCP Release Candidate Survival Guide: Apps, Auth, Deprecations, and Tool Schemas

Ben Greenberg — Thu, 02 Jul 2026 10:27:58 +0000

The MCP 2026-07-28 release candidate is the largest major specification revision since MCP launched. It is also a compatibility test for everyone building clients, servers, SDKs, gateways, and developer tools around the protocol.

The release candidate was locked on May 21, 2026. The final specification is scheduled for July 28, 2026. This window is the time to test real implementations and find migration pain points.

1. Check your transport assumptions

The biggest change is that MCP is now stateless at the protocol layer.

If your current Streamable HTTP implementation depends on initialize, initialized, or Mcp-Session-Id, you have migration work. In the release candidate, each request carries the protocol version, client info, and capabilities in _meta. The new server/discover method covers cases where a client needs server capabilities up front.

A tools/call request over Streamable HTTP now includes headers such as:

MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: search

That changes how infrastructure can handle MCP traffic. A gateway no longer needs to inspect JSON bodies just to route or rate-limit common operations. A load balancer can send requests to any server instance because the protocol no longer assumes a sticky session.

The compatibility question is simple: does your server still hide required state in the connection?

If yes, move that state into an explicit application handle. For example, a tool can return a basket_id, browser_id, or job handle, and the model can pass it back as a normal tool argument later. That makes state visible to the model and portable across server instances.

2. Test server-to-client request flows

Stateless MCP still needs interaction during a call. The release candidate changes how that works.

Server-initiated requests can only happen while the server is processing a client request. For elicitation, roots, or sampling flows, the server returns an InputRequiredResult, and the client retries the original call with inputResponses and requestState.

That means clients need to preserve and replay the right data. Servers need to treat the retry as a continuation, even if it lands on another instance.

A good test case is a destructive tool call that asks for confirmation. The server should return an input request, the client should collect the answer, and the retry should succeed without relying on connection memory.

3. Treat MCP Apps as real app surfaces

MCP Apps let servers provide interactive HTML interfaces that hosts render in sandboxed iframes.

This is a big developer-experience change, but it also has security and product implications. Tools can declare UI templates ahead of time, which lets hosts prefetch, cache, and review them before anything runs. The UI still talks back through MCP’s JSON-RPC protocol, so UI-driven actions go through the same consent path as tool calls.

If you maintain a host, test your iframe isolation, permission prompts, and caching behavior. If you maintain a server, check that your UI template declarations are deterministic and do not depend on hidden session state.

The Apps model will reward consistent discipline: explicit templates, clear tool boundaries, and no surprise network behavior.

4. Harden authorization now

The release candidate tightens MCP authorization around OAuth 2.0 and OpenID Connect deployments.

Clients now need to validate the iss parameter on authorization responses under RFC 9207. Authorization servers should begin sending iss now because future clients are expected to reject responses without it.

Dynamic Client Registration also changes. Clients declare OpenID Connect application_type, which matters for desktop and CLI clients using localhost redirect URIs. Clients also bind registered credentials to the issuing authorization server’s issuer.

The migration checklist here is direct:

Verify iss handling in clients.
Confirm authorization servers send iss.
Check Dynamic Client Registration metadata.
Re-register when a resource moves between authorization servers.

This is especially relevant for MCP because one client may connect to many servers. Mix-up risks are not theoretical in that shape.

5. Stop building new work on deprecated core features

Roots, Sampling, and Logging are deprecated in the release candidate.

They still work. The deprecation is annotation-only for this release, and the methods, types, and capability flags continue to work in every spec version published within a year of it. Removal would require a separate SEP.

Still, new work should move elsewhere:

Roots should move to tool parameters, resource URIs, or server configuration.
Sampling should move to direct integration with model provider APIs.
Logging should move to stderr for stdio or OpenTelemetry for structured observability.

If you maintain SDK abstractions, this is the moment to add warnings without breaking users. If you maintain docs, stop teaching deprecated features as the default path.

6. Validate tool schemas against JSON Schema 2020-12

Tool inputSchema and outputSchema now use full JSON Schema 2020-12.

For input schemas, the root still has to be type: "object", but schemas can now use oneOf, anyOf, allOf, conditionals, $ref, and $defs. Output schemas are unrestricted. structuredContent can be any JSON value instead of only an object.

That creates opportunity and risk.

Servers should bound schema depth and validation time. Implementations should not auto-dereference external $ref URIs. Clients that made assumptions about simple object-only schemas need tests against composed schemas.

Also check error handling. The missing resource error changes from MCP’s custom -32002 to the JSON-RPC standard -32602 Invalid Params. If your client matches on the literal code, update it.

As you work through the checklist, if you find any issues or major friction points bring them to the community. You can open an issue in the specification repository. For implementation questions, the relevant Working Group channel in the contributor Discord is the fastest path to an answer.

MCP Server or CLI: A Decision Rubric for Developer Tooling

Ben Greenberg — Wed, 01 Jul 2026 14:29:03 +0000

Teams are rushing to make their internal tools available to agents. That is good. It is also where a lot of design mistakes begin.

The question usually shows up like this:

Should we expose this as an MCP server, or should the agent just use our CLI?

That framing makes it sound like one option is more “agentic” than the other. I do not think that is the useful distinction. A CLI and an MCP server solve different problems. The better question is: where does this capability naturally live, and what contract does the agent need in order to use it well?

MCP, now hosted by the Agentic AI Foundation under the Linux Foundation, gives the open agentic AI ecosystem a shared protocol for connecting agents to tools, data, and applications. That shared protocol matters because teams should not have to rebuild the same integration patterns for every agent runtime. But MCP is not a reason to wrap every executable in a server. Sometimes a CLI is exactly the right interface. Sometimes an MCP server is. Often, the answer is both, with different responsibilities.

Here is the rubric I use.

Start with the workflow

A CLI is strongest when the workflow already belongs to a human developer.

If the task is repo-local, terminal-native, and already part of how developers build, test, debug, or ship software, start with the CLI. Developers know how to inspect it. CI can run it. Logs are usually visible. Failures can be reproduced outside the agent. The same interface works for humans, scripts, and automation.

Good CLI-shaped examples:

Running a project-specific code generator
Applying a migration in a local development environment
Linting, formatting, testing, or packaging
Inspecting repo state
Scaffolding files inside a checked-out project
Running one-off diagnostics where stdout and exit codes are enough

An MCP server is strongest when the workflow does not naturally belong in a terminal session, or when the agent needs a structured, discoverable capability instead of a command string.

Good MCP-shaped examples:

Reading from or writing to a SaaS API
Searching a private knowledge base
Fetching typed records from an internal system
Performing actions that need scoped authorization
Exposing capabilities across multiple agent clients
Providing context as resources, not just command output
Giving the agent a constrained set of tool calls instead of broad shell access

The trap is assuming that “agent can run command” and “agent has a good tool interface” are the same thing. They are not.

A CLI gives an agent a way to execute. MCP gives an agent a way to understand what capabilities exist, what inputs they accept, and what kind of result comes back.

The five-question rubric

When deciding between a CLI, an MCP server, or both, I like to ask five questions.

1. Is this primarily an interactive human workflow?

If yes, prefer a CLI.

Developers still need tools that work when no agent is involved. If a human would reasonably run the tool while sitting inside a repo, reading logs, adjusting flags, and retrying, a CLI is usually the right primary interface.

That does not mean agents cannot use it. Agents are quite good at driving existing developer workflows when the commands are documented and the outputs are predictable. This is where AGENTS.md fits naturally: document which commands are safe, how to run tests, what directories are off-limits, and what failure modes are expected.

The CLI should be boring in the best way:

Clear subcommands
Stable flags
Machine-readable output where useful
Non-zero exit codes on failure
Dry-run modes for risky actions
Good help text
No hidden interactive prompts in automation paths

If the tool needs a human to make judgment calls mid-run, keep that interaction in the CLI. Do not hide it behind an MCP tool and pretend the workflow became autonomous.

2. Does the agent need to discover the capability?

If yes, lean toward MCP.

One of the real advantages of MCP is that tools can be described to the agent as tools. The agent does not need to infer everything from a README, shell history, or tribal knowledge. It can see available tool names, descriptions, schemas, and expected inputs.

That matters when the capability is meant to be reused across agents or across teams.

A CLI can be documented well, but discovery is still indirect. The agent needs to know the command exists, know where it is installed, know how to call it, and know how to interpret the output. MCP makes the capability part of the agent’s tool surface.

Use MCP when the agent should be able to answer questions like:

What tools are available to me?
What arguments does this action require?
What resources can I inspect?
What shape will the result have?
What actions are allowed in this environment?

This is especially useful for APIs and internal systems where a raw CLI would either expose too much or force the agent to learn a human-oriented interface.

3. Where is the auth boundary?

If the action crosses an authorization boundary, consider MCP carefully.

A CLI often inherits the developer’s local environment: shell credentials, config files, tokens, SSH agents, cloud profiles. That can be fine for local workflows. It can also be too broad for agent access.

MCP gives teams a cleaner place to define permission boundaries. The server can expose only the operations the agent should have. It can scope credentials server-side. It can validate inputs before touching the underlying system. It can log tool calls in a way that is easier to review than arbitrary shell execution.

This does not make MCP magically safe. A poorly designed MCP server can still be dangerous. But the server boundary gives you a place to enforce policy.

Ask:

Should the agent inherit the user’s full shell environment?
Should this action use delegated or scoped credentials?
Do we need per-tool authorization?
Do we need audit logs of agent actions?
Do we need to prevent arbitrary command composition?

If the answer to those questions is yes, a CLI alone may be too blunt.

For production-facing systems, this is also where infrastructure projects like agentgateway become relevant. Once agent traffic spans MCP servers, APIs, models, and services, teams need consistent policy, routing, and observability. That is a different layer than the individual tool decision, but the design choices connect.

4. Is the operation stateful?

State changes raise the bar.

A read-only diagnostic command is one thing. A tool that creates tickets, deploys services, updates customer data, rotates secrets, or changes infrastructure is another.

For state-changing actions, the interface should make the action hard to misuse. That can be done in a CLI, an MCP server, or both. The question is which interface gives you the better control surface.

A CLI might be right when the state change belongs in a developer-controlled workflow:

Apply this migration to my local database
Generate this file in my branch
Create a release artifact after tests pass

An MCP server might be right when the state change touches an external system:

Create an incident
Update a CRM record
Open a pull request with a structured payload
Provision access for a user
Trigger a workflow in a deployment platform

For stateful MCP tools, I would avoid generic verbs like run, execute, or update when the action can be modeled more specifically. The tool should say what it does. The input schema should constrain what can happen. The response should include enough structured data for the agent to verify the result.

For stateful CLIs, I want dry-run support, confirmation controls that can be disabled only in explicit automation modes, and output that makes it clear what changed.

The shared principle is the same: the agent should not be guessing.

5. What is the maintenance cost?

Every new interface becomes a product surface.

A CLI needs packaging, versioning, docs, help text, examples, and compatibility guarantees. An MCP server needs all of that plus server lifecycle, transport decisions, schema design, client compatibility, authentication, deployment, monitoring, and operational ownership.

That cost may be worth it. But it should buy something real.

An MCP wrapper around a CLI can be useful when it adds:

Better tool descriptions
Safer input validation
Structured outputs
Scoped permissions
Shared access across agent clients
A stable abstraction over a messy underlying command
Resource access the CLI does not provide well

An MCP wrapper is probably not worth it when it only shells out to an existing command and returns the same text output the agent would have seen anyway.

That does not mean “never wrap a CLI.” It means the wrapper should create leverage. If the MCP server is only a thinner, less debuggable path to the same command, keep the CLI and document it well.

The “both” pattern

Many teams should build both, but not as duplicates.

A good pattern is:

The CLI remains the human and CI interface.
The MCP server exposes selected capabilities for agents.
Shared core logic lives below both interfaces.
The MCP server does not become a dumping ground for every CLI command.
The CLI does not become an escape hatch for unsafe agent actions.

For example, imagine an internal deployment tool.

The CLI might support the full developer workflow: build, validate, preview, deploy, rollback, inspect logs, and run local checks. It assumes the user is a developer with repo access and deployment permissions.

The MCP server might expose narrower tools: get deployment status, list services, create a preview environment, request a rollback plan, or fetch logs for a specific service. Those tools can have tighter schemas and safer defaults. They can also return structured data that an agent can reason over without parsing terminal output.

Both interfaces can call the same underlying deployment library. They do not need to expose the same surface area.

That separation is healthy. Humans need power tools. Agents need constrained capabilities with clear contracts.

A practical decision guide

Use a CLI when:

The task is repo-local or terminal-native
Humans need to run it directly
CI should run the same interface
Shell composition is a feature
Text output and exit codes are enough
The auth model is already appropriate for the local developer context

Use an MCP server when:

The agent needs discoverable tools or resources
The task touches an external system
Inputs and outputs should be typed
Permissions need to be scoped
Multiple agent clients should share the same integration
The tool should hide implementation details
Auditability and policy matter

Use both when:

Humans and agents both need the capability
The CLI is already valuable
The MCP server can expose a safer or more structured subset
Shared core logic can prevent drift
The agent interface should be stable even if the CLI evolves

Do neither, at least for now, when:

The workflow is not understood yet
The tool would expose broad credentials without guardrails
The “agent use case” is just novelty
A README update would solve the immediate problem
The maintenance owner is unclear

What this means for the open agentic AI ecosystem

The open agentic AI ecosystem needs standards like MCP. It also needs restraint.

If every team turns every script into an MCP server, agents get a larger tool list but not necessarily better tools. Tool overload is real. Poor descriptions, loose schemas, unsafe side effects, and noisy outputs make agents worse, not better.

The goal is not to make everything agent-accessible. The goal is to make the right capabilities available through the right contract.

That is why this decision matters so much at this particular moment. MCP gives builders a common way to expose tools and context. AGENTS.md gives projects a common place to tell coding agents how to work inside a repo. agentgateway points toward the operational layer teams need when agent traffic becomes production traffic.

These projects are stronger when we use them for the problems they actually solve.

A CLI is not “less agentic” because it runs in a terminal. An MCP server is not “better architecture” because it speaks a protocol. The useful line is simpler:

If the work belongs in the developer workflow, start with a CLI.

If the agent needs a structured, discoverable, permissioned capability, build an MCP server.

If both humans and agents need it, design both surfaces intentionally and keep the shared logic underneath.

That is the rubric. Not CLI versus MCP. CLI where the workflow lives. MCP where the capability needs a contract.

Turn a local skill library into agent-ready documentation

Ben Greenberg — Wed, 24 Jun 2026 11:32:16 +0000

Most agent setups start with a pile of useful local skills.

That pile usually makes sense to the person who built it. There is a skill for GitHub, one for writing, one for reminders, one for privacy filtering, one for making diagrams, one for checking session logs, one for working with canvases, one for creating new skills, and so on.

The problem shows up later, when a future agent has to decide what to do.

A local skill library answers the question, “What can this environment do?”

An AGENTS.md file should answer a different question:

When should an agent use each capability, what should it read first, what tools are safe to call, and what boundaries should it respect?

That difference matters. A directory full of skills is an inventory. Agent-ready documentation is an operating map.

This tutorial uses an OpenClaw-style skill library as the worked example, but the same pattern applies to any local agent setup.

Start with capabilities, not files

A common mistake is to document skills in filesystem order.

That gives you something like this:

- github
- writing-style-skill
- privacy-filter
- remind-me
- canvas
- skill-creator
- session-logs

That list is technically true, but it does not help an agent make decisions.

A better first pass groups skills by the work they enable:

## Capability map

### Development workflows

Use these when the user asks about code, repositories, issues, pull requests, debugging, or project maintenance.

- github: interact with GitHub through the `gh` CLI
- gh-issues: fetch issues, select candidates, delegate fixes, and open PRs
- node-inspect-debugger: debug Node.js processes
- python-debugpy: debug Python code

### Writing and publishing

Use these when the user asks for drafts, essays, social posts, newsletters, or style-sensitive writing.

- writing-style-skill: draft in the user's preferred voice
- blog-drafter: create blog drafts
- x-posts: optimize short-form posts and threads

### Safety and privacy

Use these when content may contain personal data, secrets, or sensitive context.

- privacy-filter: redact PII from text or files
- 1password: retrieve secrets through the approved CLI flow

### Personal automation

Use these when the user asks for reminders, home devices, calendar checks, or recurring background tasks.

- remind-me: create one-time reminders
- taskflow: coordinate longer detached jobs
- weather: check current weather and forecasts

This turns the library into a decision surface. The agent no longer has to infer that writing-style-skill is relevant to an essay draft, or that privacy-filter should be considered before sharing text externally. The map says so.

Add triggers

A capability map becomes much more useful when each section includes triggers.

Triggers are short descriptions of the user intent that should cause the agent to load a skill.

For example:

## Writing and publishing

Load `writing-style-skill` when the user asks to:

- draft an article, essay, email, talk abstract, or newsletter
- rewrite something in their voice
- adapt technical content for developers
- make a draft sound less generic

Load `x-posts` when the user asks to:

- write a post for X
- turn an idea into a thread
- improve a short social post for reach or clarity

Load `blog-drafter` only when the user explicitly wants a blog draft created.

The last line matters. Some skills only produce local context. Others take external action. blog-drafter crosses that boundary because it creates a draft in a publishing system. The agent needs to know that this should not happen casually.

Good triggers are concrete. Bad triggers are vague.

Bad:

Use this for content.

Better:

Use this when drafting or revising long-form writing, especially when tone and structure matter.

Best:

Load `writing-style-skill` before drafting blog posts, essays, conference abstracts, newsletter sections, or public-facing technical explanations.

The best version tells the agent what the user might actually say.

Document the first file to read

Many local skills have their own SKILL.md. An agent should not guess from the skill name alone. The root AGENTS.md should tell the agent which file is authoritative.

Example:

## Skill loading rule

When a task matches a skill, read that skill's `SKILL.md` before taking action.

Do not rely only on the skill name or description. The skill file may include safety rules, required tools, local paths, examples, or external-action limits.

For a local OpenClaw skill set, this is especially useful because different skills have different operational shapes.

A writing skill might mostly contain tone rules and examples.

A GitHub skill might specify preferred gh commands and review behavior.

A home automation skill might include device-specific constraints.

A privacy skill might define which data must be filtered before sharing.

The root file does not need to duplicate all of that. It needs to make skill loading mandatory and predictable.

Separate internal work from external action

Agent documentation should make one distinction very clear:

Reading, drafting, searching, and organizing are internal actions.

Sending, posting, publishing, deleting, buying, messaging, or changing real-world systems are external actions.

That boundary belongs near the top of AGENTS.md.

Example:

## External action boundary

The agent may freely:

- read local files
- inspect skill documentation
- draft text
- run non-destructive local checks
- prepare changes for review

The agent must ask before:

- sending email or messages
- publishing posts
- creating public drafts
- deleting data
- changing account settings
- controlling physical devices
- spending money

For OpenClaw-style environments, this boundary keeps powerful skills usable without making them reckless. A github skill that reads issues is different from one that opens a pull request. A blog skill that drafts locally is different from one that creates a draft in an external service. A govee or homeconnect skill can affect the physical environment.

Write those distinctions down.

Agents are much better when they do not have to reconstruct your risk model from vibes.

Capture tool boundaries inside each capability

A capability map should not only say what a skill does. It should say what the agent should avoid doing.

For example:

## Privacy and redaction

Use `privacy-filter` before sharing user-provided text outside the local workspace when it may contain:

- names
- addresses
- phone numbers
- email addresses
- account identifiers
- private messages
- internal business context

Do not paste raw private content into public channels or external tools unless the user explicitly approves it.

Or for GitHub:

## GitHub work

Use `github` for repository, issue, pull request, and CI work.

Safe without asking:

- inspect issues and PRs
- read CI logs
- check branch status
- prepare local patches

Ask before:

- opening a PR
- commenting publicly
- closing issues
- pushing branches to shared remotes

This is the part many local docs miss. They document how to use a tool, but not when to stop.

Include sequencing rules

Some skills should run before others.

In the OpenClaw set, writing-style-skill should load before drafting. privacy-filter should run before sharing sensitive text externally. skill-creator should load before changing skill files. github should load before acting on GitHub state.

That can be expressed as simple sequencing rules:

## Sequencing rules

Before drafting public writing, load `writing-style-skill`.

Before creating or modifying a reusable skill, load `skill-creator`.

Before using private text in an external channel, consider `privacy-filter`.

Before taking GitHub action, load `github` and inspect the current repository state.

Before using a tool that affects the outside world, confirm the user intended that action.

These rules save agents from doing work in the wrong order.

A good AGENTS.md does not need to cover every possible path. It should cover the paths where ordering matters.

Give agents examples of correct routing

Examples are often more useful than rules.

Here is a compact routing table:

## Routing examples

User asks: "Draft this as a technical blog post."
Use: `writing-style-skill`
Do: draft in the user's preferred voice
Do not: publish it anywhere

User asks: "Turn this into a blog draft."
Use: `writing-style-skill`, then `blog-drafter`
Do: prepare the content first
Ask before: creating the external draft, unless the user clearly requested that exact action

User asks: "Can you fix this GitHub issue?"
Use: `github`, possibly `gh-issues`
Do: inspect the issue, read the repo, make local changes, run tests
Ask before: opening a PR if the instruction was ambiguous

User asks: "Remember this workflow as a reusable skill."
Use: `skill-creator`
Do: create or update the skill through the approved skill workflow
Do not: hand-edit skill proposal state if the environment has a dedicated tool for that

User asks: "Share this private message in a public post."
Use: `privacy-filter`
Do: redact or summarize safely
Ask before: publishing or sending

The point is not to create a huge rules engine. The point is to give future agents enough examples to route the next request correctly.

Keep local notes out of shared skills

A reusable skill should explain general behavior. Local environment details belong somewhere else.

For OpenClaw-style workspaces, that might mean:

SKILL.md       -> reusable instructions
TOOLS.md       -> local device names, account aliases, hostnames, personal setup notes
AGENTS.md     -> workspace-level operating rules
MEMORY.md     -> durable user and project context

This separation keeps skills portable.

A weather skill can explain how weather lookup works. The local notes can say which city is usually relevant. A canvas skill can explain how to present HTML on connected nodes. Local notes can say which node names exist in this setup.

That distinction is small, but it keeps a skill library from turning into a private config dump.

Make safety boundaries visible, not buried

If a skill can send, post, delete, control, spend, or expose private data, say so in the capability map.

A practical format:

## High-risk skills

These skills can affect external systems or expose private data. Load their `SKILL.md` and confirm intent before using them for external action.

- blog-drafter: creates drafts in a publishing account
- imsg: can send iMessage/SMS
- work-slack: reads workplace Slack data
- gog/work-google: access personal or work Google data
- govee/homeconnect/sensibo/switchbot: control physical devices
- 1password: accesses secrets

This does not mean the skills are unsafe. It means they are powerful.

Agents do better with clear labels.

Write the root AGENTS.md as an operating manual

A useful AGENTS.md should be short enough to read and strong enough to steer behavior.

A good structure looks like this:

# AGENTS.md

## Role

You are working inside this workspace. Read local instructions before acting. Prefer existing skills and tools over inventing new workflows.

## Startup

Read:

- SOUL.md
- USER.md
- recent daily memory files
- MEMORY.md when in a direct private session

## Capability map

Group available skills by task:

- development workflows
- writing and publishing
- privacy and safety
- personal automation
- debugging and inspection
- media and presentation
- skill maintenance

## Skill loading

When a task matches a skill, read that skill's `SKILL.md` before acting.

## External action boundary

Internal work is allowed. External action requires clear user intent or confirmation.

## Safety rules

Protect private data. Prefer recoverable actions. Do not run destructive commands casually.

## Routing examples

Include examples of common user requests and the skills they should trigger.

## Local notes

Put machine-specific details in `TOOLS.md`, not in reusable skills.

That is enough to turn a pile of local skills into a working agent interface.

Treat AGENTS.md as a map, not a museum

The file should change as the skill library changes.

When you add a new skill, add it to the capability map. When a tool gains external side effects, move it into the high-risk section. When an agent makes a routing mistake, add a small example that would have prevented it.

The best AGENTS.md files are not long. They are current.

For developers building local agent systems, this is the real payoff: your skill library stops being something only you understand. It becomes a documented capability layer that future agents can read, reason over, and use correctly.

That is what agent-ready documentation is for.

An AI agent that pays for its own API calls on AWS

Ben Greenberg — Fri, 29 May 2026 11:27:13 +0000

I built a small AWS Bedrock AgentCore agent that pays for a paywalled API with real USDC on Arbitrum One. It asks for a report, gets back HTTP 402 Payment Required, settles the charge on its own, and retries. No API key, no card on file, no human clicking approve. The settlement lands on Arbitrum One mainnet, and the run prints an Arbiscan link to the transaction so you can read it yourself.

There's a great walkthrough of the same idea on Base Sepolia by William Mendoza Gopar. This post expands upon his work: mainnet instead of testnet, real USDC instead of a burn-address demo, and a merchant built on CloudFront, Lambda@Edge, and API Gateway. The full source is at github.com/hummusonrails/arbitrum-x402-aws.

What AgentCore gives you

AgentCore is AWS's hosted runtime for AI agents, still in preview. The piece this project leans on is AgentCore Payments: a managed signer that holds an embedded wallet for you and produces payment authorizations on request. Your code asks the PaymentManager to handle a charge, and the private key stays inside AgentCore.

You stand up four resources once: a PaymentManager with a connector to Coinbase CDP, an embedded crypto wallet as a PaymentInstrument, and a PaymentSession that carries a spend budget and an expiry. After that, paying is a single call.

What x402 is

x402 puts the 402 Payment Required status code to work. A paid endpoint answers an unpaid request with 402 and a JSON body describing what it wants: the network, the token, the recipient, and the amount. The client signs an EIP-3009 transferWithAuthorization for USDC, which lets someone else submit the transfer on-chain, and resends the request with the signature attached. The server verifies and settles through a facilitator, then returns the content. No accounts to create, no keys to rotate, and charges as small as a fraction of a cent. That last property is what lets an agent use it with no human in the loop.

One aside on the AWS side: this x402 support is a brand-new preview release. This week I worked with the AWS team to make sure it settles across EVM chains, Arbitrum One included, so the wallet, the facilitator, and the settlement path behave the same way on Arbitrum as on any other EVM network.

Why Arbitrum One

An agent that pays per API call cannot spend a dollar in transaction fees to move a fraction of a cent. The math only works if the settlement layer makes sub-cent payments cheap enough to vanish into the cost of the call itself. Arbitrum One clears that bar on price.

Price is half of it. The other half is predictability.

An agent commits to a workflow and runs it; it cannot pause to renegotiate when gas spikes partway through. When fees jump for a few minutes, a person shrugs and waits, but an agent paying per call either overpays or stalls. Arbitrum's gas pricing is built to absorb those spikes. The recent Arbitrum One upgrade replaced the old single-target pricing model, and during peak activity it cut gas by around 98% compared to what that model would have charged. Fees stay low, and they stay close to where they were a minute ago. For x402 micropayments, that stability is worth as much as the headline number.

The shape of the demo

Three pieces talk to each other. The agent runs on AgentCore with its embedded CDP wallet. The merchant is an AWS stack: CloudFront in front, a Lambda@Edge function on viewer-request that speaks x402, and an API Gateway HTTP API with a Lambda behind it that holds the report. Settlement runs through the Coinbase CDP facilitator, which broadcasts the USDC transfer on Arbitrum One.

The round trip looks like this. The agent does a GET /report. Lambda@Edge sees no payment and returns 402 with the terms. The agent asks AgentCore to produce a payment for those terms and retries. This time Lambda@Edge has a payment header, calls the facilitator to verify and settle, and on success passes the request through to API Gateway, which returns the gated JSON.

The agent side

The agent code is short because the wallet logic lives in AgentCore. It makes a normal GET. If the response is anything other than 402, it returns it. If it is a 402, it hands the whole challenge, status, headers, and body, to generate_payment_header, which reads the terms, signs the authorization inside the embedded wallet, and returns the header to attach. Then it retries the GET.

def fetch_with_payment(*, client, payment_manager, url, user_id,
                       payment_instrument_id, payment_session_id):
    first = client.get(url)
    if first.status_code != 402:
        return first

    payment_required_request = {
        "statusCode": 402,
        "headers": dict(first.headers),
        "body": first.text,
    }
    proof_headers = payment_manager.generate_payment_header(
        user_id=user_id,
        payment_instrument_id=payment_instrument_id,
        payment_session_id=payment_session_id,
        payment_required_request=payment_required_request,
        network_preferences=["eip155:42161"],  # Arbitrum One
        client_token=str(uuid.uuid4()),
    )
    return client.get(url, headers=proof_headers)

I pass network_preferences=["eip155:42161"] so the payment targets Arbitrum One rather than relying on a default. The agent never builds EIP-712 typed data and never touches the private key. From the caller's point of view it made one GET and got back a 200 with the report and an Arbiscan link.

The merchant side

The payment logic sits in the Lambda@Edge function on viewer-request. With no payment header it returns the 402 and the accepts[] terms. With a header it decodes the payment, calls the CDP facilitator's /verify, then /settle, and returns the original request so CloudFront continues on to API Gateway. A verify or settle failure comes back as a fresh 402 or a 502.

One detail to note: CDP's facilitator uses short-lived JWTs that are bound to the exact request URL and method and expire in two minutes. You cannot mint one ahead of time and paste it into config. The edge function signs a fresh JWT with node:crypto for each verify and settle call, which is also why the CDP key material gets inlined into the edge bundle at build time (Lambda@Edge cannot read environment variables at runtime).

A design choice worth flagging: this version verifies and settles in viewer-request, before the origin responds. That keeps the demo to one function and one round trip. For production you want to verify in viewer-request and settle in viewer-response, so you only take the money after the content is delivered.

Funding it and running it

Setup is one command that creates the AgentCore resources and prints a wallet address. You fund that wallet with USDC on Arbitrum One, grant the agent signing permission, and paste the printed IDs into .env. Then:

$ make run-agent
GET https://<merchant>/report
  via AgentCore PaymentSession payment-session-...
  using Instrument            payment-instrument-...

Status: 200
Body:
{ ...gated report JSON... }

Arbiscan: https://arbiscan.io/tx/0x...

The agent requests the report, pays, and prints the JSON plus the transaction link. The whole round trip takes a few seconds, most of it the facilitator talking to the chain. The charge in the repo is 0.01 USDC per call.

Cost and the preview caveat

Idle, this costs close to nothing. CloudFront, Lambda@Edge, API Gateway, and AgentCore are billed per use, and the demo's traffic fits inside their free tiers. Per call you pay the 0.01 USDC settlement and a rounding error of compute.

AgentCore Payments is in preview, so treat it that way. Field names and SDK shapes can move between releases, and I hit a few of those while building this. Pin your versions and re-test after you upgrade.

Where this goes next

The same pattern extends in two directions worth trying. The agent can pay several different x402 endpoints with the same wallet and session, which makes it a buyer for any priced API it can reach. And the spend budget on the PaymentSession is the natural place to wire an alert or a hard stop, so an agent that misbehaves runs out of allowance instead of running up a bill.

Resources

Repo: github.com/hummusonrails/arbitrum-x402-aws
The Base Sepolia walkthrough by William: go to his blog
x402 protocol: x402.org
Bedrock AgentCore: aws.amazon.com/bedrock/agentcore
EIP-3009 (Transfer With Authorization): eips.ethereum.org/EIPS/eip-3009

I let a kosher lobster run my Shabbat automations

Ben Greenberg — Thu, 23 Apr 2026 06:22:18 +0000

What I built

I run an Orthodox Jewish household. That means twenty-five hours a week, every week, the family doesn't touch electronics, doesn't cook, and doesn't adjust the thermostat without thinking about it. Multiply that by the Jewish holiday calendar, where a holiday can chain into Shabbat for two days straight, and you have a real scheduling problem. The fridge needs to be in Sabbath mode before candle lighting and back to normal at the conclusion of the day. The bedroom AC needs a pre-cooled run that ends before sunset. The living room AC needs to know whether it's a heat wave week or not. None of these can be touched once the time starts.

I built a personal automation stack on top of OpenClaw that handles all of it. The lobster is in charge.

There is a small wrinkle here that I think is a bit funny. Lobsters are not kosher. The mascot of the open source agent platform managing my religiously observant home is, in fact, one of the most explicitly non-kosher animals. The lobster AI has been very gracious about all of that.

How I used OpenClaw

OpenClaw skills are just directories with a SKILL.md and whatever scripts you want the agent to call. That structure made it natural to build each appliance as its own skill and then layer scheduler scripts on top that get triggered by cron jobs not the LLM.

This split matters. The schedulers don't need an LLM in the loop. They need to be deterministic, idempotent, and survive me forgetting they exist. The agent layer is for the times I message OpenClaw on Telegram and ask "is the fridge already in Sabbath mode?" and want a real answer back.

Here are two of the schedulers, with the city ID swapped out so you can drop in your own.

The Shabbat scheduler

This one runs every Friday morning. It pulls candle lighting and havdalah times from Hebcal, then schedules at jobs to flip the fridge into Sabbath mode an hour before candle lighting and back out at it concludes.

pythondef get_shabbat_times():
    """Fetch this week's candle lighting and havdalah times."""
    resp = requests.get(HEBCAL_URL, params={
        "cfg": "json",
        "geonameid": MY_CITY_GEONAMEID,
        "M": "on",
    }, timeout=15)
    resp.raise_for_status()
    data = resp.json()

    candles = None
    havdalah = None
    parasha = None
    for item in data.get("items", []):
        if item.get("category") == "candles" and not candles:
            candles = datetime.fromisoformat(item["date"])
        elif item.get("category") == "havdalah" and not havdalah:
            havdalah = datetime.fromisoformat(item["date"])
        elif item.get("category") == "parashat" and not parasha:
            parasha = item.get("title", "")
    return candles, havdalah, parasha

Then the actual scheduling:

pythonsabbath_on_time = candles - timedelta(hours=1)
schedule_at_job(sabbath_on_time, "on")
schedule_at_job(havdalah, "off")

That's the whole shape of it. Hebcal is the single source of truth for times, the appliance skill is the single source of truth for how to talk to the fridge, and the scheduler just glues them together with at.

The Holiday scheduler

This is the one that took the most thought, because the Jewish holiday calendar is genuinely hostile to naive scheduling. Rosh Hashana is two days. Yom Tov can start as Shabbat ends and run another full day. Passover has a full holiday day with all restrictions on day one, the intermediate days in the middle with no electroni restrictions, and the holiday fully again on the last day.

You can't just toggle the fridge per holiday day. You need to know when the whole continuous Sabbath-mode period actually ends.

So the scheduler walks forward through consecutive holiday days and Shabbat as one block:

pythondef find_end_of_period(start_date, yomtov_dates):
    """Walk forward through consecutive Yom Tov days and Shabbat.
    Handles multi-day Yom Tov, Yom Tov flowing into Shabbat,
    and Shabbat sandwiched between Yom Tov days."""
    current = start_date
    while True:
        next_day = current + timedelta(days=1)
        if next_day in yomtov_dates or next_day.weekday() == 5:
            current = next_day
        else:
            break
    return current

The most useful piece, though, is the coordination between schedulers. When a holiday starts as Shabbat is ending, the Shabbat scheduler has already queued an OFF job for the end of Shabbat. If the holiday scheduler runs and just queues its own ON job on top, you get a brief window where the fridge exits Sabbath mode and re-enters it, which defeats the point. So the Yom Tov scheduler clears the conflicting Shabbat job before doing its own work:

pythonif dow == 5:  # Saturday: Yom Tov starts motzei Shabbat
    log("Yom Tov follows Shabbat, fridge already in sabbath mode")
    log("Cancelling Shabbat OFF job so sabbath mode stays on")
    clear_existing_jobs("shabbat_scheduler.py")

That one block is the kind of thing working through the full complexity of the calendar introduces you to.

The reminder

Half an hour before candle lighting, OpenClaw sends me a checklist over Telegram. Nothing too complicated, just a quick list:

pythonmessage = (
    f"Shabbat Reminder -- {parasha or 'Shabbat Shalom'}\n\n"
    f"Candle lighting in 1 hour at {candles_local}.\n"
    f"Havdalah at {havdalah_local}.\n\n"
    f"Checklist:\n"
    f"- Lights\n"
    f"- Fridge (SabbathMode)\n"
    f"- Door\n"
    f"- Plata / hot water"
)

The reminder doesn't take any actions on the appliances. The schedulers already did that. It's a human-in-the-loop check that the things requiring human judgement (the door key, the lights I forgot to switch) actually got handled.

The orchestration layer

Everything is wired together with launchd plists:

kosher-lobster.openclaw.cron.shabbat-scheduler.plist fires every Friday morning
kosher-lobster.openclaw.cron.yomtov-scheduler.plist fires daily
kosher-lobster.openclaw.cron.shabbat-ac.plist and shabbat-sleep.plist handle the AC zones
kosher-lobster.openclaw.cron.shabbat-reminder.plist fires the Telegram message

The AC schedulers are weather-aware. They pull a forecast, checks against a temperature threshold, and only generates ON/OFF blocks if the forecast warrants it. The data model shows the shape:

tsinterface ShabbatPlan {
  parasha: string;
  candles: string;
  havdalah: string;
  forecast: {
    friday_high_f: number;
    saturday_high_f: number;
    threshold_f: number;
    extreme_heat?: boolean;
  };
  temp_c: number;
  temp_f: number;
  blocks: ShabbatBlock[];  // ON/OFF time blocks
  status: string;          // active | skipped | cancelled
}

A mild Friday in spring? No AC plan generated, no electricity wasted. A heat wave week? Blocks get pre-computed and queued. The scheduler decides; I don't wake up at 5 AM to think about it.

What I learned

The thing I underestimated going in was how much of OpenClaw's value comes from the boundary it draws between agent-driven work and deterministic work. I started by trying to make OpenClaw as the LLM "decide" when to flip the fridge. That was a bad idea. There's no room here for an agent reasoning incorrectly about a calendar edge case.

The right pattern was:

The scheduler scripts are deterministic, and committable to git
The skill SKILL.md files teach the agent how to query state when I ask
The agent never takes scheduled actions on its own; it answers questions and runs explicit commands

OpenClaw's skill structure made that separation easy to maintain because each skill is just a folder. The schedulers live alongside the skills they call, share the same Python environment, and don't require any agent loop to function. If I uninstalled OpenClaw tomorrow the cron jobs would keep firing and the fridge would keep going into Sabbath mode on time. That's the right resilience property for this kind of automation.

The other thing I learned is that the agent shines exactly where the schedulers can't help.

"Is the AC set for this evening?" is a Friday-afternoon question I used to answer by a lot of inquiry into the weather, figuring out what we needed in each room and more. Now I message OpenClaw on Telegram and get the AC schedule shared with me in two seconds.

The schedulers handle the recurring; the agent handles the one-off. Both of those are first-class in OpenClaw and that's why this works.

The lobster, against all expectations, has turned out to be the most observant member of the household. He never forgets the time. He never opens the fridge without checking. He has read more of the Jewish calendar API than any of us.

Quick tip: canonical URLs prevent silent SEO damage

Ben Greenberg — Fri, 03 Apr 2026 11:00:16 +0000

Quick tip on SEO:

If your site is accessible at both https://example.com and https://www.example.com, Google sees two different sites and splits your ranking signals between them.

Fix: add a canonical tag to every page:

<link rel="canonical" href="https://example.com/page" />

Check if yours is set correctly — the free audit tool at https://audit.hummusonrails.com/free checks canonical tags along with 4 other key issues.

Your backend code is a black box. It doesn't have to be.

Ben Greenberg — Wed, 01 Apr 2026 09:07:54 +0000

Your API takes inputs and returns outputs. The logic in between? Nobody outside your team can verify it. Regulators read documentation you wrote about it. Partners call your endpoint and trust the response. Users don't even get that.

This has worked for decades. But there's a growing category of backend logic where "trust us" isn't enough. Scoring algorithms, compliance checks, eligibility rules, validation pipelines. Anywhere someone needs to independently confirm that your code does what you say it does.

You don't have a code problem. You have a verifiability problem.

The case for publicly auditable code

Most backend engineers don't think about code auditability because most code doesn't need it. Your CRUD endpoints, your auth flows, your data transformations, those are internal concerns. Nobody outside your org needs to verify them.

But some functions carry weight. A scoring algorithm that determines loan eligibility. A validation pipeline that checks regulatory compliance. A pricing engine that partners depend on. For these functions, the standard answer is documentation: you write a spec, maybe you share pseudocode, and everyone agrees to trust that the running code matches the paper.

That's not verification. That's trust with extra steps.

Publicly auditable code means anyone can call the same function with the same inputs and confirm they get the same outputs. The logic is visible. Execution is deterministic. And the code can't change silently after deployment.

This isn't a new idea. Open source gives you code visibility. But open source doesn't prove that the code running in production is the same code in the repo. You need a runtime where the deployed code is the source of truth, and where every execution is independently reproducible.

That runtime exists. And you don't need to learn a new language to use it.

Rust in, verifiable execution out

When most engineers hear "deploy code onchain," they picture learning Solidity, memorizing gas optimization tricks, and rewriting working logic in an unfamiliar language. That's a reasonable reason to stop listening.

Arbitrum Stylus skips that detour. You write Rust, compile to WASM, and deploy it to a blockchain that's optimized for low-cost computation. Your existing toolchain, your existing crates, your existing mental model. The contract runs alongside Solidity smart contracts with shared state, but you never need to touch Solidity yourself.

This isn't about converting you to crypto. It's about giving you a deployment target where execution is publicly verifiable by default.

Three properties matter here:

Every execution is independently auditable. Anyone can call the contract with the same inputs and confirm they get the same outputs. No trust required.

The logic is immutable. Once deployed, the code can't change silently. If you push an update, that's a new deployment with its own address and its own history. No "we patched it last Tuesday but forgot to tell you."

Execution is deterministic. Same inputs, same outputs, every time, on every node. No environment-specific drift, no floating point surprises across hardware.

What the architecture looks like

I built a scoring engine to test this pattern. The architecture splits cleanly between what stays in your infrastructure and what moves onchain:

Your backend stays exactly where it is. An Axum API server handles business rules, authentication, request routing. Normal backend work. The only difference is that when the API needs a computation verified, it calls an onchain contract instead of a local function.

The onchain piece is a Stylus contract. It takes parameters, runs the calculation, and returns results. No state storage, just pure computation. Think of it as a function you deploy instead of host.

A shared Rust crate holds the type definitions and compiles for both environments. The contract uses no_std for WASM. The API server uses std for native. Same types, both sides. The compiler guarantees they match. No serialization mismatches, no type drift between your API and your contract.

One language across the entire stack. The chain boundary becomes a function call, not a language barrier.

The performance question

The first objection any backend engineer raises: what's the overhead?

Fair. Onchain computation has historically been expensive. That's the whole reason Solidity exists. It was designed to minimize execution cost on the EVM.

Stylus changes the math. WASM execution on Arbitrum is dramatically cheaper than EVM execution for compute-heavy workloads. The scoring engine used over 90% less gas than the equivalent Solidity contract doing identical work:

Environment	Score	Gas Usage
Offchain Rust	953	n/a
Onchain Stylus (WASM)	953	76,048
Onchain Solidity (EVM)	810	1,027,635

Storage operations cost the same either way, but iterative math, weighted calculations, and loop-heavy logic is where WASM pulls ahead.

This isn't a contrived benchmark. RedStone, an oracle provider, published similar results after porting their verification logic to Stylus. Compute-intensive work is where this architecture pays for itself.

Where auditable code matters

Not every function belongs onchain. But some backend logic sits in a category where "trust me" isn't good enough:

Scoring and risk calculations, where regulators want to audit the exact computation, not a description of it. Eligibility determinations, where partners want to verify outcomes independently instead of trusting your API response. Compliance validation, where auditors want proof that the logic running today is the same logic approved last quarter. Data pipelines, where counterparties want to confirm their data passed through agreed-upon rules.

If you've ever written documentation explaining how your algorithm works so someone else could trust it, that's the function that belongs onchain. Let them verify the code instead of reading your summary of the code.

The scoring engine I built is one example of this pattern. But the pattern is the point, not the example. Any pure function where independent verification adds value is a candidate.

What you'd actually do on a Monday morning

If you write Rust, the learning curve is smaller than you think.

Install cargo-stylus, which handles compilation and deployment. Write your function with #[entrypoint] and #[public] macros. Compile to WASM. Deploy to a testnet. Call it from your existing API using an RPC endpoint.

#[entrypoint]
#[storage]
pub struct ScoringEngine;

#[public]
impl ScoringEngine {
    pub fn score(&self, factors: Vec<Factor>, rules: Vec<Rule>) -> u32 {
        // Your computation logic here
        // Publicly verifiable, deterministic, immutable
    }
}

Your database, your auth, your business logic, none of that moves. You add one function that runs somewhere verifiable instead of somewhere trusted. Everything else stays the same.

The scoring engine repo has working code, setup instructions, and benchmarks comparing three execution paths: onchain Stylus, onchain Solidity, and offchain Rust. It's a concrete starting point, but the approach applies anywhere you need auditable computation.

You're adding a deployment target, not adopting a lifestyle

The shift is smaller than it sounds. The same way you might deploy a function to Lambda for serverless execution or to a TEE for confidential computing, you deploy to Arbitrum for verifiable execution.

Your Rust skills transfer directly. Your toolchain stays the same. The only thing that changes is who can verify your logic: everyone.

If you've been dismissing onchain as irrelevant to backend work, spend thirty minutes with the repo.

hummusonrails / stylus-scoring-engine

Verifiable credit/risk scoring engine: Stylus (Rust/WASM) vs Solidity on Arbitrum with three-way gas benchmark

Verifiable credit/risk scoring on Arbitrum with a three-way gas benchmark: offchain Rust vs onchain Stylus vs onchain Solidity.
Quick Start · Architecture · Report a Bug

What it does

Benchmarks the same scoring algorithm across three execution environments with real gas numbers
Scores entities against configurable weighted rules with iterative convergence and cross-factor correlation
Demonstrates Stylus gas savings on compute-heavy workloads (over 90% cheaper than Solidity)
Shares Rust types between the onchain contract and offchain API server from a single crate
Stores scoring rules in SQLite with full CRUD via REST endpoints

Quick Start

# clone and install
git clone https://github.com/hummusonrails/stylus-scoring-engine.git
cd stylus-scoring-engine
pnpm install

# start the local arbitrum devnode
pnpm devnode

# in a new terminal, deploy both contracts
pnpm deploy:all

# start the api server (reads .env written by deploy)
pnpm api

# in a new terminal, run the three-way benchmark
pnpm benchmark

Prerequisites

Rust 1.88+ with…

View on GitHub

The gap between "interesting in theory" and "I could actually use this" is shorter than you expect.

The readability scores your content tool is missing

Ben Greenberg — Tue, 31 Mar 2026 06:00:28 +0000

The Readability Scores Your Content Tool Is Missing

Most readability tooling stops at a single score. That is a problem if you are building a documentation pipeline, a content linter, or any system that needs to catch unreadable text before it ships.

Here are the four metrics worth tracking, what each one actually measures, and what your targets should be.

Flesch-Kincaid Grade Level

This score maps text to a U.S. school grade level based on two inputs: average sentence length and average word length in syllables. A score of 8 means a typical 13-year-old can read it without friction.

Target: 6 to 9 for most technical docs.

If your score is above 12, sentences are too long or you are leaning on polysyllabic jargon. Users will skim past dense paragraphs instead of reading them. If your score is below 5, you are likely oversimplifying to the point where context is missing.

Flesch Reading Ease

This uses the same inputs as FK Grade Level but outputs an inverse score on a 0 to 100 scale. Higher means easier. It weights sentence length more heavily than syllable count, so it punishes run-on sentences hard.

Target: 60 to 70 for technical documentation.

Below 50 and you are in academic or legal territory. Most readers will not finish the section. Above 75 and you may be losing precision, which matters in technical writing where exact phrasing carries meaning. The 60 to 70 range is the practical sweet spot where clarity and accuracy coexist.

Automated Readability Index (ARI)

ARI takes a different approach. Instead of counting syllables, it counts characters per word. This makes it faster to compute and less sensitive to syllabification edge cases. It outputs a grade-level score similar to FK but often diverges on technical content, where long words are common but not necessarily difficult for the target audience.

Target: 7 to 10 for developer docs.

Where ARI earns its place is as a cross-check. If FK says grade 8 but ARI says grade 14, you likely have a cluster of long technical terms inflating the character count. That is worth reviewing even if the content reads fine to a subject matter expert, because new users will not have that context.

Sentence Length Variance

Most tools report average sentence length and stop there. Variance is the signal they miss. Text where every sentence is roughly the same length reads as monotonous and is harder to parse. Alternating short and long sentences creates rhythm, which keeps readers oriented.

Target: Standard deviation of 8 to 15 words across your sentence lengths.

Below 5 means your writing is flat. Above 20 means sentence structure is inconsistent in a way that will confuse automated parsers and human readers alike. This is especially relevant in procedural docs where scannable short sentences should anchor longer explanatory ones.

I built a TextAnalytics API that returns all of these scores in a single call -- useful if you are building a linter, a CMS plugin, or just want to quality-gate your content pipeline: https://rapidapi.com/ben-eI6jno4PU/api/textanalytics

Quick tip: Flesch-Kincaid Grade Level 8 is your target

Ben Greenberg — Fri, 27 Mar 2026 11:00:05 +0000

Quick tip on writing docs and content:

Flesch-Kincaid Grade Level 8 = readable by a 13-year-old. That's your target for most technical documentation.

Not because your readers are 13 — but because shorter sentences and common words reduce cognitive load. Even senior engineers read faster at grade 8.

Most enterprise docs sit at grade 14-16. That's why people skim them.

The TextAnalytics API returns FK grade level (plus 4 other readability scores) in a single call: https://rapidapi.com/ben-eI6jno4PU/api/textanalytics

I built a link preview API — here's what I learned about Open Graph

Ben Greenberg — Tue, 24 Mar 2026 07:01:41 +0000

I Built a Link Preview API — Here's What I Learned About Open Graph

Link previews seem simple until you actually build something that generates them reliably. I spent weeks digging into how platforms parse Open Graph metadata, and I kept running into the same category of problems: missing images, wrong fallbacks, cached bad data. Here is what surprised me.

What Link Previews Actually Are (And Why They Break)

When you paste a URL into Slack or Twitter, the platform fetches that page, reads the <meta> tags in the <head>, and renders a card. The Open Graph protocol, originally developed by Facebook, defines the standard tags most platforms follow: og:title, og:description, og:image, and og:url.

The reason previews break so often comes down to a few recurring patterns:

The og:image tag is missing entirely
The image URL is relative instead of absolute
The image dimensions are wrong and the platform rejects it silently
The metadata exists but the page blocks crawlers with a bad robots.txt or a JavaScript render wall

That last one is brutal. If your content is rendered client-side and you have no SSR or prerendering, most crawlers will fetch an empty shell and your preview will be blank.

The og:image Requirements Most Devs Skip

I see this constantly. Developers add an og:image tag, the preview still looks broken, and they cannot figure out why. The requirements are stricter than the documentation implies:

Dimensions should be 1200x630 pixels. Facebook and LinkedIn will downscale, but if you go too small (under 200x200) they ignore the image completely.
File size should stay under 1MB. Larger images may time out during the crawl window.
The URL must be absolute. /images/preview.png will not work. https://yourdomain.com/images/preview.png will.
No SVGs. Almost no platform will render an SVG as a preview image. Use PNG or JPEG.

How Twitter Cards Differ From Open Graph

Twitter does read OG tags as a fallback, but it has its own system called Twitter Cards, and the twitter:card type changes how everything renders.

The two types you actually care about are summary and summary_large_image. If you use summary, Twitter shows a small thumbnail beside the text. If you use summary_large_image, you get the full-width banner image. Most developers want the large image but forget to set the tag, so they get the small thumbnail and wonder why it looks wrong compared to LinkedIn.

You also need twitter:title and twitter:description even if you already have the OG equivalents. Twitter will use OG as a fallback, but being explicit is more reliable.

The og:description Fallback Chain

When og:description is missing, platforms do not just leave it blank. The fallback chain typically goes:

og:description meta tag
Standard meta name="description" tag
First paragraph of visible body text

Knowing this means you can usually ensure something reasonable shows up even on pages that have not been fully optimized.

The One Gotcha That Bit Me Hard

If og:url does not match the canonical URL of the page, platforms will cache the preview against the wrong URL. I had a staging URL leak into production metadata once and spent an embarrassing amount of time wondering why the preview was showing old content. Always set og:url explicitly to the canonical version.

Parsing all of this reliably across different platforms, redirect chains, and malformed HTML is exactly the kind of work that sounds quick and turns into a week of edge cases. I use what I built in production at LinkPreview API. It handles the messy parts of parsing OG data so you do not have to: https://rapidapi.com/ben-eI6jno4PU/api/linkpreview1