freelance-search
Finds and ranks freelance gigs and consulting work matched to a CV from vetted niche boards. Use when the user wants freelance or contract work ("find freelance gigs", "freelance search", "freelance h
SKILL.mdplugins/mz-job-outreach/skills/freelance-search/SKILL.md
GitHubFreelance Search Pipeline
Overview
You are an orchestrator for a CV-to-gigs freelance pipeline. Given a CV and a free-text preferences prompt, you collect region scope, build a freelance strategy (discipline + three-format rate floor + engagement-type filter), assemble sources from the freelance canonical list plus researcher augmentations, scout multiple vetted/regional/niche boards in parallel, normalize and filter gigs against engagement-type and region, score each gig on a freelance-specific weighted axis model, and produce a single ranked report with top-N scored gigs plus DOC-ONLY guidance cards for referral-only networks.
Output is a master markdown report. Proposals are not generated here — use /freelance-pitch <rank or URL> to generate a proposal for a selected gig.
This skill explicitly excludes mass-market open marketplaces (Upwork, Fiverr, PeoplePerHour, Freelancer.com, Guru) — a user-locked exclusion enforced by the source-researcher's freelance-mode blocklist.
When to Use
Discovering and shortlisting freelance, contract and consulting work that matches a CV, including outreach guidance for vetted freelance networks.
When NOT to use
- The user wants salaried roles — use
/job-searchinstead. - The user wants to draft a proposal for a single known gig — use
/freelance-pitchinstead. - The user explicitly wants Upwork/Fiverr postings — this skill blocks them; redirect the user.
- The user wants fractional/retainer arrangements — this skill scopes to project gigs, contractor placements, and consulting/advisory only.
- The user has not provided a CV — the pipeline asks for one before invoking.
Input
$ARGUMENTS— free-text preferences body. Examples:"Senior backend freelance, Go/Rust, prefer DACH/EU, day rate €700+, project or contract""UX consulting, $200/hr floor, US-based clients, advisory only""Frontend contract React/TS, 6+ months, remote EMEA, $80/hr+"
- CV path — collected interactively in Phase 0.
- Region scope — collected interactively in Phase 0 via AskUserQuestion (
Global,EU,US,DACH,UK,France,CV-driven).
If $ARGUMENTS is empty, ask the user what kind of gigs they want and what constraints matter (discipline, engagement type, rate floor, region) before invoking.
Scope Parameters
Extract scope modifiers from $ARGUMENTS, case-insensitive. Remaining text is the free-text preferences body.
limit:<N>— maximum gigs carried through the pipeline. Default: 40.recency:<N>d— only keep gigs posted in the last N days. Default: 30 (freelance gigs are slower-moving than salaried).pitches:top<N>— convenience flag the user can pass to indicate they want this many top gigs surfaced for/freelance-pitchuse. Not enforced here; informational only. Default: 5.
Argument Parsing
Extract from $ARGUMENTS:
- preferences — full free-text body (everything not matching a parameter pattern).
- limit — optional, from
limit:<N>(default: 40). - recency_days — optional, from
recency:<N>d(default: 30). - pitches_top_n — optional, from
pitches:top<N>(default: 5).
Directory Structure
Two separate directories are used:
- State —
<PROJECT_ROOT>/.mz/task/<task_name>/state.md. Source of truth across phases. - Outreach data —
<PROJECT_ROOT>/.mz/outreach/<run_name>/(called<RUN_DIR>in phase files) holdssearch_strategy.json,sources.json,raw_gigs.json,prescored_gigs.json,scored.json,scored_excluded.json, the final<YYYY_MM_DD>_freelance_search_<slug>.mdreport, and the temp folders_scout/,_prescore_batches/and_scored/.
task_name follows the pattern <YYYY_MM_DD>_freelance_search_<slug>; run_name is <YYYY_MM_DD>_freelance_search_<preferences_slug>. Same-day collisions append _v2, _v3.
Constants
- PROJECT_ROOT: resolved once in setup with
echo "${MZ_MEMORY_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; expand<PROJECT_ROOT>to it in every command and agent prompt. - SKILL_DIR:
${CLAUDE_SKILL_DIR}. Phase files write<SKILL_DIR>/...because files opened with Read get no variable substitution; expand it to this absolute path before reading a file, running a command, or passing a path to an agent.
Core Process
Phase Overview
| # | Phase | Agent(s) | Details |
|---|---|---|---|
| 0 | Setup, CV collection, region pick | — (orchestrator, AskUserQuestion) | Inline below |
| 1 | Strategy | freelance-strategist |
phases/strategy_and_sources.md |
| 1.5 | User approval of strategy | — (orchestrator, AskUserQuestion) | Inline below |
| 2 | Source assembly | job-source-researcher mode=freelance (+ canonical) |
phases/strategy_and_sources.md |
| 3 | Scout fan-out | N × freelance-scout (parallel, skips guidance-only) |
phases/scout_score_report.md |
| 4 | Normalize + filter | — (orchestrator, inline) | phases/scout_score_report.md |
| 4.5 | Cheap pre-score (LLM 0/1/2) | N × job-prescorer (batches of up to 15 gigs) |
phases/scout_score_report.md |
| 5 | Full score & rank | N × freelance-scorer (parallel) |
phases/scout_score_report.md |
| 6 | Master report + guidance cards | — (orchestrator, inline) | phases/scout_score_report.md |
Read each phase file only when you reach the phase it covers.
Strategy schema (Phase 1 output)
search_strategy.json carries the freelance-mode contract every downstream agent reads. Key fields specific to freelance mode:
derived_from_cv.discipline— primary discipline detected from CV (one ofengineering,design,marketing,product,data,ops,founder).derived_from_cv.secondary_disciplines— up to 2 secondary disciplines.preferences.engagement_types— subset of["project_gig", "contractor_placement", "consulting_advisory"].fractional_retaineris forbidden by user-locked exclusion.preferences.regions_allowed— derived from runtimeregion_scopeplus user-stated regions.rate_floor— three formats:hourly_usd,daily_usd,project_total_usd+fx_basis+normalization_notes.scoring_weights— sum=100 across seven freelance-specific axes (skill_match=40, location_eligibility=15, scope_clarity=10, budget_fit=10, client_vetting_presence=10, recency=10, discipline_fit=5).
Legacy fields shared with job-search (search_queries, title_aliases, bilingual_query_variants, must_have_skills, nice_to_have_skills, location_eligibility_rule, recency_window_days, notes) remain in place.
Phase 1.5: User Approval of Strategy
This orchestrator (not a subagent) presents this gate. This step is interactive and must not be delegated.
Pre-read: Read <PROJECT_ROOT>/.mz/outreach/<run_name>/search_strategy.json with the Read tool. Capture the full file contents into context. The strategy file is JSON — present it verbatim inside a fenced ```json block.
State: write state.md with the artifact path and what_remains: [awaiting approval: strategy gate]; Status stays running.
Surface 1 — emit the plan message. Output the strategy verbatim as a normal markdown chat message. Emit the full verbatim contents of <PROJECT_ROOT>/.mz/outreach/<run_name>/search_strategy.json — do not substitute a path, summary, or placeholder. Structure:
## Strategy ready for review — freelance-search
Built from your CV plus preferences and selected region. Derived discipline, engagement types, rate floor (in all three formats), region eligibility, and scoring weights are below.
```json
<verbatim contents of search_strategy.json>
```
---
**Approve** → proceed to Phase 2 (source assembly + scout) · **Reject** → task marked aborted, no scouting runs · reply with feedback to revise
Surface 2 — call AskUserQuestion. A short selector — do not re-embed the strategy JSON in the question body, it lives in the plan message above:
- question:
The freelance-search strategy above is ready for review. - header:
Strategy - options:
- Approve — proceed to Phase 2 (source assembly + scout)
- Reject — mark the task aborted, no scouting runs
Response handling:
- Approve → add
- strategy approved: .mz/outreach/<run_name>/search_strategy.jsonunder## Decisionsinstate.md, remove theawaiting approvalentry fromwhat_remains, setPhase: strategy_approved, and proceed to Phase 2. - Reject → update
state.mdStatustoaborted_by_userand stop. - Any other reply (feedback) → re-dispatch
freelance-strategistwith the feedback appended, overwritesearch_strategy.json, return to Surface 1, re-read the updated strategy, and re-emit the full plan message from scratch with the new JSON contents — never diff-only, never summary-only. This is a loop — repeat until the user explicitly approves. Never proceed to Phase 2 without explicit approval. - No answer → set
Status: blocked, keepawaiting approval: strategy gate, stop. A missing answer is never approval.
Red Flags
- You dispatched scouts before the user approved the strategy.
- You included a banned source (Upwork, Fiverr, PeoplePerHour, Freelancer.com, Guru) — the researcher should block these in freelance mode; if a scout receives one, halt and report a bug.
- Master report lives in chat instead of
.mz/outreach/<run_name>/<YYYY_MM_DD>_freelance_search_<slug>.md. - A gig was scored against the job-mode axis list instead of the freelance axis list.
rate_floorwas missing from strategy but the scorer was dispatched without redistributing thebudget_fitweight.- Guidance-only entries (
scrape_allowed: false) were scraped instead of rendered as DOC-ONLY cards in the report.
Verification
Before completing, output a visible block showing: run name, total gigs scraped, gigs excluded by engagement-type or region filter, total ranked, top-1 final score, count of guidance-only sources rendered as cards, and the absolute path of the master report. Confirm the report file, scored JSON, and any guidance-card sections all exist on disk.
Phase 0: Setup, CV collection, region pick
Resolve PROJECT_ROOT with the command in Constants, before any cd or worktree switch, and use it for every .mz/ path below.
Parse arguments. Derive:
task_name(state dir) =<YYYY_MM_DD>_freelance_search_<slug>, slug is snake_case preferences summary (max 20 chars).run_name(outreach dir) =<YYYY_MM_DD>_freelance_search_<preferences_slug>, max 40 chars.
mkdir -p "<PROJECT_ROOT>/.mz/task/<task_name>"
mkdir -p "<PROJECT_ROOT>/.mz/outreach/<run_name>"
mkdir -p "<PROJECT_ROOT>/.mz/outreach/_history"
CV collection
Collect the CV path as an open-value input collector — ask a direct prose question, then read the reply. Acceptable formats: .md, .txt.
Ask: What is the path to your CV file? Provide an absolute or relative path to a .md or .txt file — the skill needs your CV in markdown or plain text. PDF and DOCX are not supported; convert first. Reply with the path, or "Cancel" to abort.
Validation:
- "Cancel" →
Status: aborted_by_user, stop. - File missing or wrong extension → re-ask once; second failure →
Status: blockedwithwhat_remains: [awaiting answer: path to the CV file], stop. - Success → read CV, capture absolute path.
Region scope pick
Collect the region scope — a closed-choice input collector. The valid set has seven values, more than AskUserQuestion's option cap, so name the four most common as options and enumerate the rest in the question. Call AskUserQuestion once:
- question:
Which region should we scope the freelance search to? This affects which boards we prioritize (Malt for EU, YunoJuno for UK, freelance.de for DACH, etc.) and which gigs survive the location-eligibility filter. Pick an option below, or reply with one of: DACH (Germany/Austria/Switzerland), UK, or France (Malt-heavy). - options:
- Global — any region, widest net
- EU — EU-wide remote and on-site
- US — US-wide remote and on-site
- CV-driven — derive from the CV's current_location
Capture the selection as region_scope.
CV-hash computation (for yield history)
cv_hash=$(tr '[:upper:]' '[:lower:]' < "<CV_PATH>" | tr -s '[:space:]' ' ' | sha1sum | cut -c 1-40)
State file
Write <PROJECT_ROOT>/.mz/task/<task_name>/state.md:
schema_version: 2
Status: running
Phase: 0
Started: <ISO timestamp>
phase_complete: false
what_remains: []
Preferences: <free-text body>
CV path: <abs path>
CV hash: <cv_hash>
Region scope: <region_scope>
Limit: 40
RecencyDays: 30
PitchesTopN: 5
RunName: <run_name>
After setup, read phases/strategy_and_sources.md and proceed to Phase 1.
State Management
State persists to .mz/task/<task_name>/state.md under the project root, ${MZ_MEMORY_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}, resolved once at the start of the run. Schema is v2: line 1 is schema_version: 2; line 2 is Status: with one of pending, running, blocked, complete, aborted_by_user or failed, lowercase and unquoted; then Phase, Started, phase_complete (boolean) and what_remains (YAML list of strings), with skill-specific keys below them. Milestones go in Phase; the reason for blocked or failed goes in what_remains. Set phase_complete: false on phase entry and true once the phase's artifacts are written and its gates pass. Refresh what_remains on every phase transition; it is [] when Status is complete. Write the file after every phase and before every gate, and re-read it after compaction. Record decisions worth recalling under a heading that reads exactly ## Decisions, placed before ## Notes; mz-memory harvests them only once Status is complete. Under a heading that reads exactly ## Lessons, add one line whenever a review finding is accepted and fixed, a step fails, gate feedback corrects a mistake, or an approved approach is reversed, in the form - (review|failure|correction|change) WHEN <situation> → <what to do> — WHY <cause>, concrete and under about 40 words; mz-memory harvests lessons whatever the Status. Treat a legacy completed as complete. On reading a schema_version: 1 or unversioned file, put schema_version: 2 on line 1 and Status on line 2, add the missing keys, and log the upgrade. Leave a file with a higher schema_version untouched: ask whether to Restart (archive it), start New (_v2) or Abort, and stop if nobody can answer.
Resume Support
Before creating anything in Phase 0, check if <PROJECT_ROOT>/.mz/task/<task_name>/state.md exists. If it does, read Phase and resume from the next incomplete phase. All phases are idempotent.
Error Handling
- Agent fails or returns empty: append
Errors:bullet instate.md, continue with available data. - All agents in a phase fail (zero results): stop the pipeline, report the failure.
- Never fabricate data.
- An agent returns
STATUS: NEEDS_CONTEXT: invokeAskUserQuestionto fill the gap, re-dispatch.