---
title: "Making Your Product Agent Self-Serve"
description: "The implementation playbook: Agent Skills, MCP servers, agent-ready docs, programmatic signup, and removing human gates. Week-by-week from zero to agent self-serve."
author: Katrina Laszlo
url: https://katrinalaszlo.com/notebook/agent-self-serve
---

# Making Your Product Agent Self-Serve

> A sequence for adding agent access, with examples and checks for each stage.

## The Agent Buyer Journey

> Eight steps between "agent discovers your product" and "agent pays for it."

An agent needs a usable path through each step below. Check where it can proceed on its own and where it needs the human to take over.

1### Discover

Agent finds the product exists. llms.txt, AgentReady scoring, search APIs.

2### Learn

Agent understands what it does. Docs, pricing, capabilities in machine-readable format.

3### Evaluate

Agent compares against alternatives. Needs structured, normalized data.

4### Ask questions

Agent clarifies specifics. MCP-accessible knowledge base, agent-to-agent Q&A.

5### Try

Agent tests the product. Instant sandbox, no auth required, API keys on demand.

6### Sign up

Agent creates an account. Programmatic signup, no CAPTCHA, no email loop.

7### Integrate

Agent builds with it. AGENTS.md, MCP server, agent-optimized docs.

8### Pay

Agent purchases. Machine-readable pricing, programmatic checkout.

## Agent Skills

> Teach agents how to use your product. A directory with a SKILL.md file.

The Agent Skills spec (Anthropic, Oct 2025, open-sourced Dec 2025) is the standard for giving agents domain expertise about your product. Adopted by Claude Code, Codex CLI, Gemini CLI, Cursor, and others.

A skill is a directory:

your-product/
SKILL.md          # Required: YAML frontmatter + instructions
references/       # Optional: detailed docs loaded on demand
scripts/          # Optional: executable code
assets/           # Optional: templates, data files

**Progressive disclosure** loads instructions as needed, in three tiers:

| Tier | Tokens | When loaded |
| --- | --- | --- |
| Metadata (name + description) | ~100 | At startup, for ALL installed skills |
| Instructions (SKILL.md body) | <5,000 | When the agent activates the skill |
| References (files in references/) | Unlimited | On demand, when the agent needs detail |

> **The single most important rule:** Trigger context must be in the description frontmatter, not the body. The body only loads after activation, so if the trigger keywords are in the body, the agent will never know to activate the skill. Supabase's description lists every product, library, framework, and keyword an agent might encounter.

### Who does this well

### Supabase

Two-tier: one catch-all skill + one deep-dive per domain. 30+ reference files with `impact: CRITICAL|HIGH|MEDIUM|LOW` frontmatter so agents prioritize which references to load. CI validation on every PR.

### Stripe

Decision-routing table mapping use cases to APIs to reference files. Hard constraints up front ("Never include payment_method_types"). Published benchmarks proving skill-guided agents outperform raw agents.

Generate a starting point from your OpenAPI spec: `npx openapi-to-skills ./openapi.yaml -o ./output`. Then hand-edit. Install skills with: `npx skills add https://github.com/your-org/repo`.

## MCP Server

> Give agents tools to take action in your product.

An MCP (Model Context Protocol) server exposes your product's capabilities as structured tools. The agent discovers available tools, calls them, and gets structured responses. Three distribution models:

| Model | How it works | Who does this |
| --- | --- | --- |
| Remote hosted | You host an endpoint (Streamable HTTP). Agents connect over HTTPS. | Stripe (mcp.stripe.com) |
| npm package | Users run locally via `npx @your-org/mcp` | Linear, most OSS servers |
| Both | Remote for production, local for dev | Stripe (the gold standard) |

### Tool Design (Anthropic ACI)

Tool descriptions are the agent's UI. Every word in the name, description, and parameter docs shapes how agents understand and use the tool.

| Rule | Do this |
| --- | --- |
| Namespace tools | `customers.create`, not `create` |
| Search, not list | Never expose "list all." Force search/filter. |
| Response format | Add `response_format` enum: "concise" (~500 tokens) or "detailed" (~2000 tokens) |
| Cap output | Max ~25k tokens. Paginate with clear "next page" guidance. |
| Say when NOT to use | Include expected latency, rate limits, and alternative tools in the description. |
| Unambiguous names | `customer_id` not `customer`. `thread_id` not `id`. |
| Actionable errors | "Not authorized for conversation 'abc'. Request access from owner or use a different thread_id." |

### Discovery

Serve a Server Card at `/.well-known/mcp-server-card` (SEP-2127, Draft). Register on the official MCP Registry. Submit to directories: PulseMCP (14.8k+ servers), Glama (21k+), Smithery (7k+). Publish to npm for local dev installs.

> **Auth pattern:** OAuth 2.1 + PKCE for remote servers (spec-mandated). API key fallback for developer convenience. Use restricted/scoped keys to control which tools each key can access. Stripe does exactly this.

## Agent-Ready Docs

> Same content, stripped of presentation noise.

### llms.txt

A markdown file at `/llms.txt`. H1 with product name, blockquote summary, H2 sections with link lists. Start with the docs an agent needs for one task.

# Observe

> AI cost observability. See which customers and features are unprofitable.

## Docs
- [Getting Started](https://docs.observe.tansohq.com/quickstart): Setup in 5 minutes
- [API Reference](https://docs.observe.tansohq.com/api): REST API endpoints
- [Billing Models](https://docs.observe.tansohq.com/billing): Usage tracking setup

## Optional
- [Changelog](https://docs.observe.tansohq.com/changelog): Release history

### More doc layers, by effort

| What | Effort | Impact |
| --- | --- | --- |
| AGENTS.md in repo root | 30 min | Every coding agent reads it on project open |
| llms.txt at domain root | 30 min | LLMs discover your docs exist |
| .md URL suffix (Stripe pattern) | 1 hour | Every doc page available as clean markdown |
| llms-full.txt (all docs concatenated) | Half day | RAG pipelines and IDE indexing |
| "Copy as Markdown" button | Half day | Anyone using an LLM to integrate your product |
| Content negotiation (Accept: text/markdown) | 1-2 days | Agents get markdown automatically on every page |
| OpenAPI spec at /openapi.json | Varies | Agents discover API capabilities on the fly |

> **Quality test:** Netlify tests doc quality by whether an agent can single-shot the feature from the markdown alone. Write the doc, hand it to an agent with no other context, see if the agent ships working code. If not, the doc needs work. One caveat: LLM-generated AGENTS.md files hurt success rates. Developer-written, minimal, precise files help.

## Removing Human Gates

> Human-only steps interrupt an agent's workflow.

GateWhy it blocks agentsFix

CAPTCHA
AI solves reCAPTCHA v2 at 100%. Stops humans, not bots.
Web Bot Auth (IETF draft). Cryptographic identity, not puzzles.

Email verification
Agents don't have inboxes.
API key auth for machine clients. Verify on claim, not signup.

"Book a demo"
Hard wall. No programmatic path.
Self-serve sandbox + usage-based upgrade. Demo for enterprise only.

Credit card required
Agents can't enter payment info.
Free tier or trial with claim flow. Monetize after value is proven.

Phone/SMS
Agents don't have phones.
Skip for API-only access. Add for human-facing upgrades.

### The Deploy-First-Claim-Later Pattern

### Netlify

`netlify deploy --allow-anonymous` creates a live site with no account. Generates a claim URL. Human has 1 hour to claim ownership. The deploy-and-claim pattern: provision first, authenticate later.

### Prisma

`npx create-db@latest` provisions a Postgres database instantly. No auth required. Lives 24 hours. Claim URL makes it permanent for free. Management API enables programmatic provisioning.

> **The scoping problem:** A 2026 audit found 93% of AI agent projects use unscoped API keys. No scope narrowing, no depth limits, no cascade revocation. Ship scoped, short-lived tokens from day one. The fix: restricted keys that control which tools/endpoints each key can access, with automatic expiry.

## Implementation Timeline

> Ordered by effort and impact. Start at week 1.

Week 1

### Zero code changes

Audit robots.txt (remove blanket Disallow for agents). Add Content-Signal directives (search=yes, ai-input=yes, ai-train=no). Create llms.txt. Add Link headers for llms.txt, sitemap, skills index. Run isitagentready.com + Lighthouse agentic browsing audit. Fix what they flag.

Week 2-3

### Auth + provisioning

Add API-key-based signup path (POST /api/signup, returns key, no UI required). Ship M2M token endpoint for service-to-service auth. Build /v1/sandboxes endpoint (returns scoped credentials + TTL, no signup gate). Implement claim flow (sandbox to claim URL to permanent account). Remove CAPTCHA from API paths. Remove email verification for API-only access.

Week 4

### Agent UX polish

Annotate key forms with WebMCP attributes (toolname, tooldescription, toolautosubmit). Serve markdown variants on Accept: text/markdown. Publish Agent Skills (SKILL.md + references/). Add "Copy as Markdown" button to docs.

Week 5+

### Full agent surface

Publish MCP server (remote + npm). Serve Server Card at .well-known/mcp-server-card. Register on MCP Registry + directories. Publish skills index at .well-known/agent-skills/index.json. Monitor agent traffic separately from human traffic.

## Validation Tools

> Measure where you are. Rescan after every change.

| Tool | What it checks | Format |
| --- | --- | --- |
| isitagentready.com | Discovery, content, bot access, capabilities, commerce | 0-100 score |
| agent-ready.dev | 15 site-wide + 23 per-page checks (Vercel Agent Readability Spec) | Pass/fail checklist |
| Lighthouse Agentic Browsing | WebMCP, accessibility tree, layout stability, llms.txt | Pass/fail ratio |
| orank (ora.run) | Broad agent readiness across 9 sectors | A-F grade + numeric |
| agentic-seo CLI | llms.txt, robot blocking, token counts, markdown availability | CLI report |

> **The loop:** Scan. Fix the easiest items. Rescan. Repeat. Each iteration is measurable. Week 1 items (robots.txt, llms.txt, Link headers) can move you from D to C in an afternoon. Auth + provisioning (weeks 2-3) is what separates "discoverable" from "usable." MCP + skills (weeks 4-5) is what separates "usable" from "self-serve."

> **Sources:** Agent Skills spec (agentskills.io), Cloudflare Skills Discovery RFC, Anthropic ACI framework, MCP spec (SEP-2127), Stripe/Supabase/Netlify public implementations, Clerk M2M docs, Prisma create-db, Vercel Agent Readability Spec, Lighthouse Agentic Browsing, Content Signals spec, Web Bot Auth (IETF draft), Grantex State of Agent Security 2026.