DEV Community: Ben Greenberg

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

5 things your website is getting wrong (and how to check for free)

Ben Greenberg — Sun, 22 Mar 2026 21:51:15 +0000

Most websites fail basic technical hygiene checks. Not because developers don't care, but because these things are easy to miss when you're focused on shipping features. Here are five common issues worth fixing today.

1. Missing or Wrong Security Headers

Headers like Content-Security-Policy, X-Frame-Options, and Strict-Transport-Security (HSTS) protect your users from clickjacking, XSS attacks, and protocol downgrade attacks. Skipping them leaves real attack surface open. Browsers and security scanners will flag these absences, and some enterprise clients actively check before integrating with your API.

How to check: Run curl -I https://yourdomain.com and scan the response headers. Or paste your URL into securityheaders.com for a free graded report.

2. Open Graph Tags That Break Link Previews

When someone shares your link on Slack, LinkedIn, or Twitter, the platform reads your Open Graph meta tags to build the preview card. If og:title, og:image, or og:description are missing or misconfigured, the preview looks broken or empty. This tanks click-through rates on content you spent real time creating.

How to check: Use the OpenGraph.xyz previewer. Paste your URL and see exactly what Slack or LinkedIn will render. Fix any missing tags in your <head>.

3. No Canonical URL

If your page is reachable at both https://example.com/page and https://example.com/page?ref=newsletter, search engines may treat these as separate pages competing against each other. Over time this splits your ranking signals and can suppress both versions. A canonical tag tells crawlers which URL is the one that counts.

How to check: Open DevTools in Chrome, go to Elements, and search for canonical in the <head>. You should find something like <link rel="canonical" href="https://example.com/page" />. If it is missing or pointing to the wrong URL, fix it in your template.

4. Images Without Alt Text

Alt text is not optional. Screen readers rely on it for users with visual impairments, and search engine crawlers use it to understand image content. A page full of images with empty or missing alt attributes is both an accessibility failure and a missed SEO opportunity.

How to check: Run document.querySelectorAll('img:not([alt])') in the browser console. Any results mean you have untagged images. Axe DevTools (free browser extension) will also flag these automatically.

5. Missing Viewport Meta Tag

Without <meta name="viewport" content="width=device-width, initial-scale=1"> in your <head>, mobile browsers will render your page at desktop width and then scale it down. The result is a tiny, unreadable layout that frustrates users and tanks your Core Web Vitals scores.

How to check: Open DevTools, toggle the device toolbar (Ctrl+Shift+M), and load your page. If it renders like a shrunken desktop site, the viewport tag is probably missing. Check the Elements panel to confirm.

These five checks take maybe 15 minutes to run manually. If you want to do all of them in one go, I built a free tool that runs 5 key checks instantly, no signup, no waiting: https://audit.hummusonrails.com/free

Quick tip: your og:image should be 1200x630px

Ben Greenberg — Fri, 20 Mar 2026 12:00:10 +0000

Quick tip about link previews:

Your og:image should be 1200x630px. Most sites get this wrong — either wrong dimensions, an SVG (which many platforms reject), or a relative URL instead of absolute.

Check yours:

curl -s https://yoursite.com | grep 'og:image'

If you're building something that reads og:image from other sites, the LinkPreview API handles all the edge cases: https://rapidapi.com/ben-eI6jno4PU/api/linkpreview1

Quick tip: check your security headers with curl

Ben Greenberg — Wed, 18 Mar 2026 21:51:11 +0000

Quick tip for checking your security headers:

curl -I https://yoursite.com | grep -i 'x-frame\|content-security\|strict-transport\|x-content-type'

If you get no output, you're missing all of them. HSTS is the most important one to add first — it forces HTTPS on all future visits.

Want a full breakdown? Run a free check at https://audit.hummusonrails.com/free

I got tired of building the same link preview function, so I made it an API

Ben Greenberg — Sun, 15 Mar 2026 18:01:45 +0000

Every app I've built in the last few years has needed the same thing: paste a URL, show a preview card. Slack does it. Discord does it. Every CMS does it. And every time, I end up writing the same cheerio scraping code, handling the same edge cases with Open Graph tags, and debugging the same issue where Twitter Cards use name instead of property and half the internet gets it wrong.

A little while ago I finally extracted all of that into a standalone API and put it on RapidAPI. Figured other people are writing the same code too.

What it actually returns

You pass a URL. You get back structured metadata across six layers:

Open Graph (title, description, images with dimensions, article metadata)
Twitter Cards (card type, site, creator; only tags that are actually present, no fallback guessing)
HTML meta (title tag, meta description, canonical, theme color)
Icons (auto-selects the highest quality favicon with a priority chain)
Feeds (discovers RSS, Atom, and JSON Feed links)
JSON-LD (parses all script blocks, prefers Article/Product over BreadcrumbList)

The response gives you both a merged top-level view (where the title comes from whichever source has it; OG first, then Twitter, then the title tag) and the raw parsed layers, so you can do your own logic.

Here's what GitHub returns:

{
  "title": "GitHub · Build and ship software on a single, collaborative platform",
  "description": "Join the world's most widely adopted...",
  "image": {
    "url": "https://github.githubassets.com/images/modules/site/social-cards/campaign-social.png",
    "width": 1200,
    "height": 630
  },
  "favicon": "https://github.githubassets.com/favicons/favicon.svg",
  "siteName": "GitHub",
  "type": "website",
  "themeColor": "#1e2327",
  "openGraph": { ... },
  "twitter": { ... },
  "feeds": [],
  "jsonLd": { "@type": "WebSite", ... },
  "responseTime": 234
}

The parts that were annoying to get right

A few things I ran into while building this that I suspect anyone writing their own scraper will hit too:

OG tags use property, Twitter uses name. The Open Graph spec says <meta property="og:title">. Twitter Cards say <meta name="twitter:card">. But a surprising number of sites swap them. The parser checks both attributes for both prefixes.

Multiple og:image tags are valid. The OG spec supports arrays by repeating the tag. Structured properties like og:image:width apply to the most recently declared og:image. Most scrapers just grab the first one and ignore the rest.

JSON-LD blocks are a mess. A typical news article page has three or four JSON-LD blocks: a BreadcrumbList, an Organization, and then the actual Article buried in the third one. You need to parse all of them and pick the right one.

Favicons have a priority order. Apple touch icons at 180x180 are usually the highest quality. Then standard icons at 32x32, then the generic /favicon.ico fallback. Most implementations just grab the first <link rel="icon"> they find.

Relative URLs everywhere. OG images and feed links are often relative paths. You need the effective URL (after redirects) as the base to resolve them correctly.

The technical approach

It's a Fastify server running on a VPS, using cheerio for HTML parsing. No headless browser, no Puppeteer, just fetch the HTML and parse it. This keeps response times under 500ms for cache misses and under 5ms for cache hits.

SSRF protection was the part I spent the most time on. Since the API accepts arbitrary URLs from users, you need to prevent people from using it to probe internal networks. The server resolves the hostname first, checks the IP against a blocklist of private ranges, then connects directly to the resolved IP to prevent DNS rebinding attacks.

I also built a text analytics API while I was at it, using the same infrastructure but for a different purpose. Pass in text, get back readability scores (Flesch-Kincaid, Coleman-Liau, SMOG, and three others), keyword density, bigrams, trigrams, and reading time. All pure math on strings, sub-10ms responses. Useful for content optimization tools and writing assistants.

Try them

Both APIs are on RapidAPI with a free tier (500 requests/month):

LinkPreview — URL metadata extraction
TextAnalytics — readability scores, keyword density, text metrics

The free tier is enough to test and prototype with.

If you run into any edge cases the parser doesn't handle well, I'd genuinely like to know. Parsing the wild HTML of the internet is a forever project.