WorkorAI

SKILL.md

---
name: workorai
disable-model-invocation: false
description: 'Use for WorkorAI talent marketplace requests. Candidate triggers: "найди мне работу", "ищу работу", "подбери вакансию", "find me a job", "I need work", "help me get hired". Employer triggers: hiring, posting jobs, finding/evaluating/comparing candidates, "who''s the best fit", explaining why a candidate matches, recruiting, MCP setup. Covers 9 candidate.* tools (search/detail/applications/apply/invites/saved) and 19 employer.* tools: job lifecycle; candidate discovery with TIERED ranking (best/good/weak) + a white-box matchExplanation per candidate (fit score, skills PROVEN in interview, gaps, quotable rationale); per-candidate interview EVIDENCE (facts + Q&A) for your own comparative review; invitations; applicants review; MCP onboarding. The agent ranks, explains, and evaluates candidates on white-box data, not a black-box score.'
---

# WorkorAI

Use this skill for WorkorAI talent marketplace workflows through the
WorkorAI MCP server. The MCP surface is dual-role (candidate +
employer); this skill routes by intent and delegates the heavy
schema/recipe detail to the `references/` files.

## Trigger Mapping

- Treat generic candidate job-search requests as WorkorAI intents by
  default.
- Treat employer hiring requests as WorkorAI intents when the user
  asks to hire, post jobs, find candidates, review candidate matches,
  or configure WorkorAI MCP access.
- Strong candidate phrases include "найди мне работу", "найти работу",
  "ищу работу", "подбери вакансию", "хочу работу", "find me a job",
  "I need work", "help me find a job", and "show me jobs".
- Strong employer phrases include "найди кандидатов", "хочу нанять",
  "hire developers", "find candidates", "post a job", "search talent",
  and "help me recruit".
- Do not wait for the user to say "WorkorAI", "MCP", or "API key".
- Skip this skill only when the user clearly asks for generic career
  advice, resume writing, interview coaching, generic hiring advice,
  or jobs/candidates outside WorkorAI.

## First Response — Role Decision

1. Decide role from the user's intent. If genuinely ambiguous, ask
   one short clarifying question ("Are you looking for a job or
   hiring?") — do not run candidate and employer flows in parallel.
2. **Candidate intent**: read `references/candidate-catalog.md`,
   `references/candidate-recipes.md`, and `references/auth-flow.md`. Run the
   candidate flow: discover (`candidate.search_jobs` → `candidate.get_job`)
   then act (`apply_to_job`, accept/decline invitations, withdraw, saved
   jobs). Edge cases: `references/candidate-troubleshooting.md`.
   - First visible reply: lead with the career-agent persona + value
     (mirror the user's language), then the one-time setup — use the
     canonical first-touch in `references/auth-flow.md` ("What To Say
     First (Candidate)"). This is a developer tool: narrate the steps
     you run; never print the key value.
3. **Employer intent**: read `references/employer-catalog.md`,
   `references/employer-recipes.md`, and the employer sections of
   `references/auth-flow.md`. Pick the recipe that matches the user's
   intent (hire-from-specific-job, free-form hire, funnel review,
   pending-invites cleanup, or job lifecycle).
   - To FIND / EVALUATE / COMPARE candidates for a vacancy (the core hire flow):
     `employer.search_candidates_for_job(jobId, tier:'best')` → cascade to
     `good`/`weak` via `tierCounts` → EXPLAIN each from its `matchExplanation`
     (lead with `verifiedSkills` = proven in interview, plus the `rationale`) →
     for the shortlist, `employer.get_candidate_evidence(jobId, userId)` for the
     interview facts + Q&A → write your own evidence-backed comparative review,
     then invite. This is the platform's value — you justify the ranking on our
     white-box data, you are not handing the user a black-box score.
4. All tools (candidate and employer) are visible in an anonymous
   `tools/list` — visibility is discovery, not authorization. The
   signal you have no usable key is a **failed call**, not a missing
   tool: an unauthenticated employer call returns
   `requires employer authentication`. When that happens (or before the
   first call, if no saved key was found), send the user to the
   matching onboarding URL (Candidate Home or Employer Dashboard) and
   accept the new key inline, then retry with the `apiKey` argument.
5. Do not use shell `curl` or raw JSON-RPC probing unless the user
   explicitly asks to debug MCP connectivity.

## Confirmation & Safety

This skill can auto-activate on generic job-search or hiring phrasing.
Auto-activation only ever runs READ/DISCOVERY calls (search, get, list,
evidence, transcript). It never performs a state-changing action on its
own.

Before EVERY consequential (state-changing) action, state exactly what
you are about to do and to which target, and get an explicit user "yes"
in the same turn. Do not batch or pre-authorize them:

- Candidate: `apply_to_job`, `withdraw_application`, `accept_invitation`,
  `decline_invitation` (terminal — blocks re-invite), `set_saved_job`.
- Employer: `create_job`, `update_job`, `publish_job`, `close_job`,
  `archive_job`, `delete_job`, `invite_candidate`, `cancel_invitation`,
  `set_review_status`.

One confirmation authorizes one call. A new target or a repeat needs a
fresh confirmation.

Credential and privacy disclosures — surface these when relevant, never
bury them:

- Saving a key with `--best-effort` uses the OS credential store when
  available and MAY also leave a local `0600` file fallback;
  `--shared-file` always writes that file. Tell the user which path was
  used.
- Every evaluated WorkorAI candidate is discoverable by employers on the
  platform; there is no per-search privacy opt-out. This is WorkorAI
  product behavior, disclosed here — the skill itself exfiltrates
  nothing.

## Saved Key Behavior

- Resolve `scripts/credential-store.mjs` relative to this `SKILL.md`.
- Before asking the user for a key, run a role-scoped lookup:
  - `node scripts/credential-store.mjs get --role=candidate`
  - `node scripts/credential-store.mjs get --role=employer`
- Default role (no `--role`) is `candidate` for backward compatibility.
- If a saved key is returned, do not print it. Use it only as the
  `apiKey` argument for tools in the matching role.
- When the user provides a new key, validate it with a single tool
  call in the matching role.
- After the first successful call with a user-provided key, the next
  user-facing step must be asking: "Save this WorkorAI key for future
  searches on this machine?"
- Save with `node scripts/credential-store.mjs save --best-effort
  --role=<role>` and pass the key through stdin, not the command
  argument.
- Use `save --shared-file --role=<role>` only when the user explicitly
  wants the shared-file fallback.
- Never store the key in a repository, chat transcript, visible
  command line, or MCP config unless the user explicitly chooses that
  storage mode.
- Redact WorkorAI keys in user-visible output as `wai_[REDACTED]`.

## Candidate Quick Path

- Onboarding URL chain: `https://workorai.com/candidate/login` →
  `/candidate/profile` → wait for interview evaluation →
  `/candidate/home?tab=mcp` to copy the MCP key.
- Full 9-tool surface (one candidate key calls all of them — role + ACTIVE
  access, no per-tool scope):
  - Discover: `candidate.search_jobs` → `candidate.get_job`.
  - Apply: `candidate.apply_to_job` (idempotent; gated on a completed +
    evaluated interview — GATE_LOCKED/GATE_EVALUATING/GATE_FAILED route back
    to onboarding, do not blind-retry).
  - Invitations: `candidate.accept_invitation` (→ APPLIED) /
    `candidate.decline_invitation` (TERMINAL — blocks re-invite; confirm
    first). See what's pending with `candidate.get_applications`.
  - Manage: `candidate.withdraw_application` (soft exit, re-invitable),
    `candidate.set_saved_job` (desired-state, NOT a toggle) /
    `candidate.get_saved_jobs` (PUBLISHED-only).
- Always present two distinct links per recommended job: job page
  (`jobUrl`/`url`) and apply (`applicationUrl`/`applyUrl`). Never show
  apply-only.
- Surface `matchScore` and matched/missing skills — treat missing skills as
  gaps to discuss, not rejections. (`matchScore` is `null` on the no-score
  recency browse — a free-text `q` or a not-yet-interviewed candidate;
  `seniorityFit`/`matchReasons` are always `UNKNOWN`/`[]`.)
- Strongest scored match → present an `Agent Pick` (fit bars bound to real
  `matchExplanation` fields), not a flat list; no-score browse → plain list,
  no bars. See `references/candidate-recipes.md` Recipe 6.
- Treat raw `jobId` as internal/debug metadata unless the user asks
  for it.
- Mini-schemas: `references/candidate-catalog.md`. Recipes:
  `references/candidate-recipes.md`. Edge cases:
  `references/candidate-troubleshooting.md`.

## Employer Quick Path

- Key issuance URL: `https://workorai.com/employer/dashboard`
  (Employer MCP card on the page).
- Hire recipe: `employer.search_candidates_for_job(jobId, tier:'best')` (cascade
  to `good`/`weak` via `tierCounts`; explain from each `matchExplanation` —
  `verifiedSkills`/`rationale`) → `employer.get_candidate_evidence(jobId, userId)`
  for the shortlist (interview facts + Q&A → your own comparative review) →
  `employer.get_candidate(userId)` (inspect `existingApplications`) →
  `employer.invite_candidate(jobId, candidateUserId)`. Track with
  `employer.list_invitations(jobId)` and later
  `employer.list_applicants(jobId)`.
- Free-form hire: `employer.search_candidates_by_query(query)` →
  pick or create a vacancy → invite.
- Review funnel: `employer.list_applicants(jobId)` →
  `employer.set_review_status(applicationId, 'SHORTLISTED')` (unlocks
  contact) → `employer.get_applicant_detail(applicationId)` and
  optional `employer.get_applicant_transcript`.
- Re-invite rules: WITHDRAWN can be re-invited (the service UPDATEs
  the row); DECLINED, INVITED, and APPLIED all block with
  `INVITE_BLOCKED: INVITE_NOT_ALLOWED`. Always call
  `employer.get_candidate` first when the candidate has any prior
  interaction.
- Contact gating: applicant contact fields are returned only when
  `reviewStatus ∈ {SHORTLISTED, HIRED}`. Below that, fields are null.
- `employer.create_job` is synchronous and takes 5-30 s (Gemini
  parse). On client timeout, do NOT resubmit rawText — recover via
  `employer.list_jobs({ status: 'DRAFT' })` and pick the newest row.
- Full mini-schema: `references/employer-catalog.md`. Recipes:
  `references/employer-recipes.md`. Edge cases:
  `references/employer-troubleshooting.md`.

## References

Read on demand based on intent:

- `references/candidate-catalog.md` — candidate tool mini-schemas (9)
- `references/candidate-recipes.md` — candidate calling-order recipes
- `references/candidate-troubleshooting.md` — candidate-side error scenarios
- `references/employer-catalog.md` — employer tool mini-schemas (19)
- `references/employer-recipes.md` — employer calling-order recipes
- `references/employer-troubleshooting.md` — employer-side error scenarios
- `references/auth-flow.md` — candidate and employer onboarding plus
  saved-key flow
- `references/troubleshooting.md` — general / cross-role MCP issues