Write criteria that find the right people

Every role in AyHire has its own criteria: the few things the person needs, each marked with how much it matters. AyHire judges everyone the role finds against them, from their public work, and its call on who to talk to first rests on those judgements. Of everything you can change on a role, the criteria change the result most.

This guide covers where criteria live, how to write ones that public work can show, what to leave out, and what happens after you change them.

Where criteria live

Open a role. Below AyHire's call, open What this role needs: it lists the criteria, each with its importance. When you create a role, AyHire suggests criteria from the title and brief, so you never start from a blank page. Treat the suggestion as a first draft.

• Edit criteria opens the list for editing (it says Add criteria when there are none yet). Each criterion has a short name, how much it matters, and a field called What good evidence looks like.
• Add a criterion adds a row. A role can have up to 8.
• Suggest from the brief asks AyHire for a fresh suggestion. It opens in the editor, so nothing changes until you save.
• Save criteria keeps your changes.

Your agent can do the same over MCP: set_role_criteria replaces a role's criteria, and the web app shows the same list.

How much each one matters

Each criterion is one of three:

• Must have: a real requirement. The role isn't filled without it.
• Important: counts for a lot, but someone could still be right without it.
• Nice to have: a bonus.

People are ordered by how much evidence of fit their public work shows. A must-have weighs the most and a nice-to-have the least. Keep must-haves to one or two: each one is something AyHire has to see clearly before it tells you who to talk to first.

Write what public work can show

AyHire judges from public GitHub work: repos, READMEs, commits, pull requests and work on other people's projects. A criterion that public work can't show comes back unknown for almost everyone, and an unknown tells you nothing.

So name the work, not an adjective. Then use What good evidence looks like to say, in one sentence, what would count. AyHire reads that sentence when it judges, so be specific: the kind of project, the tools, or the sort of contribution you would accept.

Weak criteria, made better

Take a role for a senior Rust engineer at a company building a database. Here is what a first draft often says, and what works better.

“Strong Rust skills”

Every Rust engineer would claim it, and it doesn't say what to look for. Better:

Writes production Rust · Must have

What good evidence looks like: A meaningful share of their public work is Rust, in their own crates or in merged pull requests to Rust projects other people use.

“Database experience”

Too broad. Using a database and building one are different jobs. Better:

Storage engine internals · Must have

What good evidence looks like: Has built or contributed to a storage engine, write-ahead log, B-tree or LSM tree, in their own repos or someone else's.

“Passionate about performance”

Passion can't be read from a repo. Work that made something faster can. Better:

Measures performance · Important

What good evidence looks like: Benchmarks, profiling, or pull requests that make something measurably faster, with the numbers in the description.

“Great communicator”

How someone talks in a meeting isn't public. How they explain their work often is. Better:

Explains their work · Nice to have

What good evidence looks like: READMEs that say what a project does and how to run it, and pull requests that explain the decision, not just the change.

“8+ years of experience”

GitHub doesn't show years in a job, and a long history isn't the same as the work you need. Better:

Maintains a project over time · Important

What good evidence looks like: Has kept a project working for a year or more, with releases, fixed issues and reviews of other people's pull requests.

The finished list for this role:

1. Writes production Rust · Must have
2. Storage engine internals · Must have
3. Measures performance · Important
4. Maintains a project over time · Important
5. Explains their work · Nice to have

What to leave out

Criteria are about skills and the kind of work. AyHire won't save one about age, gender, nationality or any other personal trait, or about where someone lives or their time zone. It says why, and your edit stays open so you can change it.

If location matters, keep it out of the criteria and filter the search instead. Today that filter is available to your agent and through the API, not yet in the web app. Ask your agent something like “find more people for the Rust role, in Germany or the Netherlands”. It matches the location people wrote on their GitHub profile; AyHire never guesses where someone lives.

Leave out what a conversation is for, too: how someone leads, sells or comes across in a room. Public work can't show it, so it would come back unknown for everyone.

How people are judged

When AyHire scores someone in a role that has criteria, it judges each criterion from their public work and gives one of four verdicts:

• Strong: the public work clearly shows it.
• Some: partial or indirect evidence.
• Unknown: the public work doesn't show it either way. This is common, because most work is private.
• Not shown: the public evidence points the other way. This is rare, and the reason says what points the other way.

Every verdict comes with a short reason and links to the repos, commits or pull requests it rests on. A verdict with no source behind it counts as unknown. On the person's page, the section “How Mara fits this role” (with their name) lists them, followed by questions that would settle what the evidence leaves open.

Two rules keep this fair:

• Unknown never counts against anyone. It earns nothing and costs nothing, so someone whose best work is private isn't marked down for it.
• Only a Not shown on a must-have sets a judged person aside. Nothing else in the criteria does.

When AyHire says “Talk to X first”

Once people are judged against the criteria, AyHire says “Talk to X first” only when every must-have is clearly shown in that person's work. If even one is only partly shown or unknown, the headline says so instead:

No clear fit yet. Mara comes closest; storage engine internals isn't clearly shown.

The call also names one thing to check, such as “Storage engine internals: unknown from public work. Ask about it.”

This is another reason to keep must-haves few and precise. A vague must-have is rarely clearly shown, so nobody would ever be called a clear fit.

After you change criteria

People judged against the old list show as out of date. On their page, the old verdicts stay under the names they were judged against, so nothing gets mixed up. To judge them against the new list, use Judge N people against the criteria at the top of the role page. It takes up to 10 people at a time, and you don't need to search again.

A short checklist

• One or two must-haves, each a kind of work, not a trait.
• A sentence in What good evidence looks like for every criterion.
• Nothing that public work can't show.
• Location as a search filter, never a criterion.
• After a change, judge the people already scored again.