Research current roles and real job descriptions (JDs), compare them with your resume, and decide what to target, fix, and do first
简体中文 · Architecture · Roadmap · Contributing
v0.6.0-beta
This is a set of installable career-research instructions for AI tools, built for students, job seekers, and career changers. It researches current industries, roles, and job descriptions, compares market requirements with the resume, projects, and skill evidence you provide, and helps you choose targets, close evidence gaps, and plan the next job-search actions.
- 1. Product direction and user problems
- 2. What it does
- 3. Typical scenarios
- 4. What the result looks like
- 5. Install and use it for the first time
- 6. Use it well
- 7. How it works
- 8. Technical design and defensibility
- 9. Privacy, limitations, and safe use
- 10. Validation status
- 11. Common problems
Job Navigation Skill is not a general chat prompt or an automatic application tool. It is designed to do one job: compare current job-market requirements with the experience and evidence you actually have, then reduce the result to a small number of executable job-search actions.
- hiring information is scattered across company sites and job platforms, making repeated requirements hard to identify;
- generic AI advice often omits sources and fails to show where the evidence ends;
- what a resume says someone did is not always the same as what it proves against a target role;
- students without formal work experience struggle to judge whether courses, projects, and campus experience count as credible evidence;
- learning lists expand without considering target roles, time, cost, or order;
- overloaded 30/60/90-day plans still leave users unsure what to do in the first week.
- students and recent graduates choosing a role or building evidence for one;
- job seekers comparing current JDs with a resume or portfolio;
- career changers deciding which direction to test before paying for a long course;
- professionals comparing job locations, industries, roles, or career-skill investments;
- users who want sourced advice with visible uncertainty instead of motivational filler.
- automatic job applications, recruiter messages, or account automation;
- keyword-only ATS scoring;
- inventing resume achievements, metrics, or individual ownership;
- guaranteeing hiring, admissions, income, or other outcomes;
- general personal decisions, education planning, or life advice unrelated to a target career.
This is a job-search decision and evidence-diagnosis tool, not a hiring predictor. It researches, compares, and prioritizes. You review the evidence and keep the final decision.
| Function | What you receive | Built-in boundary |
|---|---|---|
| Role and industry research | Current official, company, job-board, and labor-market evidence with a cutoff date | No claim that every requested site was accessible |
| Evidence calibration | Facts separated from inference, forecasts, and recommendations | A framework is never treated as empirical proof |
| Personal fit | Findings compared with your stated goals, constraints, and evidence | No unstated skill, experience, or achievement is invented |
| Career-market analysis | Deduplicated JD requirements, demand bands, required/preferred split | Job-ad frequency is not called total labor-market demand |
| Resume evidence review | Skill, evidence, communication, experience, and constraint gaps | Team or simulated outcomes are not rewritten as personal results |
| Skill prioritization | do now, test cheaply, build next, and defer |
It does not recommend learning every tool in every JD |
| Action planning | One direction, at most three immediate actions, effort, and completion proof | The plan is reduced when time or energy is limited |
| Review loop | Near-term behavior signals, downstream outcomes, and a review trigger | One rating or before/after story is not treated as causal proof |
| Scenario | Give the Skill | It should return |
|---|---|---|
| New graduate choosing roles | Degree, projects, location, target date, weekly capacity | Suitable role families, evidence gaps, and a small market test |
| Resume vs. current market | Redacted resume plus target role and geography | JD requirement matrix, candidate evidence grades, and priorities |
| Career change | Transferable experience, constraints, options, risk tolerance | Direction comparison, cheap validation experiments, and defer list |
| Industry or role trend | Geography, time window, titles/synonyms, decision to make | Sourced trend signals, contradictions, limits, and implications |
| Career-skill investment | Target-JD gaps, course or certificate cost, time, and alternative proof paths | Whether to learn, build a project, use another proof path, or defer |
| 30/60/90-day plan | Target, baseline, weekly capacity, deadline | Capacity-bounded milestones with only the first week shown as immediate work |
- If resume-gap analysis is requested without a resume or factual background, the Skill asks for it before creating a candidate comparison.
- If role or geography is missing and materially changes the market, it asks one concise career-scope question at a time.
- If a platform is blocked, it reports the failure and narrows the claim instead of fabricating results.
Example context: a data-science master's graduate is targeting AI product or AI operations roles in Shenzhen. They provide a redacted resume, course list, and project evidence, and want recent JDs compared before choosing a role direction and a 90-day plan.
The first screen is designed for a tired or inexperienced user:
BOTTOM LINE
Test AI operations before making AI product manager your only target.
Your current analytics evidence is stronger than your product-ownership evidence.
NEXT THREE ACTIONS
1. Rewrite one project as user problem → decision → result. 2 hours.
2. Tag repeated requirements in 10 usable first-party JDs. 90 minutes.
3. Ask two practitioners to critique that case. 45 minutes.
MAIN UNCERTAINTY
Two requested job boards were inaccessible, so this is a directional sample.
Supporting detail follows only when useful:
FACT · Medium confidence
[Current market observation with a nearby citation and date]
YOUR EVIDENCE
[Only what the supplied resume, project, or portfolio supports]
INFERENCE
[Why the overlap points toward one role family]
RECOMMENDATION
[A personalized, reversible next step]
REVIEW
Revisit after 10 targeted applications or two practitioner interviews.
The goal is not a longer answer. It is a decision you can inspect: what is known, what is uncertain, what it means for you, and what happens next.
See the fictional abbreviated example. It demonstrates output shape only; it is not current market evidence or a success claim.
A Skill is a set of professional instructions that an AI tool can read. It is not a new chat app and does not train a model. Choose the one platform you already use; do not install every version.
The product display name and technical identifier are both Job Navigation Skill / job-navigation-skill. Version 0.5.0-beta introduced a breaking rename: installations under the previous identifier require the one-time migration in Safe upgrade.
| Platform you use | Installation difficulty | Recommended route |
|---|---|---|
| Codex | Copy one command | Codex instructions |
| Claude Code | Copy one command | Claude instructions |
| Cursor | No-code import or one command | Cursor instructions |
| work-buddy | Copy one command | work-buddy instructions |
| claude.ai website | No-code upload | claude.ai upload steps; account support for custom Skills is required |
| ChatGPT | Developer route | ChatGPT note; no public store listing is currently available |
This repository does not automatically upload the Skill or your resume to any provider. Material you submit while using an agent is processed under that provider's account, tool, and data settings; see Privacy.
- at least one supported AI tool listed above;
- no Python requirement for the no-terminal Cursor or claude.ai routes;
- Python 3.11 or later for command installation, validation, or packaging;
- a downloaded or cloned copy of this repository for command installation;
- network access only when your request needs current research.
No Python package installation is required. The installer and validation scripts use the standard library.
From the GitHub repository page, choose one method:
Download ZIP
- Download the project ZIP directly, or select Code → Download ZIP.
- Extract the archive.
- Open a terminal in the extracted folder, whose name will look like
job-navigation-skill-main:- macOS: open Terminal, type
cdwith a trailing space, drag the folder into the Terminal window, and press Return; - Windows: open the folder, select the File Explorer address bar, type
powershell, and press Enter.
- macOS: open Terminal, type
Git clone
Use this method only if you are already comfortable with Git.
- Select Code on the GitHub repository page.
- Copy the HTTPS or SSH URL.
- Clone it with your Git client.
- Open Terminal or PowerShell in the resulting
job-navigation-skillfolder.
The remaining commands in this manual assume that this repository folder is your current working directory.
macOS, Linux, or PowerShell:
python3 scripts/validate_repo.pyOn Windows, use python instead of python3 if that is how Python is registered:
python scripts\validate_repo.pyExpected output:
Validation passed.
Skill: job-navigation-skill
Evaluation cases: 9
The installer runs validation automatically, so ordinary users can install directly. Maintainers and people troubleshooting a failure can run the command above separately. It checks required files, frontmatter, version consistency, local-path leakage, broken relative links, symlinks, and common secret patterns. It does not prove that web research or recommendations are correct.
macOS or Linux:
python3 scripts/install.py --agent codexWindows PowerShell:
python scripts\install.py --agent codexThe installer resolves the destination as:
${CODEX_HOME}/skills/job-navigation-skill
If CODEX_HOME is not set, it uses:
~/.codex/skills/job-navigation-skill
The install is transactional: the repository is validated first, symlinks are rejected, files are copied to a temporary staging directory, and the existing destination is never overwritten.
This repository does not currently have a public store listing that an ordinary ChatGPT user can click to install. This section is only for people developing or publishing a Plugin; downloading a ZIP does not install the Skill into ChatGPT. ChatGPT and Codex share OpenAI's plugin format, and this repository contains .codex-plugin/plugin.json plus the canonical skills/ directory.
Build the distributable plugin archive:
python3 scripts/package_skill.py --target chatgptThe archive is created under dist/. Use it in the OpenAI plugin authoring and publication workflow, or install the published plugin from the universal plugin directory when a listing is available. Packaging the archive locally does not publish or install it automatically.
After the plugin is installed, ChatGPT can choose the Skill automatically or you can select it explicitly with an @ mention.
Claude Code uses the same SKILL.md folder format:
python3 scripts/install.py --agent claudeThe default destination is:
~/.claude/skills/job-navigation-skill
The claude.ai website does not require a terminal:
- Open the
v0.6.0-betarelease. - Download the ZIP whose name contains
claude-skill; do not extract it. - If your account supports custom Skills, upload the ZIP under Settings → Features.
- Start a new chat and ask Claude to use
job-navigation-skill.
If the custom Skills option is missing, it may not be available for your current product version, account, or plan. Developers can also build an archive with the same structure:
python3 scripts/package_skill.py --target claudeUpload the resulting Claude archive through Settings → Features where custom Skills are available. Claude surfaces manage Skills separately, so a Claude Code installation does not automatically appear in claude.ai or the Claude API. See Anthropic's Agent Skills documentation.
Claude API Skill containers do not have network access. This project therefore does not claim recent job-market research on that surface unless the host application separately supplies a working search tool or retrieved evidence.
Cursor natively discovers Agent Skills. Install this Skill to its user-level directory:
python3 scripts/install.py --agent cursorThe default destination is:
~/.cursor/skills/job-navigation-skill
You can also use Cursor Settings → Rules → Add Rule → Remote Rule (GitHub) and import this repository. Start a new chat after installation, then invoke /job-navigation-skill or mention it with @. See the Cursor Agent Skills documentation.
To build a portable Cursor archive:
python3 scripts/package_skill.py --target cursorwork-buddy runs inside Claude Code, so it uses the same Claude Code Skill directory instead of a separate package format:
python3 scripts/install.py --agent workbuddyThis installs to ~/.claude/skills/job-navigation-skill. If you already installed the Skill with --agent claude, do not install a duplicate. Open a new Claude Code/work-buddy session so the Skill can be discovered. See the work-buddy documentation.
This repository does not claim a separate work-buddy-native Skill store or archive. For distribution, work-buddy users can use the Claude Skill archive because the host runtime is Claude Code.
Use a custom destination only when your Codex environment is configured to discover that directory:
python3 scripts/install.py --agent codex --dest "/absolute/path/to/codex/skills"Example for a personal macOS Skill library:
python3 scripts/install.py --agent codex --dest "$HOME/Desktop/codex/skill"--dest must point to the parent Skill directory. The installer creates the final job-navigation-skill folder inside it.
For a custom Claude Code, Cursor, or work-buddy directory, select the matching --agent value and pass the corresponding parent path. work-buddy and Claude Code normally share the same destination.
Every command installation validates the repository automatically. Successful output looks like:
Validation passed.
Installed job-navigation-skill for [agent] to ...
If python3 or python is not found, install Python 3.11 or later. On Windows, select Add Python to PATH, then reopen PowerShell.
Default macOS/Linux installation:
test -f "$HOME/.codex/skills/job-navigation-skill/SKILL.md" && echo "Skill files installed"Windows PowerShell:
Test-Path "$HOME\.codex\skills\job-navigation-skill\SKILL.md"Claude Code default installation:
test -f "$HOME/.claude/skills/job-navigation-skill/SKILL.md" && echo "Claude Skill files installed"Cursor default installation:
test -f "$HOME/.cursor/skills/job-navigation-skill/SKILL.md" && echo "Cursor Skill files installed"Then start a new Codex task and invoke the Skill explicitly:
Use $job-navigation-skill:
I am targeting [role] in [location]. Research recent roles and JDs, compare them with the
redacted resume I will provide, and identify role fit, evidence gaps, and my top three actions.
Separate facts, inferences, and recommendations.
Before uploading a resume, remove phone numbers, personal email addresses, identity numbers, exact home addresses, and unnecessary private links. Installing the Skill does not automatically read or upload a resume; only content you deliberately provide enters the conversation.
Local Skill discovery can vary by Codex environment and configuration. If the Skill is not listed or triggered, restart Codex, verify the destination, and use the explicit $job-navigation-skill invocation.
For ChatGPT, use an @ mention after installing the plugin. For Claude Code or work-buddy, start a new session and ask it to use job-navigation-skill; Claude can also select the Skill automatically when the request matches. In Cursor, use /job-navigation-skill or @.
The installer intentionally refuses to overwrite an existing Skill. Use a recoverable upgrade:
One-time migration from v0.4.0-beta or earlier: the former Skill identifier was evidence-based-personal-advisor. Move that folder out of the active Skill directory before installing job-navigation-skill; do not leave both identifiers active because an agent may trigger the outdated copy.
mv "$HOME/.codex/skills/evidence-based-personal-advisor" \
"$HOME/.codex/evidence-based-personal-advisor.pre-rename-backup"
python3 scripts/install.py --agent codexFor Claude Code and work-buddy, apply the same migration under $HOME/.claude/skills. For Cursor, use $HOME/.cursor/skills. For custom Skill directories, replace the parent path with the directory used in your installation.
- Download or pull the new repository version.
- Validate the new repository.
- Move the installed Skill to a backup name.
- Run the installer again.
- Start a new Codex task and run one known prompt.
- Remove the backup only after the new version works.
Default macOS/Linux example:
mv "$HOME/.codex/skills/job-navigation-skill" \
"$HOME/.codex/skills/job-navigation-skill.backup"
python3 scripts/install.py --agent codexRollback:
mv "$HOME/.codex/skills/job-navigation-skill" \
"$HOME/.codex/skills/job-navigation-skill.failed"
mv "$HOME/.codex/skills/job-navigation-skill.backup" \
"$HOME/.codex/skills/job-navigation-skill"For a custom destination, replace $HOME/.codex/skills with the same parent directory used during installation.
Windows PowerShell upgrade:
Move-Item "$HOME\.codex\skills\job-navigation-skill" `
"$HOME\.codex\skills\job-navigation-skill.backup"
python scripts\install.py --agent codexWindows PowerShell rollback:
Move-Item "$HOME\.codex\skills\job-navigation-skill" `
"$HOME\.codex\skills\job-navigation-skill.failed"
Move-Item "$HOME\.codex\skills\job-navigation-skill.backup" `
"$HOME\.codex\skills\job-navigation-skill"For Claude Code or work-buddy, use the same procedure under $HOME/.claude/skills and reinstall with --agent claude or --agent workbuddy. For Cursor, use $HOME/.cursor/skills and --agent cursor. ChatGPT and claude.ai packages are upgraded through their respective plugin or Skill management surfaces.
Move the installed folder out of the active Skill directory:
mv "$HOME/.codex/skills/job-navigation-skill" \
"$HOME/.codex/job-navigation-skill.uninstalled"Restart Codex and confirm the Skill is no longer discovered. Delete the moved copy later only if you no longer need rollback.
Windows PowerShell:
Move-Item "$HOME\.codex\skills\job-navigation-skill" `
"$HOME\.codex\job-navigation-skill.uninstalled"For Claude Code or work-buddy, move the corresponding folder out of $HOME/.claude/skills. For Cursor, move it out of $HOME/.cursor/skills. Remove ChatGPT or claude.ai packages from their respective Skill or Plugin management screens.
- goal and geography;
- decision deadline;
- weekly time, budget, risk tolerance, and non-negotiable constraints;
- redacted resume, portfolio, transcript, or project evidence;
- definition of success and what you want to avoid.
Remove phone numbers, personal email addresses, IDs, exact home addresses, private links, and unrelated confidential material.
| Mode | Use it for | General research scope |
|---|---|---|
quick |
Orientation, “give me a direction,” cheap tests | 4–8 useful sources, 1–2 models, short answer |
standard |
Most role, resume, and job-search direction analyses | 8–15 contextual sources, 2–4 source types, 1–3 models |
deep |
Explicitly systematic or consequential comparisons | Broader inclusion rules, contradiction mapping, explicit limitations |
For standard career analysis, the career module additionally targets 20–40 deduplicated JD records when access and market size permit. JD record count and contextual-source count are separate controls. Fewer JDs are acceptable when disclosed; neither number is a quota.
Research stops when two successive rounds add no decision-changing evidence.
Resume and current market
Use $job-navigation-skill.
I am targeting [role] in [geography] by [date]. Research the last [time window]
of industry and job trends, sample recent JDs, and compare them with my redacted
resume. Identify role fit, skill gaps, evidence gaps, and the three highest-value
actions. Separate facts, inference, and recommendations. I can spend [hours]
per week. Disclose inaccessible sources and the research cutoff.
Career change
Use $job-navigation-skill to compare [option A], [option B], and
[option C]. My transferable evidence is [brief facts]. My constraints are
[time/budget/location/risk]. Use current market evidence and recommend the
cheapest experiments that could change the decision before I commit.
Target-role skill, certificate, or course decision
Use $job-navigation-skill to assess whether [skill/certificate/course]
is the best way to close [specific target-role gap]. Use current JDs to compare
price, time, and alternative project or portfolio evidence. Tell me whether to
learn now, test cheaply, build next, or defer.
your question and redacted materials
│
▼
decision framing and research budget
│
▼
claim → best source type → current evidence
│
▼
deduplication, confidence, contradiction checks
│
▼
market evidence ↔ your inspectable evidence
│
▼
one direction → ≤3 immediate actions → review loop
For career analysis, the evidence chain is:
JD requirement → demand band → candidate evidence → evidence grade
→ gap type → recommended proof → action priority
Candidate evidence uses a separate A/B/C/D/U scale so that a confident market claim cannot manufacture proof that the candidate has a skill.
The defensibility is not the number of frameworks. It is the combination of procedures, boundaries, and tests:
- Claim-to-source routing — industry trends, hiring scale, job requirements, compensation signals, and practitioner friction use different source hierarchies.
- Two independent evidence axes — source confidence and candidate evidence strength are never merged.
- JD normalization and deduplication — syndicated postings are counted once, required and preferred signals stay separate, and posting dates are distinguished from page refresh dates.
- Evidence-first model routing — business, academic, and practice frameworks are selected only after evidence collection and removed when they do not change the action.
- Human-sized delivery — the answer begins with one direction, no more than three immediate actions, effort, and completion proof.
- Failure-aware research — blocked sources, sparse samples, contradictions, and inaccessible platforms are reported as limits instead of silently hidden.
- Validation ladder — structural validity, behavioral compliance, baseline improvement, and real-user benefit are four separate claims.
- Privacy-safe evaluation — local JSONL aggregation records scores, costs, and failures without requiring resumes or raw prompts in the public repository.
Read ARCHITECTURE.md for the runtime and evaluation flows.
- The repository does not receive or collect your resume or evaluation data.
- Local installation does not mean offline inference. ChatGPT, Codex, Claude, Cursor, work-buddy, and enabled tools may send supplied material to their configured providers or services.
- The Skill instructs the active agent not to put resume text, identifiers, contact details, or confidential records into web searches.
- This is an instructional safeguard, not a network sandbox. Review generated queries when risk is material.
- Job boards may require authentication, personalize results, block automation, or expose stale pages.
- The Skill has no bundled BOSS, LinkedIn, or Indeed crawler. It uses web access available in the active agent environment.
- Agent capabilities are not identical: login state, browser access, built-in search, file parsing, and citation behavior vary by product and account.
- Connectors and MCP tools are optional: the Skill checks what is actually available and authorized instead of assuming a provider is installed. See the tool-access policy.
- JD samples are convenience samples, not statistically representative labor-market surveys.
- Job-ad frequency is a directional demand signal, not total hiring volume.
- Frameworks organize reasoning; they do not prove claims.
- Current sources can still be wrong, incomplete, or misinterpreted.
- Verify important claims and generated career material before acting or submitting.
- Never accept invented metrics, ownership, credentials, or outcomes.
- Follow the terms of service of websites and data sources you access.
- Do not treat a role-fit assessment as a hiring probability or outcome guarantee.
See SECURITY.md for reporting and privacy guidance.
| Evidence level | Current status |
|---|---|
| Repository structure and privacy checks | Passed locally; CI workflow is configured for GitHub |
| Codex, Claude Code, Cursor, and work-buddy installer paths | Passed isolated local installation tests; work-buddy shares Claude Code's destination |
| ChatGPT, Claude, and Cursor package generation | Passed archive structure checks |
| Automatic Skill discovery | 14 bilingual positive/negative trigger cases exist; cross-agent results are not yet published |
| Behavioral compliance across model/tool versions | Nine output-behavior scenarios exist; repeatable results are not yet published |
| Better than a neutral baseline | Not established |
| Improves real user outcomes | Not established |
There are no fabricated adoption numbers here. Until at least 10 complete paired tasks and 10 relevant users produce usable data, accuracy, actionability, and token savings remain design goals—not proven benefits.
To test the local evaluation machinery:
python3 skills/job-navigation-skill/scripts/summarize_evals.py --self-test
python3 skills/job-navigation-skill/scripts/summarize_evals.py --templateRead the evaluation protocol before collecting results. Raw prompts, resumes, employer identities, and complete model outputs do not belong in the public repository.
| Problem | Check | Next step |
|---|---|---|
python3 not found |
Run python --version |
Use python on Windows or install a supported Python version |
| Validation fails | Read the first reported missing file, link, local path, or secret | Restore/fix that exact item; do not bypass validation |
| Destination already exists | The installer protects an existing installation | Use the backup-and-upgrade procedure above |
| Skill files exist but Codex does not show it | Confirm the parent directory is a Skill directory for that environment | Start a new task, invoke $job-navigation-skill, then restart Codex if needed |
| Requested platforms are inaccessible | Check authentication and platform restrictions | Provide exported links/text or accept a narrower, clearly labeled sample |
| ChatGPT package cannot be installed | Confirm the plugin is published or available through an enabled development/local source | Validate .codex-plugin/plugin.json; packaging alone does not create a listing |
| Cursor does not discover the Skill | Confirm it is under ~/.cursor/skills/ and contains SKILL.md |
Start a new chat and invoke /job-navigation-skill or mention it with @ |
| work-buddy does not discover the Skill | Confirm Claude Code can see ~/.claude/skills/job-navigation-skill |
Do not duplicate the install; start a new Claude Code/work-buddy session |
| Answer is too long | Ask for quick mode and state weekly capacity |
Request only the bottom line, three actions, and main uncertainty |
| Resume analysis invents facts | Stop using the output | Report a privacy-safe bug and remove unsupported claims |
job-navigation-skill/
├── .codex-plugin/plugin.json # ChatGPT/Codex universal Plugin manifest
├── skills/job-navigation-skill/
│ ├── SKILL.md # Core decision router
│ ├── agents/openai.yaml # Codex UI metadata
│ ├── references/ # Conditional specialist guidance
│ ├── evals/cases.yaml # Nine output-behavior scenarios
│ ├── evals/trigger-cases.yaml # 14 bilingual discovery scenarios
│ └── scripts/summarize_evals.py # Local paired-result summary
├── examples/ # Explicitly labeled examples
├── scripts/install.py # Transactional installer
├── scripts/package_skill.py # ChatGPT, Claude, and Cursor archive builder
├── scripts/validate_repo.py # Structure and privacy checks
├── ARCHITECTURE.md
├── ROADMAP.md
├── CHANGELOG.md
└── .github/ # CI, issue forms, and PR checklist
Observed failures, clearer language, behavioral tests, translations, and privacy-safe aggregate evaluations are welcome. Start with CONTRIBUTING.md and follow the code of conduct.
MIT. Use it, inspect it, adapt it, and report where it fails.