DEV Community: Yonyon

OrchestKit scored 83/100 on ORA — what "agent-readiness" actually measures

Yonyon — Wed, 17 Jun 2026 06:43:34 +0000

I ran OrchestKit — my open-source Claude Code toolkit — through ORA, an independent audit that scores how agent-ready a product is: how easily an AI agent can discover you, identify itself, authenticate, and actually get work done against your surface.

Result: 83/100, Grade B ("Competitive"), ranked #49 of 12,200.

The breakdown

Layer	Score
Auth & Access	28/30	🟢 Strong
Agent Integration	18/20	🟢 Strong
Identity	18/20	🟢 Strong
User Experience	10/10	🟢 Perfect
Discovery	9/20	🟠 Partial

What I take from it

The foundation is strong: an agent can identify, connect, and use OrchestKit with near-zero friction — exactly what an agent-native toolkit should be.

The one hole is Discovery — presence, not product. The thing is ready; it just needs more people (and agents) to know it exists. Honestly the most fun problem to have, and it's the next focus.

Solo-built. Open-source. Independently verified.

→ https://orchestkit.yonyon.ai

Making your docs site agent-readable: llms.txt, MCP, and the .well-known files that actually matter

Yonyon — Sun, 14 Jun 2026 17:13:20 +0000

AI agents increasingly read your docs instead of a human. If your documentation site only emits HTML for a browser, an agent has to scrape and guess. There's a better surface — and most of it is a handful of small, standard files. Here's the full stack we ship on the OrchestKit docs site, why each piece exists, and how to verify it.

1. `llms.txt` — the agent's table of contents

A plain-text index at /llms.txt: what the product is, its constraints, and a link map to every machine-readable resource. Keep it under ~30k chars; put the exhaustive page list in /docs/llms.txt and the full corpus in /llms-full.txt. The win: an agent gets oriented in one fetch instead of crawling.

2. Markdown content negotiation

Append .md to any page URL (or send Accept: text/markdown) and return the raw Markdown. Agents get clean tokens; humans still get the rendered page.

3. An OpenAPI spec for your read APIs

Even a docs site has an API surface (search, page fetch). Publish an OpenAPI document at a predictable path so an agent can call it without reverse-engineering. Pair it with RFC 9727 — a /.well-known/api-catalog linkset that enumerates every API entry point.

4. An MCP server

The Model Context Protocol lets agents call your tools natively. We expose a read-only MCP server over Streamable HTTP at /api/mcp plus a discovery server-card.json. Two tools — search docs, get a doc by id — are enough to be useful.

5. The `.well-known` identity files

agent-card.json (A2A): declares your agent skills.
agent-skills/index.json: the Agent Skills Discovery RFC, with a SHA-256 digest per skill so a consumer can verify it.
oauth-protected-resource (RFC 9728): if your API is anonymous, say so — an empty authorization_servers is a positive signal, not an omission.

6. JSON-LD that an entity graph can reconcile

Emit a schema.org graph (Organization, SoftwareApplication, WebSite) linked by @id, with sameAs pointing at the registries that already verify you (GitHub, your package registry, Wikidata). One canonical Organization block, reused everywhere, so the graph never sees conflicting identifiers. Never fabricate an aggregateRating — surface real signals (e.g. GitHub stars as an InteractionCounter) instead.

7. Tell crawlers the truth in `robots.txt`

Explicitly allow the named AI crawlers you want (GPTBot, ClaudeBot, OAI-SearchBot, Google-Extended…), and emit a Content-Signal directive. Link your sitemap and a schema-map.

How to verify

curl -s https://yoursite/llms.txt, fetch each .well-known path, and run your JSON-LD through a structured-data validator. If you build on Claude Code, the open-source OrchestKit docs site implements every item above — the source is on GitHub, MIT-licensed, and you can read the route handlers directly.

I maintain OrchestKit (a free, MIT plugin for Claude Code, 111 skills/37 agents/210 hooks). The agent-discovery surface described here is what its docs site ships today.

I made my portfolio readable by AI agents. A scanner found four things that didn't exist

Yonyon — Thu, 11 Jun 2026 16:42:20 +0000

Last week I wrote about making my site fully agent-readable — an MCP server, an NLWeb /ask endpoint, llms.txt, a .well-known/ discovery tree. Shipping those was the easy half.

Then I started scoring the site with an agent-readiness scanner — a prober that visits like a real agent: no JavaScript execution, spec-shaped requests, no goodwill. Every round it found something that worked in my browser and did not exist as far as an agent could tell.

These are the four that stung. All real code from yonyon.ai, all fixed this round.

1. The "helpful" GET that made my endpoint read as missing

My /ask endpoint (Microsoft's NLWeb shape) answered POST { "query": "..." }. For GET, I did what felt like good API manners — return a machine-readable descriptor telling the caller how to use the endpoint:

// GET /ask — the old version
export function GET(): Response {
  return Response.json({
    _meta: { response_type: "nlws", version: NLWEB_VERSION },
    description: 'POST { "query": "..." } for answers...',
    method: "POST",
  });
}

Polite, self-documenting, useless. The NLWeb reference client — and therefore the scanner — issues GET /ask?query=... and expects an answer. It got my descriptor back, which is not an answer, so the endpoint graded as not implemented. My documentation-instead-of-data response was indistinguishable from a stub.

The fix: GET with a query parameter runs the real pipeline (including SSE via ?streaming=true); a bare GET keeps the descriptor.

export async function GET(req: Request): Promise<Response> {
  const url = new URL(req.url);
  const hasQuery = ["query", "q", "question"].some((k) => url.searchParams.get(k)?.trim());
  if (hasQuery) return handleAsk(req); // same pipeline as POST, SSE supported
  return descriptor(); // bare GET still teaches probing agents how to call it
}

Lesson: agents don't read your descriptor and adapt — they call you the way their reference client calls everyone. Implement the spec's client behavior, not your idea of good manners.

2. The WebMCP tools nobody could see

I exposed in-browser tools via WebMCP (navigator.modelContext, Chrome early preview): ask_yonatan, browse_projects, book_intro_call. The natural React implementation is a client component:

"use client";
export function WebMcpTools() {
  useEffect(() => {
    const provide = (navigator as any).modelContext?.provideContext;
    if (typeof provide !== "function") return;
    provide.call(navigator.modelContext, { tools: [/* ... */] });
  }, []);
  return null;
}

Feature-detected, try/caught, tidy. Also invisible. Crawlers and scanners detect WebMCP support by scanning the unhydrated document — they don't run your bundle, and even executing browsers without the experimental API skip the registration entirely. A hydration-gated capability has no static trace. As far as any external observer was concerned, the site had no WebMCP support at all.

The fix is almost embarrassing: a server component that emits the registration as an inline <script>, so it's right there in the raw HTML:

// Server component — no hydration involved
const WEBMCP_REGISTRATION = String.raw`(function () {
  var mc = navigator.modelContext;
  if (!mc || typeof mc.provideContext !== "function") return;
  mc.provideContext({ tools: [ /* same tools, plain JS */ ] });
})();`;

export function WebMcpScript() {
  return <script dangerouslySetInnerHTML={{ __html: WEBMCP_REGISTRATION }} />;
}

(Next.js already requires 'unsafe-inline' in CSP, so this adds no new policy cost. If your CSP is stricter, use a nonce.)

Lesson: a runtime-registered agent capability needs a statically visible twin. If it can't be seen in curl output, it doesn't exist.

3. The status page that 404'd in production only

I added /status — a tiny health page with content negotiation: JSON for Accept: application/json, HTML for humans. It worked in dev. In production: 404.

The culprit was next-intl's middleware. My site is internationalized, and the middleware matches every page-ish path and routes it into the [locale] tree. I'd even left myself a comment claiming route handlers escape the middleware. They don't. Bare /status was being locale-routed into /[locale]/status, which doesn't exist.

// src/proxy.ts — the matcher had to exclude /status explicitly
export const config = {
  matcher: "/((?!api|studio|trpc|_next|_vercel|status|.*\\..*).*)",
};

And there was a second bug hiding behind the first: I'd marked the route force-static for cheapness. Static means Next.js prerenders one variant — with an empty Accept header — and serves that frozen response to everyone. My own content negotiation could never run. It had to be force-dynamic with Vary: Accept.

Lesson: i18n middleware and agent endpoints fight over the same URL space, and the agent endpoints lose silently. Every bare path you promise agents (/ask, /mcp, /status) needs an explicit carve-out — and content negotiation is incompatible with static prerendering by definition.

4. `ai-train=yes`, on purpose

Most advice about AI crawlers is defensive: block GPTBot, block CCBot, opt out of training. My robots.txt does the opposite, explicitly:

# Content Signals (https://contentsignals.org). Discovery is a goal for this
# site, so AI training is allowed — being in training corpora is the point.
Content-Signal: search=yes, ai-input=yes, ai-train=yes

This is a portfolio. Its entire job is to be found when someone — increasingly, someone's agent — asks "who can build a production RAG system?" An assistant that learned about my work during training, or retrieves it at inference time, is doing my marketing. Blocking that to protect content whose value is being known would be self-defeating.

That trade-off is deliberate and it isn't right for everyone — if your content is the product, sell it, don't donate it. But make the choice consciously. The default-deny advice assumes your content's value is captured by humans reading it on your domain. For a personal site optimizing for discovery, the math runs the other way. (The same file blocks Bytespider and other bulk scrapers that offer no assistant or search surface — welcome the tier that cites you, refuse the tier that doesn't.)

The pattern under all four

"Agent-readable" turned out to be two separate properties, and I kept confusing them:

Works when called correctly — the endpoint answers, the tool executes.
Discoverable by something that won't call you correctly — no JS execution, spec-default request shapes, bare paths, raw HTML.

Everything above failed on the second property while passing the first. My browser hydrated the WebMCP component; the scanner read static HTML. My docs explained POST /ask; the prober sent GET. Dev served /status; production's middleware ate it.

The only thing that caught any of this was pointing an external, JS-free, spec-literal scanner at the production domain and treating its score as the truth. Your own browser is the worst possible test client for agent-readability — it's too forgiving.

The full implementation (MCP server, NLWeb endpoint, llms.txt, .well-known tree) is covered in part one. Try the live surfaces: curl -X POST https://yonyon.ai/ask -d '{"query":"what does yonatan build?"}' or GET https://yonyon.ai/status with Accept: application/json.

How I made my website fully agent-readable: an MCP server + NLWeb /ask in Next.js

Yonyon — Tue, 09 Jun 2026 10:13:55 +0000

How I made my website fully agent-readable: an MCP server + NLWeb /ask in Next.js

Most websites are built for humans with browsers. Increasingly, the visitor is an AI agent — Claude, a custom assistant, some autonomous tool — and it doesn't want your hero animation. It wants structured, machine-readable answers and actions it can take.

I rebuilt my own site, yonyon.ai, to be readable and usable by agents end to end: a live /ask endpoint (Microsoft's NLWeb shape), a real MCP server at /mcp, in-browser WebMCP tools, plus llms.txt and a .well-known/ discovery tree. This post is the worked example — the three pieces that did the heavy lifting, with the actual code.

The trap: locale routing eats your agent endpoints

My site is internationalized with next-intl. Its middleware matches every path and routes it into a [locale] segment. So the moment I added a bare /ask route for agents, the i18n middleware grabbed it first and tried to render /[locale]/ask — 404. Same problem would hit /mcp.

Agents expect bare, unprefixed paths (/ask, /mcp) — not /en/ask. The fix is to intercept those paths in the proxy/middleware, before the i18n matcher runs, and rewrite them onto the real API route. rewrite() (not redirect()) preserves the HTTP method and body, so a POST /ask stays a POST:

// src/proxy.ts  (next-intl middleware entrypoint)
import createMiddleware from "next-intl/middleware";
import { NextResponse, type NextRequest } from "next/server";
import { routing } from "./i18n/routing";

const intlMiddleware = createMiddleware(routing);

export default function proxy(request: NextRequest) {
  // Rewrite the bare /ask onto the /api/ask route handler BEFORE next-intl
  // pulls it into the [locale] tree (which would 404). rewrite() keeps the
  // method + body, so POST /ask works.
  if (request.nextUrl.pathname === "/ask") {
    return NextResponse.rewrite(new URL("/api/ask", request.url));
  }
  return intlMiddleware(request) as NextResponse;
}

export const config = {
  // Skip /api, /_next, static files, etc. — only run on page-ish paths.
  matcher: "/((?!api|studio|trpc|_next|_vercel|.*\\..*).*)",
};

That's the whole alias trick: bare agent paths are matched first and rewritten into /api/*, so they never reach the locale router. Add a line per endpoint you want to expose unprefixed.

A dependency-free MCP server

The Model Context Protocol is how agents discover and call your tools. The official SDK is great — but it peer-depends on zod 3, and my repo is on zod 4. Rather than fight the dependency tree, I hand-rolled the handler. MCP's Streamable-HTTP transport is just JSON-RPC 2.0 over POST, and I only needed a handful of methods: initialize, tools/list, tools/call, ping. Zero dependency risk:

// src/app/api/mcp/route.ts
export const dynamic = "force-dynamic";

const SERVER_INFO = { name: "yonyon.ai", version: "1.0.0" };
const PROTOCOL_VERSION = "2025-06-18";

const TOOLS = [
  {
    name: "ask_yonatan",
    description: "Ask about Yonatan Gross's work, projects, or experience.",
    inputSchema: {
      type: "object",
      properties: { question: { type: "string", maxLength: 2000 } },
      required: ["question"],
      additionalProperties: false,
    },
    // Behavioural hints so agents can reason about side effects:
    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
  },
  // browse_projects, book_intro_call ...
];

const rpc = (id, result) => Response.json({ jsonrpc: "2.0", id, result });
const rpcError = (id, code, message) =>
  Response.json({ jsonrpc: "2.0", id, error: { code, message } });

export async function POST(req: Request) {
  const { id, method, params } = await req.json();

  if (method === "initialize")
    return rpc(id, { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: SERVER_INFO });

  if (method === "tools/list") return rpc(id, { tools: TOOLS });

  if (method === "tools/call") {
    const { name, arguments: args } = params;
    if (!TOOLS.some((t) => t.name === name))
      return rpcError(id, -32602, `Unknown tool: ${name}`); // structured error, not soft text
    return rpc(id, await callTool(name, args));
  }

  if (method === "ping") return rpc(id, {});
  return rpcError(id ?? null, -32601, `Method not found: ${method}`);
}

Two details that matter for agent ergonomics:

Tool annotations (readOnlyHint, destructiveHint, openWorldHint) let a planner decide whether a tool is safe to call autonomously.
An unknown tool returns a structured JSON-RPC error (code + message), not a friendly text blob — so agents branch on it programmatically instead of string-matching.

Discovery: llms.txt + .well-known

Endpoints are useless if nothing can find them. Two conventions cover it:

/llms.txt — a human- and agent-readable map of the site, modeled on robots.txt but for LLMs: who you are, what an agent can do here, and the exact endpoints:

# yonyon.ai — Yonatan Gross

> AI Platform Engineer & Backend Developer. Builds production AI systems
> end-to-end: RAG pipelines, multi-agent architectures, MCP servers.

## What an agent can do here
- Ask about my work — POST /ask with {"query":"..."}  (NLWeb, no auth)
- Browse projects, book a free 15-min intro call
- MCP server at /mcp (initialize, tools/list, tools/call)

The .well-known/ tree carries the machine-readable specs:

public/.well-known/
├── mcp.json                 # points agents at /mcp
├── mcp/server-card.json     # MCP server identity card
├── openapi.json             # OpenAPI for the HTTP endpoints
├── api-catalog              # RFC 9727 linkset of all APIs
└── agent-skills/            # discrete "skills" (ask, browse, book) as SKILL.md

Because these live in public/, they're served as plain static files — bypassing the locale router entirely, so there's no dotpath/404 issue. I also emit RFC 8288 Link headers (rel="describedby" → llms.txt, rel="service-desc" → openapi.json) so an agent that only fetches headers still discovers everything.

The payoff

You can verify it live:

curl -s https://yonyon.ai/ask \
  -H 'content-type: application/json' \
  -d '{"query":"What does Yonatan build?"}'

That single-shot, no-auth, agent-facing endpoint returns a grounded answer from the same RAG-backed model that powers the site chat. An agent can then call the MCP book_intro_call tool and act.

Building agent-ready surfaces is also just good practice for the corpus AI models train on — the more structured and citable your presence, the more likely a model recalls your work. I package these patterns (and a lot more) as OrchestKit, my open-source Claude Code agent framework — 111 skills, 37 agents, 211 hooks.

If you're making something agent-readable and want a second pair of eyes, the front door at yonyon.ai is itself the demo — ask it a question, or grab a free 15-minute intro call.

Building an Automated Content Pipeline That Posts to 6 Platforms

Yonyon — Thu, 12 Mar 2026 10:32:21 +0000

Every developer knows the pain: you write a great article, publish it on one platform, and then spend the next hour manually reformatting and posting it everywhere else.

I built an automated content distribution pipeline that publishes to 6 platforms from a single source of truth. Here's how.

The Architecture

Write once, distribute everywhere:

Hashnode (source of truth)
Dev.to (you're reading this here)
LinkedIn (article share + commentary)
Threads (text teaser)
Instagram (card image + caption)
daily.dev (auto via RSS)

Each platform gets a tailored variant — not a blind copy-paste.

The Platform Adapter Pattern

Each platform implements a common interface with a single publish() method. Adding a new platform is just implementing one class. Rate limiting is Redis-backed per platform.

Smart Content Composition

The hardest part isn't the API calls — it's making content feel native. Twitter gets a 280-char hook. Threads gets a 500-char teaser. LinkedIn gets a 3,000-char article share.

The Quality Ladder

Ollama (local, free) generates the first draft
Quality gate checks readability and boring-start patterns
Claude Haiku polishes if needed (~$0.002)
Template fallback as safety net

The Feedback Loop

A weekly task evaluates performance, extracts patterns, and injects learnings into future prompts. The system gets smarter over time.

The Stack

Python 3.13, FastAPI, SQLAlchemy 2 async, Celery
Next.js 16, TypeScript, TanStack Query
AI quality ladder (Ollama → Haiku), RAG, pgvector
1Password secrets, Redis rate limiting

This post was cross-posted using the pipeline described above.

DEV Community: Yonyon

OrchestKit scored 83/100 on ORA — what "agent-readiness" actually measures

The breakdown

What I take from it

Making your docs site agent-readable: llms.txt, MCP, and the .well-known files that actually matter

1. llms.txt — the agent's table of contents

2. Markdown content negotiation

3. An OpenAPI spec for your read APIs

4. An MCP server

5. The .well-known identity files

6. JSON-LD that an entity graph can reconcile

7. Tell crawlers the truth in robots.txt

How to verify

I made my portfolio readable by AI agents. A scanner found four things that didn't exist

1. The "helpful" GET that made my endpoint read as missing

2. The WebMCP tools nobody could see

3. The status page that 404'd in production only

4. ai-train=yes, on purpose

The pattern under all four

How I made my website fully agent-readable: an MCP server + NLWeb /ask in Next.js

How I made my website fully agent-readable: an MCP server + NLWeb /ask in Next.js

The trap: locale routing eats your agent endpoints

A dependency-free MCP server

Discovery: llms.txt + .well-known

The payoff

Building an Automated Content Pipeline That Posts to 6 Platforms

The Architecture

The Platform Adapter Pattern

Smart Content Composition

The Quality Ladder

The Feedback Loop

The Stack

1. `llms.txt` — the agent's table of contents

5. The `.well-known` identity files

7. Tell crawlers the truth in `robots.txt`

4. `ai-train=yes`, on purpose