Micro-Tool Website Playbook
End-to-end guide — idea to AdSense approval — using AstroJS, Cloudflare Pages, and AI coding agents. Follow each step in order.
Primary tools for building and deploying micro-tool websites. Install at least one AI coding agent before starting.
AI agents are trained on documentation — but docs go stale fast. When you use a package like zod, drizzle, or astro, the agent often hallucinates function names, wrong argument shapes, or APIs that were removed in the latest version. opensrc solves this by putting the actual source code on disk so the agent can search it instead of guessing.
The agent calls a function that doesn't exist in the package
Docs are weak, stale, or too abstract for what you need
You're integrating a fast-moving SDK (AstroJS integrations, Drizzle ORM, etc.)
The agent keeps installing alternative packages instead of finding the right API
You want the agent to follow the package's actual internal patterns, not examples from 2022
npm install -g opensrc
# Fetch + cache a package (instant on repeat runs)
opensrc path zod
# Search a package's source with ripgrep
rg "parse" $(opensrc path zod)
# Read a specific file directly
cat $(opensrc path zod)/src/types.ts
# Works with any registry (npm, pypi, etc.)
find $(opensrc path pypi:requests) -name "*.py"
After fetching, put the path in your AGENTS.md or tell the agent directly. The key insight: don't paste the source into chat — let the agent search it on disk.
When working with zod, reference the local source under: `$(opensrc path zod)` Do not guess API names. Search the source first, then implement.
Build a form validation module using zod. Before coding: 1. Search `$(opensrc path zod)/src` for the correct schema API and .parse() patterns. 2. Note which files/functions you used as reference. 3. Implement only the minimal validation function. 4. Keep the diff small. 5. Tell me which source files you looked at.
Context window limit. Full docs = thousands of tokens. On-disk search = zero tokens until the agent reads what it needs.
Docs lie. README examples often use old APIs. Source code is always current.
Types don't lie either. TypeScript .d.ts files show exact function signatures — more reliable than any example.
opensrc path fetches on first use, then returns the cached path instantly. Pair it with the Source Code Context agent skill in the workflows section below.
Install these before starting any project. Skills give your AI agent specialized knowledge it doesn't have by default.
Vercel's design system — consistent, professional UI patterns.
npx skills add vercel-labs/agent-skills --skill web-design-guidelinesAgents know v3 well but struggle with v4 — this fixes that.
npx skills add Lombiq/Tailwind-Agent-SkillsAesthetic direction and visual identity for distinctive UI.
npx skills add anthropics/skills --skill frontend-designLatest AstroJS docs via MCP for accurate syntax.
skills.sh/astrolicious/agent-skills/astroEnd-to-end framework for building with AI agents. Harness selection, context management, and loop refinement.
npx skills add ./skills/agentic-engineering-workflowSeparates orchestration actions from reusable operations. Keeps code clean and avoids AI duplication.
npx skills add ./skills/code-structure-cleanupAuto-research PR-fix loop. Iteratively resolves review feedback and runs tests until clean.
npx skills add ./skills/grep-loop-review-workflowSupplies local repository references to stop AI hallucination and ensure correct SDK usage.
npx skills add ./skills/source-code-contextDramatically improves AI-generated UI quality. Creates a design token file the agent references.
npx getdesign@latest add vercel
When your agent hallucinates function names, give it real source code. Put the repo in a reference folder and add an instruction to AGENTS.md.
When working with [library/tool], reference the local source under: `reference/repos/github.com/company/project`. Do not guess API names. Search the source first, then implement.
Build [feature]. We use [library/tool]. Before coding: 1. Search `reference/repos/github.com/company/project` for the correct API and patterns. 2. Identify the files/functions/examples you used as reference. 3. Implement only the minimal service function and one calling route/component. 4. Keep the diff small. 5. Explain which source files you referenced.
Place in project root. The agent reads this first at the start of every session. This is the single most important file for agent behavior.
Always Use: - astro, tailwind-4-docs, web-design-guidelines (these 3 skills every project) - DESIGN.md for this project's visual design Install MCPs for your tech stack before starting. Start new sessions frequently. Always use git — commit after each working milestone.
The hardest step. You need a small, specific problem with no great existing solution.
Affects you personally or someone you know
Seems small — less competition, easier to rank
No great existing tool solving it properly
Notice what you search for and can't find a good answer to
Reddit complaints in relevant subreddits
Quora questions with weak or no answers
Ask Claude/Gemini: "What small everyday problems could be solved with a simple web tool?"
Look at existing tools and note every weakness
Google your keyword — check first 4 pages. Government site or Quora on page 4 = goldmine opportunity.
Note every weakness in the top results
Write down what your tool will do better
Validate search volume before building anything. Tool: Ahrefs Free Keyword Generator
Enter your main keyword — even 1,000 monthly US searches is enough
Questions tab — copy all FAQs. These become your FAQ section later.
Related terms tab — find supporting keywords for your SEO content
Type keyword in Google + Space — autocomplete = real searches from real users
Domain is a ranking factor. Tool: Instant Domain Search
.com only — no exceptions. .com ranks easiest and is most trusted.
Primary keyword must appear in the domain
Shorter is better, but keyword presence matters more than length
No hyphens
One-time install. Do this before writing any code.
Git — version control (commit after every working milestone)
VS Code — code editor
Node.js — required to run AstroJS
Claude Code / Cursor / Gemini CLI — AI coding agent
npm create astro@latest .
# Press Enter for all defaults
# Choose "Basic" template
# Say Yes to initialize Git
npx getdesign@latest add vercel
Paste this prompt in your AI coding agent. It will analyze the competitor and start building.
I have initialized a new AstroJS project. Use the astro-docs MCP, tailwind-4-docs skill, and web-design-guidelines skill. Also use @DESIGN.md. Keep the design like Vercel. Name: [Your Tool Name] Domain: [yourdomain.com] Create a [describe your tool]. My competitor is [URL] — go to this website, analyze it, identify weaknesses, and build a better version. Do not copy the competitor's design or UI. Use MPA architecture for best SEO.
npm run dev
Dark mode toggle
Mobile responsiveness — test via Chrome DevTools mobile icon
Multiple language support — separate URL paths = international SEO
Run in a fresh session after /clear.
Do the on-page SEO of this website for: Main Keyword: [your keyword] Supporting Keywords: [comma-separated list from Ahrefs] Also add proper OG meta tags. Write 600 words about the tool on the home page for SEO.
<title> tag contains your primary keyword<meta description> under 160 chars, contains keywordalt attributes/online-ruler not /page?id=123Drives long-tail traffic and can trigger Google rich results (higher click-through rates).
Add an SEO-friendly FAQ section using JSON-LD structured data for these questions: [paste questions from Ahrefs "Questions" tab + Google "People Also Ask"] Use FAQ JSON-LD schema with @type: FAQPage and Question/Answer pairs.
AdSense rejects sites without these four pages. Generate all at once.
Create these pages as separate MPA routes for best SEO: - Privacy Policy - Terms & Conditions - About Us - Contact Us Make them visible and linked in the home page footer and header. This should be a multi-page application (MPA) for best SEO.
npx wrangler login
Then tell your AI agent: "Deploy this to Cloudflare Pages and add a deploy command to package.json."
npm run deploy
Add a _headers file in /public to stop Google indexing your .pages.dev domain:
https://yoursite.pages.dev/* X-Robots-Tag: noindex
X-Robots-Tag: noindex should appear on .pages.dev but NOT on your .com domain.
Cloudflare → Domains → Add a Domain → select free plan
Delete all existing DNS records
Add A record: Name @, Value 8.8.8.8 (placeholder)
Copy the two Cloudflare nameservers provided
Go to your registrar → update nameservers → wait 10–30 min
Workers & Pages → your project → Settings → Custom Domains → add domain
Repeat for the www version. Both go live within 15 min.
Google Search Console — add domain property, verify via TXT DNS record, submit sitemap.xml, request indexing on homepage
Bing Webmaster Tools — sign in with Google, import from GSC, submit URL for indexing
Wait until you have at least 10 daily users consistently (Google Analytics → Real-time).
Go to adsense.google.com ? Add your site
Paste AdSense snippet via AI agent: "Add this AdSense script to the site header" ? deploy
Verify ownership via ads.txt (agent creates this)
Click Request Review — takes days to weeks
Once approved, enable Auto Ads
CRITICAL CONTEXT COMPRESSION: Summarize our entire session up to this point. Include: 1) The overarching goal, 2) Key technical decisions made, 3) Files modified and current state, and 4) The exact next steps required. Format as a dense, context-rich prompt I can paste into a new session to instantly resume. Output ONLY the summary prompt, nothing else.
We are building using an agentic engineering workflow. Rules: 1. Keep the change small and reviewable. 2. Search existing code before creating new abstractions. 3. If using a package/framework, reference its source or official repo before guessing APIs. 4. Build the minimal working version first. 5. After it works, run a code-structure cleanup pass. 6. Run relevant tests/typechecks. 7. Summarize what changed, what was tested, and what needs human judgment. Task: [describe the feature or fix here]
System-level workflow skills from your local skills/ directory. These are reusable operating patterns for every AI coding session — read them once, apply them always.
🔄 Skill 1 · Agentic Engineering Workflow
The high-level operating system for building with AI agents. This is not "ask the AI to build everything and hope." The human decides the outcome, the agent does mechanical work, tests and reviews keep it honest.
1. Pick the strongest harness/model you can access. The harness is the wrapper around the model: file search, terminal, browser, tools, system prompt, and project memory. The model matters, but the harness determines what the model can actually do.
2. Keep the task small. Ask for one feature, one fix, or one reviewable unit at a time. If a plan is too large, ask the agent to split it into PR-sized chunks first.
3. Give source code as context when docs are not enough. If you're using a package, SDK, or open-source tool, put its source in a reference folder and tell the agent to search it before coding. Use opensrc for npm packages.
4. Build the minimal feature first. Do not refactor the whole app while building the feature. Get the smallest working version running before anything else.
5. Run a cleanup pass. After the feature works, ask the agent to find duplicated runtime mechanics and move them into reusable service-layer modules.
6. Run a review-fix loop. Use tests, typechecks, and AI/human review. Feed review feedback back into the coding agent. Keep fixing until the PR is clean or a human decision is needed.
7. Launch earlier than feels comfortable. A semi-functional MVP with user feedback beats a perfect private project. Competitors ship while you polish.
8. Apply security guardrails. Use 2FA, a password manager, avoid young packages, and ask your agent to check if your project is exposed when a package breach trends.
We are going to build this using an agentic engineering workflow. Rules: 1. Keep the change small and reviewable. 2. Search the existing code before creating new abstractions. 3. If using a package/framework, reference its local source or official repo before guessing APIs. 4. Build the minimal working version first. 5. After it works, run a code-structure cleanup pass. 6. Run relevant tests/typechecks. 7. Summarize what changed, what was tested, and what still needs human judgment. Task: <describe the feature or fix here>
🧹 Skill 2 · Service Layer & Code Structure Cleanup
Two-layer separation: Actions orchestrate domain rules (the "why/when"), while a service layer centralizes reusable operational mechanics (the "how"). This prevents duplicated code, inconsistent behavior, and bugs fixed in one path but not others.
Orchestration Layer (Actions) Service Layer (Shared Mechanics)
├── owns business rules ├── owns reusable operations
├── owns state transitions ├── owns provider/SDK interactions
├── owns auth/ownership checks ├── owns command execution details
├── owns failure classification ├── owns health checks / readiness
├── owns retries / user-facing errors └── returns structured results
└── calls service functions
"What this product flow means" → keep in actions/routes
"How to do this operation reliably" → move to service layer
// ✅ Good: composable capability blocks — each caller picks what it needs
createManag edSandbox(...) // one job
prepareRepo(...) // one job
detectPackageManager(...) // one job
installDependencies(...) // one job
// Each function:
// - accepts explicit params (no hidden global state)
// - returns structured output: { ready, previewUrl, port }
// - never reads from database directly
// - makes failure explicit (no silent swallowed errors)
The feature is working. Now do a code-structure cleanup pass. Goal: - Find duplicated runtime mechanics, repeated API calls, repeated parsing, repeated validation, or repeated business logic. - Move repeated mechanics into reusable service-layer functions/modules. - Keep domain policy in the calling route/action/component. - Do not change user-facing behavior. - Keep the diff small. Process: 1. Inspect the files touched by the feature. 2. Identify repeated logic and name the duplication clearly. 3. Propose the smallest service-layer extraction. 4. Implement it. 5. Run the relevant tests/typechecks. 6. Summarize exactly what got simpler.
Write the flow in action code first (clear behavior)
Mark repeated operational chunks across callers
Extract only repeated, non-domain chunks to service
Replace one caller → verify → replace remaining callers
Keep domain policy in actions (auth, status transitions, error classification)
Run verification: typecheck, lint, confirm all flows still work
🔁 Skill 3 · Grep Loop Review Workflow
An auto-research-style loop for code review: create small PR → let a review tool or human inspect it → feed review back to the coding agent → agent fixes → review again → repeat until clean.
Is this PR too large for a reliable review loop? If yes, suggest how to split it.
Run a review-fix loop for this PR. Inputs: - Current branch: <branch-name> - Review feedback: <paste feedback or point to reviewer output> - Required end state: tests pass, reviewer issues resolved, no unrelated rewrites. Rules: 1. Read the PR diff first. 2. Read the review feedback. 3. Fix only issues that are real and relevant to this PR. 4. Add or update tests for each bug fix when possible. 5. Run the relevant tests/typechecks. 6. Commit/push the fix if this workflow is allowed to push. 7. Stop only when the PR is clean or when blocked by a decision that needs a human.
📂 Skill 4 · Source Code as Agent Context
Code is often the best source of truth. Docs can be outdated, examples can be incomplete, and blog posts lag behind the current API. When an agent has access to the actual repo source, it can search for real function names, types, examples, and edge cases. Use this skill to stop the agent from guessing.
Identify the package/repo you're using
Add the repo source into a clearly named folder: reference/repos/github.com/company/project — or use opensrc path <package> for npm packages
Add a short instruction in AGENTS.md, CLAUDE.md, or your harness memory (see prompt below)
When working with <library/tool>, reference the local source under: `reference/repos/github.com/company/project`. Do not guess API names. Search the source first, then implement.
Build <feature>. We use <library/tool>. Before coding: 1. Search `reference/repos/github.com/company/project` for the correct API and patterns. 2. Identify the files/functions/examples you used as reference. 3. Implement only the minimal service function and one calling route/component. 4. Keep the diff small. 5. Explain which source files you referenced.
We need to integrate Daytona sandboxes into this app. Reference the local Daytona source under `reference/repos/github.com/daytonaio/daytona`. Find the current SDK pattern for creating a sandbox and running a command. Then implement only the minimal service function and one calling route.
Go through this list before considering your site ready. Every item is non-negotiable for AdSense approval.
SEO drives free organic traffic. AdSense places ads. Zero marginal cost — build once, earn forever.
1 tool, 1,000 daily US visitors
10–15 tools with traffic
first meaningful ranking
Pure static HTML — best output for search crawlers
No JS hydration overhead on non-interactive pages
Perfect Core Web Vitals out of the box
MPA architecture — far better for SEO than SPAs
Cloudflare acquired Astro — native CDN support globally
Built for fast execution. Ship more, overthink less.