DEV Community: Alex Shev

Stop Testing APIs by Hand. Give Your AI Agent a Bruno Workflow.

Alex Shev — Wed, 29 Jul 2026 23:25:57 +0000

Most API testing workflows break in a boring way.

Not because the team does not care about testing.

Not because nobody knows how to send a request.

Because the API workflow lives in too many places at once.

One developer has a Postman collection.
Another has a few curl commands in shell history.
The backend repo has environment variables in .env.example.
CI has a smoke test that only checks one endpoint.
The docs say one thing.
The staging API behaves slightly differently.

Then an AI coding agent enters the repo and gets asked:

Can you check this API flow?

The agent can read code.
It can write tests.
It can generate curl commands.
It can explain HTTP status codes.

But it still has the same problem a new human has.

Where is the API workflow?

If the answer is "somewhere in a GUI tool, someone's local history, and a few scattered docs," the agent has to reconstruct the whole thing from scratch.

That is not a tool problem.

That is a workflow packaging problem.

API collections should live near the code

This is why I like Bruno.

Bruno is an open-source API client that stores collections as plain text files in your Git repository.

That detail matters more than the UI.

If your API collection lives next to the application code, it becomes part of the engineering system:

request changes show up in pull requests
environment files can be reviewed
auth flows can be documented as runnable requests
test assertions can live with the request that needs them
CI can run the same collection humans use locally
new team members can learn the API by running the collection

The collection is not a private artifact hidden in a synced workspace.

It is a repo artifact.

That changes what an AI agent can do with it.

The real unit is not a request

A single API request is easy.

The useful workflow is usually a sequence:

Login.
Save the token.
Create a resource.
Read it back.
Update it.
Verify the response shape.
Clean up or test the failure path.

When developers test this manually, they often remember the sequence in their head.

That works until the API changes.

It works until staging has different data.

It works until someone else needs to debug the same flow.

It works until an agent has to run it and cannot rely on tribal memory.

The important thing to encode is not:

Send a POST request.

It is:

This is the auth flow.
These variables move from one request to the next.
These assertions prove the contract still works.
This command runs the flow in CI.

That is where Bruno's file-based model becomes useful.

A .bru request can contain the request metadata, headers, body, scripts, and tests in a human-readable format.

An environment file can define baseUrl, test users, and secret placeholders.

Post-response scripts can save values for later requests.

The CLI can run the collection:

bru run --env staging

or a folder:

bru run auth/ --env dev

or output CI-friendly results:

bru run --env dev --output results.xml --format junit

That is a much better artifact for an agent than a vague instruction like:

Test the API.

What an AI agent should not improvise

I do not want an agent inventing an API testing workflow every time.

That is how you get impressive-looking activity and weak verification.

The agent might:

hit the happy path only
test against the wrong environment
forget auth state
use fake data that bypasses the real bug
skip assertions and only report that the request returned something
paste a curl command that nobody ever runs again

None of those failures look dramatic.

They look like work.

The agent says:

I tested the endpoint.

But the team has no durable artifact, no diff, no reusable flow, and no CI hook.

That is the wrong end state.

For API work, I want the agent to leave behind something the repo can keep.

A better Bruno workflow for agents

The workflow I would want from an AI coding agent looks like this.

1. Discover the API surface

The agent should inspect routes, controllers, OpenAPI specs if they exist, existing tests, and any current API docs.

The output should be a short map:

auth endpoints
core resources
destructive actions
environment assumptions
test data requirements
flows that need chained state

No collection changes yet.

First understand the shape.

2. Create a Git-friendly collection structure

The collection should mirror the API, not the agent's thought process.

For example:

api-collection/
  bruno.json
  environments/
    dev.bru
    staging.bru
  auth/
    login.bru
    refresh-token.bru
  users/
    list-users.bru
    get-user.bru
    create-user.bru
  orders/
    create-order.bru
    process-refund.bru

That structure is boring on purpose.

People can navigate it.

Agents can navigate it.

Reviewers can diff it.

3. Encode variables and secrets correctly

Environment files should carry normal config like:

baseUrl: http://localhost:3000
testEmail: test@example.com

Secrets should be marked as secrets and not committed as plain values.

This is one of the places where an agent needs a rule, not vibes.

If a tool can run requests, it can also leak credentials by accident.

So the workflow has to define where config lives, which values can be committed, and what must stay local or injected by CI.

4. Chain requests deliberately

Many real API tests are stateful.

Create user returns an ID.

Create order depends on the user.

Refund depends on the order.

The agent should not fake those IDs when it can capture them from the real response.

That is where post-response scripts are useful.

The point is not clever scripting.

The point is making the API flow executable instead of explanatory.

5. Put assertions next to the request

A request without assertions is only a smoke signal.

The agent should add tests for the contract that matters:

status code
required fields
expected types
auth behavior
error shape
permission boundaries
idempotency or retry behavior when relevant

The test should answer:

What would make this endpoint unsafe to ship?

Not:

Did the server return any JSON?

6. Add a CI command

The workflow is not done until there is a command the team can run again.

For example:

bru run --env staging

or:

bru run auth/ users/ --env ci --output results.xml --format junit

The exact command depends on the project.

But the artifact should be clear enough that a developer, CI job, or future agent can repeat the same check.

Where Terminal Skills fits

This is exactly the kind of workflow that belongs in a skill.

The Terminal Skills catalog has a bruno skill for AI agents:

Bruno on Terminal Skills

The useful part is not "the agent has heard of Bruno."

That is not enough.

The useful part is giving the agent an operating procedure:

use Bruno as a Git-first API testing tool
store collections as reviewable repo files
organize requests by API structure
use environment files for config
keep secrets out of committed values
write assertions in requests
chain state between calls intentionally
run collections through the Bruno CLI
treat the collection as living API documentation

Install for Codex:

npx terminal-skills install bruno --agent codex

Install for Gemini CLI:

npx terminal-skills install bruno --agent gemini

Install for Claude Code:

npx terminal-skills install bruno

The broader point is simple:

If an agent is going to touch your API workflow, do not ask it to improvise testing.

Give it a repeatable workflow it can follow, edit, run, and leave behind.

Why this matters for API teams

API testing is one of those areas where AI can create false confidence quickly.

An agent can generate a convincing explanation of an endpoint.

It can generate sample requests.

It can say the test passed.

But unless the workflow leaves a durable artifact, the value disappears after the chat.

The better outcome is:

the Bruno collection was updated
the change is visible in Git
the request has assertions
the environment is explicit
the command can run locally
CI can run it later
the next agent does not need to rediscover the flow

That is the difference between assistance and operational memory.

The agent did not just test the API.

It improved how the team tests the API.

My practical checklist

If I were reviewing an agent-generated Bruno workflow, I would ask:

Does the collection live in the repo?
Does the folder structure match the API shape?
Are environments separated cleanly?
Are secrets marked and excluded from committed values?
Do important requests include assertions?
Are auth tokens and IDs passed through real response state?
Can the collection run from the CLI?
Is there a CI-ready command?
Would a new teammate understand the API faster after reading and running it?

If the answer is yes, the agent left behind something useful.

If the answer is no, it probably just tested by hand with extra steps.

The broader lesson

AI agents are good at producing one-off work.

Engineering teams need repeatable work.

That is the gap skills are meant to close.

For API testing, the difference is especially visible.

Do you want the agent to send a request once?

Or do you want it to build the API workflow your team can keep using?

That is why Bruno is a good fit for Terminal Skills.

It turns API testing into files, diffs, commands, and checks.

And those are exactly the kinds of artifacts agents can use without asking everyone to trust a chat transcript.

Disclosure: AI assistance was used to draft and edit this article.

I fixed an unbounded audio queue in a live translation server before it could take the process down

Alex Shev — Wed, 15 Jul 2026 01:51:04 +0000

This is a submission for DEV's Summer Bug Smash: Clear the Lineup powered by Sentry.

Project Overview

The project is a live speech translation app.

A browser client captures microphone audio, converts it to 16 kHz PCM, and streams it to a NestJS server over Socket.IO. The server opens one WebSocket session to a local ML service, forwards the audio frames, and relays translated segments back to listeners.

The important part for this bug: audio starts arriving from the browser before the ML WebSocket is guaranteed to be open.

That is normal for realtime systems. The dangerous part was what happened when the ML service was unavailable, slow to handshake, or stuck behind a bad connection.

Bug Fix or Performance Improvement

The MlSession class buffered audio frames while waiting for the ML WebSocket to open:

sendAudio(pcm: Buffer) {
  if (this.closed) return;
  if (this.open) this.ws.send(pcm);
  else this.queue.push(pcm);
}

That looks harmless until you remember what the data is: raw PCM audio.

At 16 kHz, mono, 16-bit PCM, the stream is roughly 32 KB per second per active speaker. If the ML WebSocket never opens, every audio event keeps appending another Buffer to queue. A stalled ML service could quietly turn one active audio source into an unbounded memory growth path.

The server did not have to be under heavy traffic for this to matter. One broadcaster with a stuck ML backend was enough to create an ever-growing in-memory queue.

Code

I added an explicit cap for queued audio before the ML connection opens, tracked queued bytes, reset the counter once the connection opens, and released queued buffers on close/error.

const MAX_QUEUED_AUDIO_BYTES = Number(
  process.env.ML_MAX_QUEUED_AUDIO_BYTES || 512 * 1024,
);

The send path now fails fast instead of buffering forever:

sendAudio(pcm: Buffer) {
  if (this.closed) return;
  if (this.open) this.ws.send(pcm);
  else {
    if (this.queuedBytes + pcm.byteLength > MAX_QUEUED_AUDIO_BYTES) {
      this.finish(new Error("ML websocket audio queue overflow before connection opened"));
      try {
        this.ws.close();
      } catch {}
      return;
    }
    this.queue.push(pcm);
    this.queuedBytes += pcm.byteLength;
  }
}

When the socket opens, queued audio is flushed and the byte counter goes back to zero:

this.ws.on("open", () => {
  this.ws.send(JSON.stringify({ type: "config", ...config }));
  this.open = true;
  for (const buf of this.queue) this.ws.send(buf);
  this.queue = [];
  this.queuedBytes = 0;
});

Close/error paths also clear the queue:

close() {
  this.closed = true;
  this.queue = [];
  this.queuedBytes = 0;
  try {
    this.ws.close();
  } catch {}
}

private finish(err?: Error) {
  if (this.closed) return;
  this.closed = true;
  this.queue = [];
  this.queuedBytes = 0;
  this.onClose(err);
}

My Improvements

The fix changes the failure mode.

Before:

ML service unavailable or stuck
browser keeps streaming audio
server queues every PCM frame
memory grows until the process is restarted or killed

After:

ML service unavailable or stuck
server accepts only a bounded amount of pending audio
session closes with a specific overflow error
existing gateway cleanup runs and listeners get the normal ended signal
memory is released immediately

I kept the default cap at 512 KB, which is around 16 seconds of 16 kHz mono PCM audio. That is enough for normal connection delay but small enough to prevent a single stalled session from becoming a memory leak.

The value is configurable:

ML_MAX_QUEUED_AUDIO_BYTES=1048576

That lets production tune the buffer based on expected network conditions without changing code.

Verification

The normal server build still passes:

npm run build

Output:

> live-translation-server@0.1.0 build
> tsc -p tsconfig.json

I also ran a smoke test that accepts the TCP connection but intentionally never completes the WebSocket handshake. Then I sent audio chunks into MlSession with a small queue limit.

Expected result: the session should close with the overflow error instead of keeping the buffers forever.

Observed result:

{"closed":true,"errMessage":"ML websocket audio queue overflow before connection opened"}

That is the behavior I wanted: when the ML backend is not actually ready to receive audio, the realtime server fails the session explicitly instead of becoming a quiet memory sink.

What I learned

Realtime systems make small buffers feel safe.

This was not a dramatic bug in the happy path. The app worked when the ML WebSocket opened quickly. The bug lived in the waiting room between "the browser is already sending audio" and "the ML service is ready."

That is exactly where production bugs like to hide: not in the main algorithm, but in the glue code that assumes the next component will be ready soon.

The fix was not a bigger abstraction. It was a boundary:

audio may wait briefly, but it may not wait forever.

That one rule turns an unbounded failure into a controlled one.

Your AI App Does Not Need Ten Model Clients. It Needs a Gateway Workflow.

Alex Shev — Tue, 14 Jul 2026 23:44:12 +0000

Most AI apps start with one provider.

That is usually fine.

You add an OpenAI SDK call, pick a model, ship the feature, and move on.

Then the product grows.

One workflow needs a cheaper model. Another needs a stronger reasoning model. Another needs image or video generation. A customer wants data routed through a specific provider. A fallback model becomes necessary because the primary one is rate-limited during a launch.

Suddenly, "just call the model" is not really the architecture anymore.

The real problem is routing.

The trap: provider logic spread across the app

The messy version looks like this:

if (task.type === "support_summary") {
  return openai.chat.completions.create(...)
}

if (task.type === "deep_research") {
  return anthropic.messages.create(...)
}

if (task.type === "image") {
  return imageProvider.generate(...)
}

That works for a while.

But as soon as the team needs fallbacks, model swaps, cost controls, or media endpoints, provider decisions start leaking into product code.

Now the app has two problems:

product logic
model routing logic

Those should not be the same layer.

A gateway is boring in the best way

This is why I like the routerbase-gateway pattern on Terminal Skills.

The useful idea is not "one more AI provider."

The useful idea is putting OpenAI-compatible calls, model IDs, fallback choices, streaming behavior, tool calling, JSON mode, and media generation behind one gateway layer.

Instead of teaching every part of the app how to talk to every model provider, the application talks to one interface.

The routing layer decides what happens behind it.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ROUTERBASE_API_KEY,
  baseURL: "https://api.routerbase.com/v1",
});

const result = await client.chat.completions.create({
  model: "fast-support-summary",
  messages: [
    { role: "system", content: "Summarize the customer issue clearly." },
    { role: "user", content: transcript },
  ],
});

The application code stays boring.

The routing policy can change without rewriting every feature.

Why this matters for agents

An AI coding agent can wire up raw API calls.

That is not the hard part.

The hard part is getting the agent to make the same architectural decision the team would make:

keep provider-specific logic out of product code
use environment variables consistently
keep model names configurable
support fallbacks without scattering conditionals everywhere
preserve streaming and JSON-mode behavior where the feature needs it
avoid logging sensitive prompts or keys

That is exactly the kind of workflow that belongs in a skill.

Not because the commands are complicated.

Because the judgment should be repeatable.

The skill version of the task

Without a skill, the prompt tends to be vague:

Migrate this app to use RouterBase.

That leaves too many decisions open.

With a workflow-oriented skill, the agent has a narrower job:

npx terminal-skills install routerbase-gateway --agent codex

Then the agent can follow a safer pattern:

Find existing OpenAI-compatible client calls.
Move provider configuration into environment variables.
Replace direct provider clients with the gateway base URL.
Keep model IDs outside hard-coded feature logic where possible.
Preserve streaming, tool calling, and structured-output behavior.
Add a small verification path before claiming the migration worked.

That is much closer to production work than "switch the API key."

The real win is change management

Model routing is not just an infra preference.

It changes how product teams can operate.

When the routing layer is explicit, the team can:

test cheaper models on low-risk tasks
keep stronger models for high-value workflows
add a fallback route for outages
move media generation behind the same operational pattern
compare providers without rewriting the feature
keep provider churn away from product code

The application becomes less attached to one vendor.

The team becomes more explicit about which model is used for which job.

This is where skills are useful

Most teams do not need an agent that merely knows a gateway exists.

They need an agent that knows how to migrate safely:

inspect the codebase first
identify provider-specific assumptions
make the smallest useful change
avoid leaking secrets
preserve existing behavior
verify the path after the edit

That is the difference between a tool and a workflow.

The tool is the gateway.

The workflow is how you introduce it without making the codebase harder to reason about.

Source workflow:

https://terminalskills.io/use-cases/route-ai-model-requests-through-routerbase

The short version:

If your AI app is starting to juggle providers, models, fallbacks, and media endpoints, do not scatter that logic through the product.

Put it behind a gateway.

Then teach the agent the migration workflow.

Your AI Coding Agent Does Not Need a Refactor Prompt. It Needs an Architecture Workflow.

Alex Shev — Sat, 11 Jul 2026 17:30:59 +0000

Most AI refactoring advice starts in the wrong place.

It assumes the hard part is telling the model what to change.

So the prompt gets longer:

Act as a senior architect.
Review this codebase.
Find refactoring opportunities.
Improve maintainability.
Make it more testable.

That sounds reasonable.

But in a real repo, that prompt is too vague to be useful.

The hard part is not asking for better architecture.

The hard part is finding the parts of the codebase where architecture is actually hurting the work.

Not every ugly file needs a refactor.
Not every repeated function needs extraction.
Not every small module is a good module.
Not every "clean" interface hides useful complexity.

Sometimes the code that looks messy is doing the real work.
Sometimes the code that looks clean is only clean because the complexity was pushed into every caller.

That is the part an AI coding agent needs help with.

It needs an architecture workflow.

The problem with generic refactoring agents

When I let an agent inspect a codebase with only a broad refactor instruction, it tends to do one of three things.

First, it finds obvious style issues.

Naming.
Duplication.
Large files.
Missing comments.
Inconsistent patterns.

Those can matter, but they are rarely the architectural bottleneck.

Second, it proposes interface extraction too early.

The agent sees coupling, so it creates a service.
It sees repeated logic, so it creates a helper.
It sees conditionals, so it creates strategies.

The code looks more "designed" afterward, but the system may become harder to understand because the same concept is now split across more files.

Third, it treats testability as an extraction problem.

If something is hard to test, the agent may pull small pure functions out of the flow until the tests become easy.

That can make unit tests pleasant while hiding the real bugs in orchestration, boundaries, state, and integration behavior.

The result is a codebase with more files, more seams, more mock points, and not necessarily better architecture.

I do not want an agent to refactor like that.

I want the agent to slow down and ask a better question:

Where did understanding this system become expensive?

Architectural friction is a better signal than file size

A useful architecture pass should start by exploring the codebase the way a new senior engineer would.

Not by counting lines.
Not by ranking files by complexity score.
Not by searching for "TODO".

By following concepts.

For example:

Where does one business concept require bouncing through five shallow modules?
Where is the public interface almost as complicated as the implementation?
Where do callers need to know too much about internal sequencing?
Where are tests mostly checking implementation details?
Where do changes require touching several files that should probably move together?
Where does the agent keep losing the thread while trying to understand one behavior?

That last one is underrated.

If an agent gets lost while navigating the repo, that is not only a model limitation.

It may be an architecture signal.

Humans feel this too. We just describe it differently:

Every change here takes longer than it should.

or:

You have to know too much context before touching this module.

or:

The tests pass, but I do not trust this area.

That is the layer worth investigating.

The deep module idea maps surprisingly well to agents

John Ousterhout's deep module idea is still one of the best ways to think about this.

A deep module has a small interface that hides meaningful complexity.

That matters for humans because a good interface reduces the amount of system knowledge a developer needs to hold in their head.

It matters for AI agents for the same reason.

Agents are good at following local instructions.

They are worse when every small change requires reconstructing a hidden social map of the repo:

This helper is called here.
But only after this validation.
Unless this flag is set.
And this type is technically shared.
But this caller mutates it.
And the test mock does not match production behavior.

When the implementation is scattered but the concept is unified, the agent has to infer the module boundary every time.

That is waste.

Good architecture gives both humans and agents a smaller surface to reason about.

The goal is not fewer files.

The goal is better boundaries.

A better workflow for agent-assisted architecture review

The workflow I prefer has seven stages.

1. Explore before proposing

The agent should walk the codebase and record friction.

No refactor proposals yet.
No new interfaces yet.
No patches yet.

Just exploration.

The output should be a list of architectural friction points, not a list of code smells.

For each candidate, I want:

the module or concept cluster involved
why those files are coupled
what state or behavior is spread across them
what tests are hard to write or trust
what kind of change becomes expensive there

This is the step most refactor prompts skip.

2. Present candidates, not solutions

The agent should show the candidates and ask which one to explore.

That sounds small, but it prevents a common failure mode:

The agent picks an area that looks bad but is not important.

Architecture work should follow business and maintenance pressure.

If an area is ugly but stable, it may not be the next refactor.

If an area changes every week and every change creates review anxiety, that is a better target.

3. Frame the problem space

Before designing anything, the agent should describe the constraints.

For example:

This cluster handles customer eligibility.
It currently depends on plan state, billing status, account flags, and region rules.
The callers mostly need one decision: can this customer use this feature?
The current implementation exposes too many intermediate checks.

This framing is useful because it separates the problem from the proposed interface.

The team can disagree with the framing before arguing about code.

4. Generate multiple interface designs

One proposal is not enough.

Architecture design benefits from contrast.

I like asking separate agents, or separate passes, to design different interfaces:

one minimal interface
one flexible interface
one optimized for the most common caller
one ports-and-adapters version if external dependencies are involved

The point is not to blindly choose the most elegant design.

The point is to expose trade-offs.

5. Compare the designs in prose

This is where the main agent should be opinionated.

Not:

Here are three options. Which do you prefer?

Better:

Option A is easiest to adopt but leaks dependency order.
Option B hides the right complexity but may be too abstract for current callers.
Option C is the strongest default because most callers only need one decision.
I would use C, with the error reporting shape from B.

That is the kind of help I actually want from an agent.

6. Turn the decision into an RFC

Once the direction is chosen, do not jump straight to a giant PR.

Create a refactor RFC issue.

It should include:

the current friction
the chosen boundary
the interface sketch
migration plan
test strategy
risks
what not to change yet

This gives the team a reviewable architecture artifact before implementation begins.

7. Only then edit code

The implementation should be the last step, not the first.

If the agent starts by editing, it will often optimize the local patch instead of the architecture.

The workflow has to force the design conversation first.

Where Terminal Skills fits

This is the kind of workflow that belongs in a skill, not in a one-off prompt.

The Terminal Skills catalog has an improve-codebase-architecture skill that packages this exact style of process:

Improve Codebase Architecture on Terminal Skills

It is not a magic refactoring button.

That is the point.

It teaches the agent to:

explore the codebase organically
treat navigation friction as a signal
identify shallow modules and coupling clusters
present candidates before proposing interfaces
design multiple alternative boundaries
compare trade-offs
create a GitHub issue RFC instead of silently rewriting the system

Install command for Codex:

npx terminal-skills install improve-codebase-architecture --agent codex

For Claude Code:

npx terminal-skills install improve-codebase-architecture

The native ad here is simple:

If your agent keeps making refactors that look clean but do not make the codebase easier to change, do not give it a bigger prompt.

Give it a repeatable architecture workflow.

Why this matters more now

Agent skills are becoming a serious part of terminal-agent work.

The ecosystem is moving in the same direction: reusable procedures are becoming a way to encode what to accomplish, when to apply it, and how to execute terminal tasks. The uncomfortable side is that skill retrieval, skill quality, and reusable automation can become fragile if the procedure is vague or unsafe.

That matches what I see in practice.

Skills are powerful when they are specific, procedural, and verifiable.

They are weak when they are just long advice files.

An architecture skill is a good test case because it cannot succeed by memorizing commands.

It has to guide judgment.

It has to slow the agent down.

It has to preserve human decision points.

It has to make the final artifact reviewable.

That is what separates an agent workflow from an agent vibe.

My practical checklist

If I were evaluating an architecture skill for a coding agent, I would ask:

Does it force exploration before edits?
Does it identify concept clusters, not just files?
Does it distinguish coupling from duplication?
Does it ask for human selection before deep design?
Does it generate multiple interface options?
Does it compare trade-offs in plain language?
Does it produce an RFC before implementation?
Does it define what should not be changed?
Does it improve test boundaries instead of just adding mocks?

If the answer is no, it is probably not an architecture workflow.

It is just a refactor prompt wearing a better title.

The broader lesson

AI agents are getting better at writing code.

That makes architecture more important, not less.

When the agent can produce a thousand-line refactor in minutes, the bottleneck shifts from typing to judgment:

Was this the right boundary?
Did we hide the right complexity?
Did we make future changes easier?
Can the team review the decision?
Can the agent explain why it chose this shape?

Those questions do not belong at the end of the PR.

They belong in the workflow.

That is why I think the next useful layer for AI coding agents is not more autonomous editing.

It is better operating procedures.

Skills are one way to package those procedures.

And architecture review is one of the places where that packaging starts to matter.

Disclosure: AI assistance was used to draft and edit this article.

The Local SEO Report Should Be an Agent Run, Not a Dashboard Screenshot

Alex Shev — Fri, 03 Jul 2026 16:21:25 +0000

Every local SEO agency has some version of the Monday reporting ritual.

Someone opens a spreadsheet.

Someone opens Google Business Profiles.

Someone checks rankings for a few money keywords.

Someone looks at reviews.

Someone peeks at competitors.

Then the team turns all of that into a client-friendly update that says what changed, what matters, and what needs approval.

The work is valuable.

The ritual is awful.

It is repetitive, stateful, and full of tiny judgment calls:

did the business drop out of the map pack?
did a negative review arrive over the weekend?
does the reply need owner approval?
did a nearby competitor suddenly gain reviews?
is this a real issue, or just noise?
should the client act this week, or just keep watching?

That is exactly the kind of workflow where I do not want an AI agent to "write an SEO report" from scratch.

I want the agent to run the operating loop.

The dashboard is not the workflow

Dashboards are useful for humans.

They are less useful as the primary interface for agents.

A dashboard usually answers:

What can I see if I click around?

An agent workflow needs a different interface:

What state exists?
What changed?
What should be checked next?
What requires approval?
What should never be done automatically?

That difference matters.

Local SEO reporting is not just data extraction. It is a recurring workflow with memory:

businesses already onboarded
keywords already tracked
ranking history over time
reviews already answered or still pending
competitors already on a watchlist
locations that need neighborhood-specific checks
client-specific rules around tone, compliance, and approval

If the agent only gets a screenshot or CSV export, it has to infer too much.

If the agent gets a structured tool layer, it can operate much closer to the real job.

That is why the SEOG skill on Terminal Skills is interesting to me.

It turns local SEO monitoring into a terminal-native MCP workflow instead of another browser tab to babysit.

Source skill: SEOG on Terminal Skills

Use case: Automate Local SEO Monitoring for Client Businesses

What the skill actually gives the agent

The SEOG skill connects an AI coding agent to the SEOG MCP server.

The platform is built around local businesses that live or die on Google Maps visibility: Google Business Profile data, map-pack rankings, reviews, and nearby competitors.

The MCP server exposes those operations as tools.

That is the important part.

Instead of asking the agent to scrape pages or reason from a dashboard screenshot, the agent can call tools for the core entities in the workflow:

businesses
keywords and rankings
Google reviews
competitors

The skill describes a streamable HTTP MCP endpoint:

claude mcp add --transport http seog https://api.seog.ai/mcp \
  --header "Authorization: Bearer <your-seog-mcp-token>"

After that, the agent can work through a structured local SEO loop:

list_businesses
check_keyword
keyword_history
sync_reviews
list_reviews
draft_review_response
discover_competitors
snapshot_competitor

That is a much better contract than:

Open my dashboard and tell me how things look.

The useful report is an impact queue

A weak AI-generated SEO report sounds like this:

Your local visibility is important. Reviews matter. Keep optimizing your profile.

Technically true.

Completely useless.

A useful local SEO report is closer to an impact queue:

1. You dropped from #2 to #5 for "emergency dentist near me" in Hyde Park.
2. Two new negative reviews need owner-approved replies.
3. A competitor within 1km added 43 reviews this month.
4. Your service page still does not match the GBP category you are trying to rank for.

That is the reporting shape agencies actually need.

The agent should not just summarize.

It should triage.

The Terminal Skills use case frames this well: the agent checks rankings, syncs reviews, snapshots watched competitors, and writes a weekly digest with movement, unanswered negative reviews, drafted replies, and competitor alerts.

The detail I like most is prioritization.

A client dropping out of the 3-pack for a money keyword matters more than a 4-star review that has not been answered yet.

That sounds obvious to an operator.

It is not obvious to a generic writing model unless the workflow teaches it.

Location context is not optional

One trap in local SEO reporting is pretending that rankings are a single global number.

They are not.

For local businesses, the search location changes the answer.

Checking from the agency office is often the wrong measurement.

A coffee shop, dentist, med spa, or plumber may care about one neighborhood more than another. The useful question is not only:

Where do we rank?

It is:

Where do we rank from the places customers actually search?

That is why I like seeing locationLabel and coordinates as part of the keyword tracking flow.

The agent can track a keyword from "Hyde Park" and "South Congress" instead of flattening the whole city into one report.

That makes the weekly digest more honest.

It also changes the recommendations.

A business might be fine near its physical address but weak in the service area it wants to expand into. That is a different action item than "rankings are down."

Review replies should be draft-first

This is the line I would not cross with automation:

An agent can draft review replies.

It should not silently publish them.

The SEOG skill makes that boundary explicit: draft_review_response saves a draft, but the owner approves in-app.

That is the right design.

Review replies are public. They touch customer trust. In medical, legal, home services, and other sensitive categories, a careless reply can create real problems.

For regulated businesses, even a friendly response can go wrong if it confirms that someone was a customer or patient.

So the automation boundary should look like this:

Agent:
- finds reviews that need attention
- groups negative or risky reviews first
- drafts safe replies
- explains why each reply needs review

Human:
- approves
- edits
- publishes

That is not a limitation.

That is the workflow becoming safer.

Good agent systems are not the ones that automate every click.

They are the ones that know which clicks require approval.

Competitor monitoring is where the report gets interesting

Most agencies already track their own client.

The better reports also watch the local battlefield.

If a nearby competitor suddenly gains review velocity, changes categories, adds services, or starts outranking the client for a money keyword, the client should hear about it before they notice it themselves.

The SEOG workflow includes competitor discovery and snapshots:

discover_competitors
add_competitor
set_competitor_watchlist
snapshot_competitor

That gives the agent a useful job:

Do not tell me everything.
Tell me what changed around this business.

That is the difference between reporting and monitoring.

Reporting describes what happened.

Monitoring notices what is starting to happen.

For local SEO, that can be the difference between:

Your rankings dropped last month.

and:

The competitor two blocks away is about to pass your review count. Start a compliant review request push now.

The second one is much more valuable.

The agent still needs guardrails

This kind of workflow is also a good reminder that MCP tools are not enough by themselves.

The skill has to teach operational boundaries.

For example:

deleting a business is irreversible and should require confirmation
live rank checks consume quota and should not run in tight loops
review replies are drafts, not published responses
API tokens are credentials and should never be logged or committed
a 401 probably means the token was revoked and needs reissue

Those details are not decoration.

They are the difference between a useful agent and a risky one.

A generic model can understand "local SEO reporting."

A skill can tell it:

Do not delete this portfolio by accident.
Do not burn quota in a loop.
Do not claim a review reply was published.
Do not leak the token.

That is exactly why I keep coming back to skills as the right abstraction for agent work.

Prompts describe intent.

Skills describe operating procedure.

A weekly agency run should look boring

The best version of this workflow is not flashy.

It is a scheduled run.

Every Monday morning:

For each client:
1. sync the business state
2. check active keywords by tracked location
3. compare rank movement against the last 7 days
4. sync reviews
5. draft replies for negative or unanswered reviews
6. snapshot watchlisted competitors
7. produce an impact-ranked digest
8. stop before anything public is published

That is boring in the best way.

It gives the agency leverage without turning the account into an autopilot risk.

The human still owns strategy, client communication, and approvals.

The agent owns the repetitive monitoring loop.

That is the split I trust.

The bigger lesson

I do not think the future of local SEO work is "AI writes reports."

That is too shallow.

The more useful shift is:

AI agents run recurring evidence-gathering workflows,
then hand humans a prioritized approval queue.

For a local SEO agency, that queue might be:

rankings that moved
reviews that need attention
competitors that changed
pages that need technical cleanup
schema gaps
business facts that no longer match across the web

The report becomes a byproduct of the operating loop.

That is the part worth building.

If an agent can run the same checks every week, preserve state, respect approval boundaries, and explain what changed, it is no longer just generating content.

It is doing operational work.

And that is where agent skills start to feel less like prompt engineering and more like actual software.

The Blender Skill That Makes AI Agents Prove the Render Exists

Alex Shev — Tue, 30 Jun 2026 21:36:15 +0000

Most AI + Blender demos stop one step too early.

The agent writes a script.

The script looks plausible.

The explanation sounds confident.

But the real question is much simpler:

Did Blender actually render the thing?

That is the line between a demo and a workflow.

If an AI agent is helping with 3D production, the output cannot just be a paragraph of advice or a Python snippet that might work. At some point, the agent has to cross into the production layer:

configure the render engine
set resolution and file format
create or aim the camera
set up lights
apply materials
render a frame or sequence
verify that the output file exists
return something the human can inspect

That is why I like the idea behind the blender-render-automation skill on Terminal Skills.

It is not trying to make Blender “magic.”

It is trying to make Blender boring enough for an agent to operate.

And boring is where real automation starts.

The problem with AI-generated Blender scripts

Blender has a powerful Python API.

That makes it tempting to treat Blender automation as a code-generation problem:

Ask the agent for a bpy script.
Paste it into Blender.
Hope it works.

Sometimes it does.

Sometimes the script uses the wrong render engine name.

Sometimes the camera points nowhere useful.

Sometimes the material code assumes a node that is not there.

Sometimes the render settings are incomplete.

Sometimes the agent says “done” even though no image was written to disk.

The annoying part is that these failures are not always dramatic. They are small production misses. The script almost works. The scene almost renders. The output almost matches what you asked for.

But “almost” is expensive in 3D work.

If you are creating product shots, thumbnails, animation previews, turntables, or review renders, the workflow needs a stronger contract than:

Here is some code you can try.

It needs:

Here is the render output. Here is the path. Here is what was configured. Here is what still needs review.

A render skill is a definition of done

The useful thing about a Blender render skill is not only that it knows bpy.

The useful thing is that it teaches the agent what “done” means.

For a render workflow, “done” should not mean:

the agent wrote a plausible answer
the agent described Cycles vs EEVEE
the agent generated a script and stopped

It should mean:

Blender was run headlessly or through a known script path
the render engine was explicitly configured
output resolution and format were set
cameras and lights were created or selected
materials were applied with clear names
a still frame or animation sequence was rendered
the expected file appeared at the expected path

That is a much better interface for AI agents.

It turns the task from “make a nice Blender thing” into a workflow with observable artifacts.

Why headless Blender matters

Blender is a visual tool, but it can also run from the command line.

That changes what an agent can do.

Instead of manually clicking through the UI, the agent can operate through a repeatable loop:

blender scene.blend --background --render-output /tmp/frame_ --render-frame 1

or:

blender scene.blend --background --frame-start 1 --frame-end 100 --render-anim

That loop is important because agents are much better when they can run something, inspect the result, and continue.

A GUI-only workflow often leaves the agent guessing.

A terminal workflow gives it evidence.

The agent can check:

did the command exit successfully?
did the PNG sequence appear?
did the MP4 get created?
did the output directory contain the expected frames?
did the render crash halfway through?

Those checks are not glamorous.

They are exactly what make automation useful.

Cycles, EEVEE, and choosing the right failure mode

The blender-render-automation skill also points at an important production distinction: not every render needs the same engine.

Cycles is physically accurate and better for final quality.

EEVEE is fast and better for previews.

That sounds obvious, but it matters for agents.

If an agent always chooses the slowest path, it wastes time.

If it always chooses the fastest path, it may return a preview that is not good enough for review.

A good render workflow should make that choice explicit:

use EEVEE for fast preview and layout checks
use Cycles for final stills or higher-quality review frames
enable denoising when samples are low
use GPU rendering when the environment supports it
avoid pretending a preview render is a final render

That kind of operational judgment is exactly what belongs in a skill.

The model can still reason about the task.

But the workflow gives it defaults that are safer than fresh improvisation every time.

Cameras and lights are not decoration

A lot of failed AI-Blender attempts are not really modeling failures.

They are camera and lighting failures.

The object exists.

The scene exists.

But the camera misses the subject, the focal length is wrong, the light is too weak, or the result is technically rendered but useless.

A render automation skill can push the agent to treat cameras and lights as part of the deliverable:

create a camera at a known location
aim it at the subject
use a reasonable focal length
add area lights or environment lighting
name cameras clearly
batch render multiple camera views when needed

This is especially useful for product work.

One render is rarely enough.

A human reviewer may need a hero angle, front view, side view, top view, and a transparent-background version.

That should not require five separate improvisations.

It should be a repeatable operation.

Render animations as image sequences first

One of the best small rules in render automation is:

Render animations as image sequences before assembling video.

That sounds like old-school pipeline advice because it is.

It is also exactly the kind of rule AI agents need.

If a direct video render fails at frame 87, you may lose the whole output or have a painful recovery path.

If an image sequence fails at frame 87, frames 1-86 still exist.

The agent can inspect what completed, rerun the missing range, and then assemble the sequence with FFmpeg.

That is a production workflow.

It is not just a Blender trick.

It is a reliability pattern:

Prefer recoverable intermediate artifacts over one fragile final artifact.

That pattern applies far beyond Blender.

But Blender makes it very visible.

Materials need conventions, not vibes

When a human says “make it premium,” an agent can generate endless material ideas.

That is not always helpful.

Production scenes need conventions:

named materials
predictable PBR settings
sane roughness and metallic values
glass separated from plastic and metal
transparent-background settings when needed
output formats chosen for the downstream use case

A render skill does not remove taste from the process.

It keeps the mechanical layer consistent so the human can spend attention on the creative layer.

That is the right division of labor.

The agent handles setup, naming, rendering, and verification.

The human judges whether the result is good.

The real product is the workflow boundary

When people talk about AI agents and creative tools, the conversation often jumps to autonomy.

Can the agent make a complete scene by itself?

Can it replace a 3D artist?

Can it generate a finished animation from one sentence?

I think that is the wrong starting point.

The more useful question is:

Can the agent own a narrow, repeatable production step?

For Blender rendering, that step might be:

set up a studio render scene
render a transparent PNG
create a 36-frame turntable
generate a contact sheet from multiple cameras
render an animation sequence
produce preview and final variants

That is a realistic agent workflow.

It does not need to replace the artist.

It needs to remove the repetitive setup work around the artist.

Why this matters for agent skills

The bigger lesson is not only about Blender.

It is about how we package work for AI agents.

A model can know a lot and still fail at the last mile.

Skills help close that gap by giving the agent:

a trigger for when the workflow applies
operational steps
command patterns
quality checks
failure modes
a definition of done

That is why I keep coming back to Terminal Skills as a useful layer.

It treats skills less like prompt decorations and more like small workflow contracts.

For Blender, that contract is easy to understand:

Do not just describe the render. Produce it, verify it, and tell me where it is.

That is the part agents need.

Not more confidence.

More proof.

The skill I am talking about is blender-render-automation on Terminal Skills:

https://terminalskills.io/skills/blender-render-automation

If you are experimenting with AI agents and Blender, I would start with one narrow workflow:

Create a clean product scene, render one preview, verify the image exists, and return the output path.

That is not flashy.

But it is the right kind of boring.

And once that works, you can build a real pipeline on top of it.

ComfyUI Is Becoming the Workflow Layer for AI Image Agents

Alex Shev — Sat, 27 Jun 2026 17:46:10 +0000

Most image generation tutorials still treat ComfyUI like a visual playground.

Open the UI.
Drag a few nodes together.
Load a checkpoint.
Generate an image.

That is useful, but it undersells why ComfyUI keeps mattering.

The more interesting shift is this:

ComfyUI is not just a UI for image generation anymore. It is becoming a workflow layer.

That matters a lot for AI agents.

An agent does not only need to write a prompt. It needs to run a repeatable process:

choose the right model
place files in the right folders
load the workflow
queue the job
wait for completion
retrieve the output
verify that the output exists
adapt the graph for the next run

A plain prompt does not give you that.

A graph does.

Why the graph matters

The big advantage of ComfyUI is that the workflow is explicit.

Instead of hiding the image pipeline behind one text box, ComfyUI exposes the steps:

checkpoint loading
prompt encoding
latent image creation
sampling
VAE decoding
image saving
ControlNet inputs
LoRA loading
upscaling
custom nodes

That can look intimidating at first, but it is exactly what makes ComfyUI useful for serious automation.

If an image workflow is just a prompt, an agent has to guess what happened.

If an image workflow is a graph, an agent can inspect the moving parts.

It can reason about the graph. It can reuse it. It can change one piece without rewriting the whole pipeline.

That is the difference between "generate something like this" and "run this visual production workflow again with different inputs."

Agents need workflows, not vibes

For casual generation, a prompt box is fine.

For production work, the weak point is rarely the first image.

The weak point is consistency.

Can you run the same style again?
Can you swap the input image?
Can you keep the ControlNet guide but change the subject?
Can you send the result into an upscale pass?
Can you use the same workflow from a script instead of clicking through the UI?

That is where ComfyUI starts to feel less like an art tool and more like infrastructure.

The workflow JSON becomes the contract.

The agent does not need to remember every step from scratch. It can submit the workflow, poll for the result, download the output, then report what happened.

The API is the underrated part

The visual graph is what people notice first.

The API is what makes it automation-friendly.

A normal agent path looks like this:

Start ComfyUI locally or on a GPU box.
Load or generate a workflow JSON.
Submit that workflow to the /prompt endpoint.
Poll /history/{prompt_id} until the job completes.
Fetch the generated image through /view.
Save the output into a known folder.

That is a much better fit for agents than browser-only image generation.

The agent can run the same workflow from code. It can log prompt IDs. It can keep output paths stable. It can fail cleanly when the server is down or a model file is missing.

That is not glamorous, but it is what makes the workflow usable.

The setup details are the real trap

The hard part is not only "how do I use ComfyUI?"

The hard part is all the small operational details around it:

which Python version is expected
which CUDA or ROCm path is being used
where checkpoint files belong
where LoRAs belong
where ControlNet models belong
how custom nodes are installed
how to run ComfyUI in Docker with GPU access
how to avoid losing outputs in random folders

These details are boring, but agents break on boring details.

That is why I like packaging this kind of workflow as a skill instead of leaving it as a loose note.

For example, I keep a ComfyUI Terminal Skill here:

https://terminalskills.io/skills/comfyui

The point is not "here is another page to read."

The point is that an agent needs a repeatable operating path. The skill gives it the ComfyUI install shape, model folder conventions, API queue example, result polling, custom node setup, ControlNet pattern, and Docker deployment notes in one place.

So when the task is "use ComfyUI for this workflow," the agent is not starting from search results. It has a known path through the tool.

You can also install it directly for an agent:

npx terminal-skills install comfyui --agent codex

That is the useful version of documentation for agent work: not a brochure, not a generic tutorial, but a compact workflow the agent can act on.

A practical ComfyUI agent workflow

If I were building an agent-controlled ComfyUI flow, I would keep it simple at first.

Start with one known working workflow.

Do not begin with ten custom node packs and a giant experimental graph.

Use a small txt2img or img2img workflow and make the agent prove it can:

start or reach the ComfyUI server
submit one workflow
capture the prompt ID
wait for completion
download the generated file
verify the file exists
report the exact output path

Only after that would I add more complexity:

ControlNet
LoRA variants
upscale passes
image prompt adapters
animation nodes
batch generation
remote GPU deployment

The first milestone is not a beautiful image.

The first milestone is a reliable loop.

Why this matters for creative automation

ComfyUI is one of the places where AI image work becomes more like software engineering.

You do not just write a prompt.

You build a pipeline.

That pipeline can be versioned, reused, inspected, debugged, and called from code.

For human artists, that gives more control.

For AI agents, it gives something even more important: structure.

Agents are much more useful when the workflow has shape.

ComfyUI gives image generation that shape.

And once the workflow is explicit, the agent can stop guessing and start operating.

Your Wix Site Is Not the Problem. The Migration Workflow Is.

Alex Shev — Fri, 19 Jun 2026 02:32:16 +0000

Wix is good at the thing it was built for.

It lets someone get a website online without opening a repo, choosing a framework, setting up hosting, wiring a CMS, or learning deployment.

That is useful.

For a lot of businesses, a Wix site is not a mistake. It is the reason they had a website at all.

The problem usually starts later.

The site grows. The business changes. Marketing wants better landing pages. SEO becomes more serious. Someone wants custom checkout logic. Someone wants the blog to behave differently. Someone wants better performance. Someone wants a dashboard, a pricing page, a gated area, a headless CMS, or a proper deployment workflow.

And suddenly the team says:

Can we move this Wix site to React?

That question sounds simple.

It is not.

There is no clean universal "export to Next.js" button for the real version of this job.

You are not just moving pixels.

You are moving a live website with content, layout decisions, SEO assumptions, forms, media, tracking, business logic, and usually a few messy surprises nobody documented.

That is why Wix-to-React migration is a workflow problem, not a framework problem.

The naive version of this task

The naive version sounds like this:

Take this Wix site and rebuild it in React.

An AI agent can try.

It can open the page, inspect the layout, create a component, copy some text, approximate the styling, and produce something that looks close enough in a screenshot.

That is fine for a demo.

It is not enough for a migration.

Because the first screenshot is not the website.

The website is also:

all the pages you forgot to mention
mobile layouts
navigation states
images and files
redirects
metadata
forms
blog posts
product pages
CMS collections
tracking scripts
accessibility issues
weird spacing that only exists on one page
business content that is hidden behind menus
SEO URLs that should not break

If you treat the job like a design clone, you miss the operational work.

If you treat it like an operational migration, the task becomes much clearer.

The real question

The real question is not:

Can React recreate this page?

Of course it can.

The better question is:

What exactly needs to survive the move?

That question changes the whole workflow.

A brochure site with five static pages is one thing.

A Wix site with blog content, member areas, forms, stores, bookings, and SEO history is another.

For a small static site, you might rebuild everything in Next.js and move on.

For a site using Wix CMS or Wix Stores, you have decisions to make:

do you migrate the data out of Wix?
do you keep Wix as a headless backend?
do you recreate the CMS somewhere else?
do you preserve the URL structure?
do you rebuild forms manually?
do you map products to a new ecommerce system?
do you keep any Wix SDK integration?

Those are not code-generation questions.

They are migration design questions.

And if you skip them, the React app may look fine while the business workflow breaks.

Why agents need a skill for this

AI agents are pretty good at writing React components.

They are less reliable when the task is open-ended and the definition of "done" is fuzzy.

That is exactly what a Wix migration is.

Without a workflow, the agent might do the most obvious thing:

open the homepage
copy the visual layout
create a few components
call it a migration

But a real migration needs a more boring sequence:

inventory -> classify -> extract -> rebuild -> migrate data -> verify -> report gaps

That is not glamorous.

It is also the difference between a useful migration and a pretty mockup.

This is where Terminal Skills becomes relevant.

Terminal Skills is a catalog of reusable skills for AI agents. The point is not to give the agent one magic command. The point is to give it a repeatable operating procedure.

For this exact problem, the useful skill is:

wix-to-react

The skill page is here:

https://terminalskills.io/skills/wix-to-react

The important part is the shape of the workflow.

It tells the agent to treat a Wix-to-React conversion as a migration with inspection, decisions, preservation rules, and verification, not as a one-shot clone.

What a Wix-to-React workflow should do first

The first step should not be code.

The first step should be inventory.

Before the agent builds anything, it should answer:

how many pages exist?
which pages are public?
which pages are hidden or linked only from menus?
what content is static?
what content comes from Wix CMS?
are there blog posts?
are there products?
are there forms?
are there bookings, events, or members-only areas?
what scripts are installed?
what URLs need to be preserved?
what assets need to be downloaded?

This is not busywork.

This prevents the classic migration failure:

The homepage was rebuilt, but half the website disappeared.

The homepage is usually the easiest page.

The risk is in the boring pages:

thank-you pages
old campaign landing pages
policy pages
blog detail templates
category pages
product variants
forms connected to business processes

If those pages are not inventoried, they are easy to lose.

The second step is classification

Once you know what exists, you need to classify it.

Not every part of a Wix site should be migrated the same way.

I would separate it like this:

Static marketing pages

These are usually safe to rebuild directly in React or Next.js.

Examples:

homepage
about page
service pages
contact page
pricing page
landing pages

The agent can rebuild these as components, sections, layouts, and reusable content blocks.

CMS-driven content

This needs a data decision.

Examples:

blog posts
case studies
team members
locations
service areas
resource libraries

You can migrate this to another CMS, keep it in files, move it into a database, or use Wix as a headless backend through the Wix SDK.

But the decision needs to be explicit.

Business logic

This is where a screenshot clone fails badly.

Examples:

forms
bookings
ecommerce
member areas
gated downloads
payment flows
email automations

These are not visual elements.

They are workflows.

If the old site uses Wix Forms or Wix Stores, the new React app needs a replacement plan.

SEO and analytics

This is easy to forget because it does not show up in the page design.

But it matters.

The migration should preserve or map:

page titles
meta descriptions
canonical URLs
open graph images
headings
structured data
redirects
analytics events
pixels
conversion tracking

If a business already gets traffic from the Wix site, migration is not just a design task.

It is a traffic-preservation task.

Rebuilding the UI is the easy part

Once the inventory and classification are done, the React work becomes much easier.

The agent can create:

a layout system
shared header and footer
reusable section components
page templates
image components
content loaders
route structure
SEO metadata helpers
form components

This is where React and Next.js shine.

Instead of editing every page manually inside a visual builder, you can create a system.

For example:

components/
  Header.tsx
  Footer.tsx
  Hero.tsx
  ServiceGrid.tsx
  TestimonialSection.tsx
  ContactForm.tsx

app/
  page.tsx
  about/page.tsx
  services/[slug]/page.tsx
  blog/[slug]/page.tsx

The goal is not to recreate Wix as code.

The goal is to turn the site into a maintainable product.

That means reusable components, clear content sources, predictable routes, and a deployment workflow the team can understand.

The Wix SDK option

There is one important nuance.

Moving to React does not always mean abandoning Wix completely.

For some teams, Wix still owns useful business data:

products
CMS collections
bookings
members
blog content

In that case, the migration may become:

React/Next.js frontend + Wix as backend

That is where @wix/sdk can matter.

Instead of ripping everything out immediately, the new app can use Wix data as a headless backend while the frontend becomes custom.

That is not the right answer for every project.

But it is a real migration option.

And it is exactly the kind of decision an agent should surface instead of guessing.

A good workflow should say:

If the site depends on Wix CMS, Stores, Blog, or Forms, decide whether to migrate the data out or keep Wix as a backend before rebuilding those features.

That is a much safer instruction than:

Convert Wix to React.

Verification matters more than generation

The most dangerous part of this workflow is false confidence.

The agent can generate a React app that looks convincing.

But the migration is not done until the output is checked.

A practical verification checklist should include:

every important URL has a matching route or redirect
desktop and mobile layouts are checked
images load from the right source
navigation works
forms submit somewhere real
blog or CMS pages render from data
metadata exists
old URLs are mapped
no obvious console errors appear
performance is acceptable
accessibility basics are not broken

For example:

npm run build
npm run lint
npm run test

Then check the running site:

npm run dev

And inspect actual pages in the browser.

This is the same pattern I keep coming back to in agent workflows:

inspect -> decide -> run -> verify -> report

The code generation part is only one step.

The verification is where the work becomes trustworthy.

Where Terminal Skills fits

This is why I like the Terminal Skills framing.

The useful thing is not "AI can write React."

We already know that.

The useful thing is:

AI can follow a repeatable migration workflow if the workflow is packaged clearly enough.

The wix-to-react skill gives the agent a more specific operating path.

It turns a vague request:

Move my Wix site to React.

Into something closer to:

Inventory the Wix site.
Classify static pages, CMS content, business logic, and SEO requirements.
Choose whether to migrate data or use Wix as a backend.
Rebuild the frontend in React or Next.js.
Verify routes, content, forms, metadata, and deployment readiness.
Report what was completed and what still needs human decisions.

That is much better.

It reduces the number of hidden assumptions.

It also makes the agent easier to supervise.

Instead of asking:

Did it convert the site?

You can ask:

What pages did it inventory?
What content sources did it find?
Which Wix features still need a migration decision?
What routes were rebuilt?
What checks passed?
What is still missing?

Those are better questions.

They produce better work.

The agent should report gaps, not hide them

One thing I would explicitly want in a Wix migration skill:

Do not pretend every Wix feature was migrated if it was only visually approximated.

This matters.

If the old Wix site had a booking workflow and the new React app has a button that looks like "Book Now" but does nothing, that is not a migration.

That is a visual placeholder.

Placeholders are fine if they are labeled.

They are dangerous if they are hidden.

A good final report should say:

rebuilt pages
skipped pages
assets copied
data exported
data not exported
forms recreated
forms still placeholder
SEO mappings completed
redirects still needed
manual decisions required

That kind of honesty is boring.

It is also what makes agent work usable in production.

A realistic migration plan

If I were using an agent for a Wix-to-React migration, I would want the workflow to look roughly like this.

Phase 1: Discovery

Open the Wix site.

Map the visible pages.

Check navigation, footer links, sitemap if available, blog index, product pages, and any public routes.

Create an inventory file.

Phase 2: Feature audit

Identify whether the site uses:

Wix CMS
Wix Blog
Wix Stores
Wix Bookings
Wix Forms
member login
custom code
third-party scripts

This decides how risky the migration is.

Phase 3: Content and asset extraction

Download or document:

images
logos
icons
copy
metadata
blog content
product data
form fields

Do not start rebuilding until the content source is clear.

Phase 4: React/Next.js rebuild

Create the app structure.

Build shared components.

Recreate pages.

Wire content.

Add metadata.

Add forms or placeholder warnings.

Phase 5: Verification

Run build checks.

Open pages locally.

Compare important pages visually.

Check mobile.

Check forms.

Check SEO metadata.

Check old-to-new URL mapping.

Phase 6: Deployment readiness

Prepare environment variables.

Document backend dependencies.

Write redirect rules.

Create a final migration report.

Only then should anyone talk about launch.

The bigger lesson

Wix-to-React is a good example of where AI agent work is going.

The value is not just producing code faster.

The value is turning messy operational work into repeatable workflows.

Most real tasks are not one command.

They are sequences of judgment:

inspect the current system
understand what matters
choose the safest path
make the change
verify the result
explain the remaining risk

That is true for video processing.

It is true for deployment.

It is true for content publishing.

And it is definitely true for migrating a Wix site into React.

The framework is not the hard part.

The workflow is.

That is why skills matter.

Not because they make agents magical.

Because they make agents less random.

Final thought

If you have a small Wix site and it still works, you may not need to migrate it.

No-code tools are not automatically bad.

But if your site has outgrown the builder, the migration needs to be treated like a real software project.

Not a screenshot clone.

Not a prompt.

Not a one-click export fantasy.

A workflow.

That is the reason I like the wix-to-react skill on Terminal Skills.

It frames the job correctly:

inventory, classify, rebuild, verify, and report.

That is how you move from "the agent made something that looks like my Wix site" to "the agent helped migrate the actual website."

Explore the skill here:

https://terminalskills.io/skills/wix-to-react

And if you are building agent workflows around real work, not just demos, the broader Terminal Skills catalog is worth watching:

https://terminalskills.io

Solstice Cipher: a light-routing puzzle for the June Solstice Game Jam

Alex Shev — Sun, 14 Jun 2026 15:41:40 +0000

This is a submission for the June Solstice Game Jam.

What I Built

Solstice Cipher is a small browser puzzle game about the longest day, code-breaking, and the turning point between signal and shadow.

The player rotates mirrors to route a solstice beam through every cipher node before landing on the final beacon. Each level is a tiny circuit of light: if the beam misses a cipher gate, the beacon does not unlock.

The game is inspired by a few June themes from the challenge prompt:

the June solstice and the long arc of daylight
light versus darkness
turning points
Alan Turing, code-breaking, and computational thinking

Demo

Demo video: watch in browser / direct MP4

Playable game: https://desciple88.github.io/solstice-cipher-devto-game-jam/

Source code: https://github.com/desciple88/solstice-cipher-devto-game-jam

How It Works

The game is a dependency-free HTML/CSS/JavaScript canvas app.

The board is a 6x6 grid. A sunbeam enters from one side of the board, moves in one of four directions, and reflects when it hits a mirror:

/ turns east to north, south to west, and so on
\ turns east to south, north to west, and so on

Cipher nodes record whether the beam visited them. A level is solved only when the beam has touched all required cipher nodes and then reaches the beacon.

Controls

Click or tap a mirror to rotate it.
Use Reset or press R to restart the level.
Use Next or arrow keys to switch levels.
Use Hint or press H if the path gets stuck.

Why the Turing Angle

I wanted the Alan Turing category to feel like part of the mechanics, not just a label. The player is effectively debugging a simple signal machine: change one reflector, trace the path, see which gates activated, and iterate until the message resolves.

It is not an Enigma simulator, but it borrows the feeling of signal routing, symbolic gates, and systematic code-breaking.

What I Used

HTML
CSS
JavaScript
Canvas 2D
ffmpeg for the demo capture

AI assistance was used while preparing the implementation and write-up. I am not entering this under the Best Google AI Usage category because I could not complete a real Google AI toolchain step during the build; the local Gemini CLI was unavailable in my environment.

What I Learned

For a tiny jam game, the best scope was a mechanic that could be understood instantly: rotate mirrors, follow light, unlock the beacon.

The solstice theme gave the visual direction. The Turing theme gave the rules: the path is not just pretty, it has to carry a complete signal.

MCP Gives Your Agent Stripe Access. Skills Tell It What Not to Break.

Alex Shev — Sun, 14 Jun 2026 13:10:19 +0000

Stripe integrations are one of the places where AI coding agents look magical right up until they are dangerous.

The agent can read docs.

It can generate a checkout flow.

It can wire a webhook.

It can create a connected account, move money between a platform and a seller, and leave you with code that looks believable.

That last part is the problem.

Payments code does not fail like a todo app.

If a todo app has a bad edge case, someone cannot mark a task complete.

If a marketplace payment flow has a bad edge case, the wrong party collects fees, a seller cannot finish onboarding, a payout goes missing from your internal state, or a webhook retry silently creates a reconciliation mess.

This is why I do not think "just connect the agent to Stripe MCP" is enough.

MCP gives the agent access.

A skill gives the agent a playbook.

The access layer: Stripe MCP

Stripe has an MCP server for agentic workflows.

That matters because an agent can work with Stripe through a structured tool surface instead of guessing from memory or copy-pasting stale snippets from the web.

Stripe's own docs describe the MCP server as a set of tools agents can use to interact with the Stripe API and search Stripe's knowledge base.

That is a real improvement over asking an LLM:

"Build Stripe Connect for my marketplace"

and hoping it remembers the latest API shape.

But access is not the same thing as judgment.

If an agent has a Stripe tool, it still needs to know:

which Connect charge type fits the product model
whether sellers need Express, full dashboard access, or a fully embedded flow
where to store the connected account id
which events must update internal order state
when to use direct charges vs destination charges vs separate charges and transfers
how to handle refunds, disputes, onboarding requirements, and payout status

Those are not just API calls.

They are product decisions.

The instruction layer: a Stripe Connect skill

The latest Stripe-related skill I looked at on Terminal Skills is stripe-connect.

It is built for marketplace and platform payments:

two-sided marketplaces
seller/provider onboarding
splitting payments between buyers and sellers
platform fees
payouts
connected account management
Connect webhooks

The important detail is that the skill is not just a list of endpoints.

It tells the agent how to reason through the flow.

For example, the skill uses Stripe Accounts v2 for new Connect platforms. Instead of thinking in the old flat type: "express" shape first, it frames a connected account around configurations:

merchant for accepting payments
recipient for receiving transfers and payouts
customer for being billed as a customer

That is the kind of detail an agent can easily miss if it is only pattern-matching from older examples.

The skill also makes dashboard access explicit:

express for Stripe-hosted onboarding and dashboard
full for sellers who need a full Stripe dashboard or OAuth-style flow
none for embedded/custom platform control

That distinction matters because onboarding is not just a technical step. It changes who owns UX, support, compliance surface, and seller control.

Why this belongs in a skill, not just a prompt

You can tell an agent:

"Use Stripe best practices."

That sounds clear.

It is not.

Best practices for what?

A simple SaaS checkout?

A usage-based subscription?

A marketplace with sellers?

A white-label platform?

A service marketplace where money should be held until work is delivered?

Those are different systems.

A good skill narrows the task before code starts appearing.

For Stripe Connect, I want the agent to ask and encode questions like:

Is the platform the merchant of record, or is the seller?
Does the seller need dashboard access?
Should the platform collect the fee at charge time?
Is fulfillment immediate, delayed, or milestone-based?
What internal state changes when onboarding completes?
Which webhook events are the source of truth?
What happens on refund, dispute, failed payment, and failed payout?

That is the work.

The API call is the last mile.

The most useful part: choosing the charge model

A lot of marketplace payment bugs start with choosing the wrong charge model.

The stripe-connect skill separates the main options:

Direct charges

The charge happens on the connected account.

This can make sense when the seller should own more of the payment relationship and see the charge directly in their Stripe account.

Destination charges

The platform creates the charge and routes funds to the seller.

This is often the clean marketplace default when the platform controls the buyer experience and collects an application fee.

Separate charges and transfers

The platform charges the buyer first, then transfers funds later.

This is the flexible option when delivery, risk, escrow-like timing, or multi-party routing matters.

The agent needs to make this decision before it writes the PaymentIntent code.

Otherwise it may produce code that works in a test card happy path but does not match the business.

Webhooks are where the integration becomes real

Stripe integrations are not done when the payment succeeds in the browser.

They are done when the backend state survives reality.

That means webhooks.

For Connect, the platform may need to listen for:

onboarding updates
payment success and failure
transfers
payouts
disputes
connected-account events

The skill calls out an easy-to-miss detail: Accounts v2 emits thin events through event destinations, and onboarding status can require listening for account requirements updates.

That is exactly the kind of thing a generic prompt can skip.

It may build the happy path and leave the operational path unfinished.

Where Stripe MCP and skills fit together

The way I think about it:

MCP is the tool socket.

The skill is the operating procedure.

Stripe MCP can let the agent query Stripe knowledge, inspect resources, and work through a structured API-facing interface.

The stripe-connect skill tells the agent how a marketplace payment system should be assembled:

define the seller account model
create the connected account
generate onboarding
store the account id
choose the charge type
collect platform fees intentionally
wire webhooks
handle refunds, disputes, and payouts
test with Stripe CLI and test cards

That is the difference between "agent can call Stripe" and "agent can build the right Stripe flow."

The agent should not be trusted with vague money movement

This is the big lesson for me.

AI agents are getting better at implementation.

But money movement is not just implementation.

It is policy, product design, compliance boundary, risk handling, and state reconciliation.

So the workflow should look more like this:

Human defines the marketplace model
        |
        v
Skill frames the Stripe Connect decisions
        |
        v
MCP/API tools give the agent current Stripe access
        |
        v
Agent writes the implementation
        |
        v
Tests + webhooks + review prove the money flow

That is the stack I trust more than a big prompt.

Not "AI, build payments."

"AI, follow this payment architecture, use current Stripe tools, and show me the decisions before you move money."

That is where agents start becoming useful for serious backend work.

Source:

Terminal Skills stripe-connect: https://terminalskills.io/skills/stripe-connect
Stripe MCP docs: https://docs.stripe.com/mcp
Stripe AI build docs: https://docs.stripe.com/building-with-ai

Product Videos Should Be Build Artifacts, Not Manual Exports

Alex Shev — Tue, 09 Jun 2026 19:42:24 +0000

Every product launch needs the same small pile of video assets:

a 16:9 demo clip for the launch page
a square cut for social
a GIF preview for the changelog
a poster image for email

The weird part is how often that still means opening a video editor by hand.

Someone updates the product copy. Someone swaps the screen recording. Someone exports a new MP4. Someone crops another version. Then two weeks later the same release video cannot be reproduced exactly because the editor timeline, font version, plugin state, or export preset drifted.

For product teams, that is the wrong abstraction.

The launch video should be closer to a build artifact.

Change the source. Open a PR. Let CI render the exact same video every time.

The useful idea: HTML as the video source

Most product launch videos are not cinema.

They are structured compositions:

headline
short subcopy
screen recording
background audio
a few transitions
a logo or CTA

That maps surprisingly well to HTML and CSS.

Instead of keeping the source of truth in a visual editor, the source can live in a normal index.html file:

<div
  id="stage"
  data-composition-id="release-2-4"
  data-start="0"
  data-width="1920"
  data-height="1080"
>
  <video
    data-start="0"
    data-duration="8"
    src="assets/screencast.mp4"
  ></video>

  <h1
    id="headline"
    data-start="1"
    data-duration="5"
  >
    v2.4 - Realtime Collaboration
  </h1>

  <p
    id="sub"
    data-start="2"
    data-duration="4"
  >
    Comment, mention, resolve - live.
  </p>

  <audio
    data-start="0"
    data-duration="8"
    data-volume="0.7"
    src="assets/bed.wav"
  ></audio>
</div>

That one file now carries things a video editor usually hides:

canvas size
timing
copy
media references
animation hooks
composition id

And because it is text, it can be reviewed like any other product change.

The important part is deterministic rendering

Rendering HTML to video is only useful if the result is reproducible.

If a CI job renders a different file every time, the system is just another flaky media tool.

The better workflow is frame-seeking:

Load the HTML composition in headless Chrome.
Seek to each timestamp.
Capture the frame.
Encode the frames into MP4.
Produce the same output from the same source.

That is the reason HyperFrames is interesting here. It treats HTML, CSS, media, and seekable animation as a renderable video composition.

Then FFmpeg handles the boring but necessary production work:

# master render
npx hyperframes lint
npx hyperframes render

# 1:1 social cut
ffmpeg -i out/release-2-4.mp4 \
  -vf "crop=1080:1080:420:0" \
  -c:a copy \
  out/release-2-4-square.mp4

# lightweight GIF for changelog
ffmpeg -i out/release-2-4.mp4 \
  -vf "fps=12,scale=640:-1:flags=lanczos" \
  out/release-2-4.gif

# poster frame for email
ffmpeg -ss 2 \
  -i out/release-2-4.mp4 \
  -frames:v 1 \
  out/release-2-4-poster.jpg

One master render becomes every format the team needs.

Why CI is the right place for this

For a small SaaS team, the release note is already part of the engineering workflow.

The video can be too.

name: Render launch video

on:
  push:
    tags: ["v*"]

jobs:
  render:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "22"

      - run: sudo apt-get update && sudo apt-get install -y ffmpeg

      - working-directory: launch-video
        run: |
          npx hyperframes lint
          npx hyperframes render
          ffmpeg -i out/release-2-4.mp4 -vf "crop=1080:1080:420:0" -c:a copy out/square.mp4

      - uses: actions/upload-artifact@v4
        with:
          name: launch-video
          path: launch-video/out/*.mp4

Now the video is attached to the release process:

copy changes are visible in PRs
timing changes are versioned
release tags regenerate the same artifacts
reviewers can inspect the rendered output
social cuts come from the same master file

The team is not replacing creative work with CI.

It is removing the repetitive export layer around a video that is mostly structured product information.

Where this fits

This works best for videos that are template-driven:

product launch clips
changelog videos
feature teasers
onboarding explainers
social demos
doc/video snippets

It is probably the wrong tool for a cinematic brand film.

But most weekly product videos are not cinematic. They are release communication.

And release communication should be repeatable.

The agent angle

The interesting part is what happens when an AI coding agent can edit the video source.

An agent can:

update the release copy
swap in a new screencast
adjust timing
add a maintained transition block
run the lint step
render the preview
post-process the output

That is much more useful than asking an AI tool to generate a random video from a prompt.

The agent is working inside the same system as the product team: files, PRs, CI, artifacts, and review.

That is where AI video automation starts to feel practical.

I wrote up the full workflow here:

https://terminalskills.io/use-cases/automate-product-videos-from-html

The short version:

If the video changes every release, put the video source next to the release.

Then let the build system render it.

How to Write Terminal Skills That AI Agents Can Actually Use

Alex Shev — Mon, 08 Jun 2026 21:07:58 +0000

Most AI agent advice still sounds like prompt advice.

Add more context.
Write clearer instructions.
Give the model examples.
Use a better system prompt.

That helps, but it misses the part that breaks in real work.

The problem is not always that the agent does not know a command. The problem is that the agent does not know your workflow.

It does not know when to inspect first.
It does not know which defaults are safe.
It does not know what "done" means.
It does not know when to stop instead of guessing.
It does not know which checks matter before something leaves the local machine.

That is where Terminal Skills become useful.

A Terminal Skill is not just a command shortcut. It is a small reusable operating procedure for an agent.

It teaches:

when to use a workflow
what inputs are acceptable
which commands or scripts are preferred
what output should exist
how to verify the result
when to stop and ask for help

That last part is the difference between a useful agent workflow and a confident mess.

Here is the pattern I use when writing one.

Start with the task, not the tool

The easiest mistake is to begin with a tool name.

Bad starting point:

Make an FFmpeg skill.

Better starting point:

Make a skill that turns a raw video file into an X-ready MP4, then verifies the upload is likely to work.

Those are different scopes.

The first one is a tool wrapper.

The second one is a workflow.

Agents do not need every possible FFmpeg flag. They need a stable path through a common problem.

The same applies to any terminal workflow:

not "make a git skill"
but "review a dirty worktree without touching unrelated user changes"
not "make a deploy skill"
but "deploy a Next.js app to Vercel and verify the live URL"
not "make a search skill"
but "inspect a repo and find the smallest safe file set for this task"

The more specific the workflow, the more useful the skill.

A useful skill has a contract

I like thinking about a Terminal Skill as a contract between the human, the agent, and the machine.

The contract says:

If this kind of task appears,
and these inputs exist,
follow this workflow,
produce this output,
run these checks,
and stop under these conditions.

That sounds simple, but it removes a lot of randomness.

Without a contract, the agent improvises.

With a contract, the agent has a default operating path.

That does not make the agent less intelligent. It makes the work less dependent on fresh reasoning every time.

The basic structure

For most Terminal Skills, I would start with a folder like this:

my-skill/
  SKILL.md
  scripts/
    run.sh
  examples/
    input-example.txt
  README.md

Not every skill needs a script.

Some skills are mostly procedural. Some are wrappers around existing CLIs. Some are just strong instructions plus verification commands.

But the SKILL.md is the important part.

It should tell the agent how to work, not just what the tool does.

Here is a practical template.

# Skill Name

## Use When

Use this skill when the user asks to:
- ...
- ...

## Do Not Use When

Do not use this skill when:
- ...
- ...

## Inputs

Expected inputs:
- source file or directory
- target format
- optional config

## Workflow

1. Inspect the input.
2. Choose the smallest safe action.
3. Run the script or command.
4. Verify the output.
5. Report the result with file paths and any warnings.

## Commands

```bash
./scripts/run.sh input-file
```

## Verification

Check:
- output file exists
- output format is correct
- command exited successfully
- logs contain no obvious errors

## Stop Conditions

Stop and ask the user if:
- required input is missing
- output validation fails
- the task would publish, delete, charge, email, or deploy something
- the command could overwrite user data

That is already more useful than a loose prompt.

It gives the agent a map.

The most important section is "Stop Conditions"

Most people underwrite this part.

They document the happy path and skip the failure boundaries.

But agents need stop conditions badly.

A good skill should say things like:

stop if the repo has unrelated user changes
stop if the API token is missing
stop if the public page cannot be verified
stop if the output file has no video stream
stop if the command would delete or overwrite source files
stop if the user approved a draft but did not approve publishing

This is where agent workflows become safer.

For example, a social publishing skill should not only say:

Open the composer and publish the post.

It should say:

Before posting, verify the composer contains the exact approved text.
After posting, verify the final permalink shows the full text and attached media.
If media is missing, do not report success.

That is a real operating rule.

It captures the part of the workflow that normally lives in someone's head.

Verification should be concrete

"Check that it worked" is not enough.

A good Terminal Skill names the actual check.

For a video skill:

ffprobe -v error -show_streams -show_format output.mp4

For a code skill:

npm test
git diff --check

For a content publishing skill:

Open the final live URL.
Confirm the title, body, tags, canonical URL, and media are visible.
Do not trust the editor preview as final verification.

For a data export skill:

Check row count, headers, encoding, and sample records before sending the file.

Agents are very good at saying "done" too early.

Verification commands make "done" harder to fake.

Keep the skill narrow

The best skills are boringly specific.

Bad:

content-automation

Better:

devto-draft-from-markdown
x-safe-video-export
reddit-comment-visibility-check
vercel-preview-deploy-and-verify

Narrow skills have clearer triggers and fewer hidden assumptions.

They are also easier to improve.

If a video export fails, fix the video skill.
If a DEV.to draft misses a canonical URL, fix the DEV.to skill.
If a Reddit comment is visible to the owner but not public, fix the visibility check.

One giant "content automation" skill would hide all of those failures inside one vague blob.

Small skills make the workflow inspectable.

Use scripts for mechanics, instructions for judgment

I do not think every skill should become a huge script.

Scripts are good for mechanical repeatability:

convert this file
validate this JSON
resize this image
call this API
generate this report

Instructions are better for judgment:

when to use the script
which candidates to reject
how to handle approval
what counts as verification
when not to continue

The skill should combine both.

For example:

SKILL.md explains the workflow.
scripts/export.sh performs the conversion.
Verification commands prove the output.
Stop conditions prevent the agent from bluffing.

That is the useful shape.

Not "the agent has a tool."

"The agent has a way of working."

Example: a tiny repo-inspection skill

Here is a small example that does not need a script.

# Repo Inspection

## Use When

Use this before editing an unfamiliar codebase.

## Workflow

1. Print the current directory.
2. Check git status.
3. List top-level files.
4. Identify package/framework files.
5. Search for relevant code with ripgrep.
6. Read the smallest useful files before editing.

## Preferred Commands

```bash
pwd
git status --short
rg --files | head -80
rg -n "keyword|component|route" .
```

## Stop Conditions

Stop before editing if:
- the user has unrelated changes in the target file
- the task requires a destructive git command
- the repo structure is unclear after inspection

## Verification

Before reporting done:
- show changed files
- run the smallest relevant test or check
- explain any test that could not be run

This is not glamorous.

But it prevents a lot of common agent mistakes.

It teaches the agent the shape of careful work.

What makes a skill good?

I usually judge a skill by five questions.

1. Does it have a clear trigger?

The agent should know when to use it.

If the trigger is vague, the skill will either be ignored or overused.

2. Does it reduce repeat reasoning?

A good skill saves the agent from rediscovering the same workflow again.

If the workflow is only used once, it may not need a skill yet.

3. Does it define done?

The skill should say what output must exist and how to verify it.

If "done" is subjective, the agent will guess.

4. Does it include stop conditions?

This is the safety layer.

The skill should prevent confident continuation when the workflow is missing a required input, external approval, or verification.

5. Is it small enough to maintain?

If the skill becomes a giant manual for everything, it stops being useful.

Small, composable skills are easier to trust.

The bigger point

AI agents are getting better at tool use.

That does not mean every workflow should be improvised in chat.

The more capable the agent becomes, the more important operating procedures become.

Prompts are good for intent.
Tools are good for capability.
Skills are good for repeatable work.

That is the layer I think more developers should build.

Not because it is flashy.

Because boring, reusable workflows are what turn agents from demos into something you can actually depend on.

I am collecting more examples of this pattern at Terminal Skills.

If you are building your own agent workflows, start with one annoying task you repeat every week.

Write down the trigger, workflow, verification, and stop conditions.

That is your first skill.