agentleFS
len5kylen5ky/synth-personas/.agents/skills/synth-personas/SKILL.md

synth-personas

Skill40 starsChanged 6 months agoMITView on GitHub

Drive parallel persona-based feedback against a user-supplied artifact (usually a markdown file: pitch, proposal, design doc). Each persona returns scored rubric judgments + freeform reactions; an aggregator writes a single report.md. - User has an artifact (markdown file: pitch, proposal, design doc, white paper) AND - Wants reactions or scored feedback across many simulated viewpoints (panel of VCs / tech media / billionaires / scientists / etc.). The user needs an OpenRouter API key set in OPENROUTER_API_KEY. If it isn't…

  • Reads credentials
  • Installs packages

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Always do a 3-persona run first to verify output quality and cost.

    line 104
  2. Distinctive:

    Always confirm with the user before a full run if N > 20.

    line 127

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

synth-personas

Drive parallel persona-based feedback against a user-supplied artifact (usually a markdown file: pitch, proposal, design doc). Each persona returns scored rubric judgments + freeform reactions; an aggregator writes a single report.md.

When to use

  • User has an artifact (markdown file: pitch, proposal, design doc, white paper) AND
  • Wants reactions or scored feedback across many simulated viewpoints (panel of VCs / tech media / billionaires / scientists / etc.).

When not to use

  • Single-persona roleplay ("write as Elon Musk would")
  • General critique with no rubric or panel framing
  • Feedback on code, PRs, or content that's not a pitch-style artifact

Prerequisites

The user needs an OpenRouter API key set in OPENROUTER_API_KEY. If it isn't set, prompt them to create one at https://openrouter.ai/ before the run step.

export OPENROUTER_API_KEY=...

The synth-personas binary should already be on PATH (installed globally via npm i -g @sociosim/synth-personas-cli). If not, install it before continuing.

Workflow

1. Discover available personas (free, no API calls)

synth-personas list-personas
synth-personas list-personas --category vcs
synth-personas list-personas --category billionaires

Categories shipped: billionaires, vcs, media, podcasters, scientists, public_intellectuals, dev_audience.

2. Author an evaluation task

A task is a YAML file with a rubric (3-6 named criteria, 1-10 scales), a persona selection (by category / slug / tag), and the artifact path. Reference the included evaluations/moonshot.yaml as a template.

Minimal shape:

name: my-pitch
artifact:
  path: ./pitch.md
  kind: pitch_deck
  title: My Pitch
rubric:
  - name: novelty
    description: How new is this idea?
    scale: [1, 10]
  - name: feasibility
    description: How realistic is execution?
    scale: [1, 10]
persona_selection:
  categories: [vcs, billionaires]
  limit: 20
model:
  default: anthropic/claude-sonnet-4
output:
  dir: ./runs

The rubric is the load-bearing part. Propose 3-6 criteria, confirm with the user, then write the YAML.

3. Validate before running (free)

synth-personas validate-task ./my-task.yaml
synth-personas show-prompt ./my-task.yaml --persona-slug elon-musk

show-prompt renders the exact prompts so the user can sanity-check before spending tokens.

4. Dev-mode run with --limit

Always do a 3-persona run first to verify output quality and cost.

synth-personas run ./my-task.yaml --limit 3

5. Full run (only after dev-mode passes and user confirms)

synth-personas run ./my-task.yaml

Output: <output.dir>/<UTC-timestamp>-<task-name>/report.md + per-persona JSON under personas/.

Cost awareness

A full run = N personas × ~2k output tokens. At 80 personas:

  • Sonnet-class: ~$1-3
  • Opus: ~$5-15
  • Haiku / Gemini Flash: <$1

Always confirm with the user before a full run if N > 20.

Persona library

Bundled with the package. Inspect with list-personas. The persona library covers tech billionaires (Musk, Bezos, Gates, Altman, …), VC partners, tech media (Mossberg, Newton, Patel, …), podcasters (Fridman, …), scientists (Hassabis, …), public intellectuals (Cowen, …), and developer audiences (HN skeptic, indie hacker, ML research engineer, …).

To add a custom persona, point --personas-root at your own directory of markdown files (same schema as the bundled ones — see _TEMPLATE.md in the bundled persona library, or in the public repo at https://github.com/len5ky/synth-personas).

Re-aggregating an existing run

synth-personas aggregate ./runs/<run-dir>/

Useful if a run was interrupted or you want to regenerate the report without re-spending tokens.

Failure handling

  • Persona refusals (As an AI, I can't roleplay…) are detected, logged as <slug>.error.json, and excluded from numerical aggregation but listed in the report's failures section.
  • Each persona's JSON is streamed to disk as it returns — Ctrl-C or partial failures leave usable output, and aggregate re-runs against whatever's on disk.

Checklist

  • OPENROUTER_API_KEY is set
  • User's artifact exists and is markdown
  • Task YAML written and validated
  • Prompt sanity-checked with show-prompt
  • Dev-mode --limit 3 run completed; output looks reasonable
  • User confirmed before full run if N > 20
  • report.md reviewed and highlights surfaced to the user

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.