Claygent Prompt Builder — MVP Spec

spec.md

Claygent Prompt Builder — MVP Spec

What is this?

A Claude Code project that helps you write, test, and improve Claygent prompts through an automated feedback loop. You describe what data you want to extract from company websites, it drafts a prompt, sends it to Clay, evaluates the results, and iterates until the prompt is good.

Why does this need to exist?

Writing Claygent prompts is trial and error. You write a prompt, run it in Clay, eyeball the results, tweak, repeat. This is slow and subjective. The value here is:

1. Structured evaluation — a scoring rubric replaces "looks good to me"
2. Automated iteration — Claude sees the results and rewrites the prompt itself
3. Pattern library — proven prompt structures for common enrichment tasks

Core Loop

You describe what you want
        ↓
Claude drafts a prompt (using patterns + references)
        ↓
Claude sends test rows to Clay via webhook
        ↓
Clay runs the Claygent on each row
        ↓
You paste results back into the conversation
        ↓
Claude scores results against a 7-dimension rubric
        ↓
Score < 8.0? → Claude rewrites prompt, sends again
Score ≥ 8.0? → Done. Prompt saved to project folder.

What the user provides

1. A Clay workspace with the pre-built template copied in (webhook → Claygent → JSON parse chain)
2. The webhook URL from that template
3. What they want to find — e.g., "detect what CRM a company uses" or "find the CEO's email"
4. 3-5 test domains — companies to test against
5. Results — copy-paste Claygent output from Clay back into the conversation after each batch

What Claude does

Phase 1: Discovery

Ask 3-5 questions to understand:

• What data they want to extract
• What input data they have (just domains? LinkedIn URLs? company names?)
• What "good" looks like (expected outputs for known companies)
• Edge cases (company types, industries, sizes)

Phase 2: Draft Prompt

Using the pattern library and reference material:

• Pick the best pattern (or combine patterns) for the task
• Write a v1.0 prompt with clear instructions, JSON schema, confidence scoring
• Include failure handling (what to return when data isn't findable)

Phase 3: Test

• Send test rows to Clay webhook via curl
• Each payload includes: row_id, prompt, prompt_version, change_log, callback_url, reference_json_text
• Tell user to watch Clay table and paste back the results

Phase 4: Evaluate

Score each result across 7 dimensions:

• Accuracy (25%) — is the extracted data correct?
• Completeness (25%) — did it find everything findable?
• JSON Validity (15%) — does the output match the schema?
• Source Quality (15%) — did it use reliable sources?
• Step Efficiency (10%) — did it take a reasonable path?
• Consistency (5%) — same inputs → same outputs?
• Error Handling (5%) — graceful failures, not hallucinations?

Calculate weighted overall score. Show per-row breakdown.

Phase 5: Iterate

If score < 8.0:

• Identify the weakest dimensions
• Rewrite the prompt targeting those weaknesses
• Bump version (v1.0 → v1.1)
• Log what changed
• Send the same test rows again
• Repeat until 8.0+

Phase 6: Save

• Save final prompt to projects/{project-name}/prompts/v{final}.md
• Save test results to projects/{project-name}/results/
• Save the JSON schema separately for easy copy-paste into Clay

File Structure

projects/
└── {project-name}/
    ├── prompts/
    │   ├── v1.0.md          # First draft
    │   ├── v1.1.md          # After first iteration
    │   └── v1.2.md          # Production version
    ├── results/
    │   ├── v1.0-results.json
    │   └── v1.1-results.json
    ├── schema.json           # Final JSON schema for Clay
    └── test-domains.json     # The test rows used

Reference Material (bundled in repo)

File	What it is
references/patterns.md	9 proven prompt patterns (business model classification, platform detection, CRM validation, etc.)
references/rubric.md	The 7-dimension scoring rubric with detailed per-score criteria
references/best-practices.md	Prompt engineering rules (3-task max, always require JSON, name sources, handle failures)
references/clay-json-rules.md	Clay's JSON schema constraints (what's valid, nesting limits, enum limits)
references/examples/	3 worked examples showing v1→v2 iteration with real scores

What's NOT in the MVP

• No licensing/auth — it's a local Claude Code project
• No Supabase — user pastes results manually
• No content API — reference material is local files
• No native integration checker — can add later
• No webhook server — Clay's output is right there in the table
• No setup ceremony — just start building

Future additions (not now)

• Automated callback: Supabase Edge Function so Claude can poll for results instead of manual paste
• Native integration check: Before building a Claygent, check if Clay already does it natively
• Batch testing: Send 20+ rows and aggregate scores
• Prompt versioning UI: Compare versions side-by-side
• Template gallery: Pre-built Claygents for common tasks