# How /upskill Generates Skill Gap Heatmaps and Prioritized Learning Plans > Learn how /upskill creates skill gap heatmaps and prioritized learning plans. It analyzes job requirements against your skills to identify and sequence study resources. - Repository: [Mads Lorentzen/ai-job-search](https://github.com/MadsLorentzen/ai-job-search) - Tags: how-to-guide - Published: 2026-07-14 --- **The `/upskill` command analyzes job requirements against your documented skill profile to generate Markdown heatmaps and prioritized learning plans by calculating binary gap scores, filtering high-priority deficits, and sequencing study resources based on dependencies.** The `/upskill` command is a Claude skill defined in the [ai-job-search](https://github.com/MadsLorentzen/ai-job-search) repository that automates skill gap analysis for software engineers and data professionals. By comparing extracted competencies from job postings against your current abilities listed in [`CLAUDE.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/CLAUDE.md), the tool produces deterministic visualizations and actionable study sequences without requiring external API keys or secrets. ## Understanding the /upskill Command Architecture The skill operates as a deterministic pipeline defined in [`.claude/skills/upskill/SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/skills/upskill/SKILL.md). It processes either aggregated historical data or targeted job postings to identify competency deficits and recommend learning paths. The workflow relies on two primary data sources: - **[`CLAUDE.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/CLAUDE.md)** – Contains your normalized skill profile, including hard skills and soft skills - **`job_search_tracker.csv`** – Stores tracked job postings for aggregate analysis ## Step-by-Step Heatmap Generation Workflow ### Input Mode Selection (Aggregate vs. Targeted) The skill first determines its execution mode based on command arguments: - **Aggregate mode** (`/upskill` without arguments): Reads every entry from `job_search_tracker.csv` to analyze patterns across multiple applications - **Targeted mode** (`/upskill `): Fetches a single job posting from the provided URL for immediate analysis ```bash # Run aggregate analysis across all tracked jobs $ claude /upskill # Analyze a specific job posting $ claude /upskill https://example.com/job/12345 ``` ### Skill Extraction and Gap Computation For each job posting, the skill extracts required hard skills (technologies, certifications, frameworks) and soft skills (phrases like "team-player" or "communication"). The gap calculation uses a binary scoring formula: ```markdown gap_score = 1 – (candidate_has_skill ? 1 : 0) ``` This produces **0** for covered skills and **1** for missing ones. Soft-skill gaps are identified by comparing descriptive phrases against the profile's soft-skill section in [`CLAUDE.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/CLAUDE.md). ### Rendering the Markdown Heatmap Table The skill sorts gaps by descending score and renders them as a Markdown table displaying **skill**, **required level**, **candidate level**, and **gap severity**. This heatmap prints to the terminal before any further processing, as specified in step 5 of the skill documentation. ## Building Prioritized Learning Plans ### Filtering High-Priority Skill Gaps Only gaps exceeding a configurable priority threshold advance to the learning plan phase. This filtering ensures the plan focuses on critical competencies rather than minor skill variations. ### Resource Discovery and Sequencing For each prioritized gap, the skill executes a web search via the repository's generic search utility to locate relevant study resources. It infers estimated study time from resource metadata (e.g., "3-hour video" or "2-day tutorial") and orders recommendations to respect technical dependencies. For example, the system sequences "Docker → Kubernetes" to ensure foundational knowledge precedes advanced topics. ## Report Persistence and Progress Tracking The final report merges the heatmap table and learning plan into a Markdown file saved under the `upskill/` directory. Filenames follow the pattern: ```markdown report-YYYY-MM-DD[--].md ``` Aggregate analyses use the date-only format, while targeted analyses append company and role identifiers. If a previous report exists, the new run calculates **gap-closed** and **new-gap** sections to visualize progress over time. After saving, the skill prints a confirmation message with the report path, allowing you to review the heatmap and learning plan at any time. ## Summary - **Binary gap scoring** (`gap_score = 1 – (candidate_has_skill ? 1 : 0)`) determines missing competencies by comparing [`CLAUDE.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/CLAUDE.md) against job requirements - **Dual execution modes** support both aggregate analysis of `job_search_tracker.csv` and targeted single-job analysis via URL arguments - **Configurable thresholds** filter which skill gaps receive prioritized learning resources - **Dependency-aware sequencing** orders study materials to respect prerequisite chains like Docker before Kubernetes - **Deterministic Markdown reports** save to `upskill/` with dated filenames and track progress through gap-closed metrics ## Frequently Asked Questions ### How does /upskill determine which skills are missing? The skill parses your current profile from [`CLAUDE.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/CLAUDE.md) and compares it against required skills extracted from job descriptions. It assigns a binary gap score of **1** for missing hard skills and **0** for present ones, while soft-skill gaps are identified through descriptive phrase matching. ### Can I analyze multiple job postings at once? Yes. Running `/upskill` without arguments triggers aggregate mode, which reads every entry from `job_search_tracker.csv` to identify patterns across your entire job search history. Targeted mode (`/upskill `) analyzes individual postings. ### Where are the heatmap reports stored? Reports save as Markdown files in the `upskill/` directory using the filename pattern `report-YYYY-MM-DD[--].md`. The system automatically tracks progress by comparing new reports against previous runs to identify closed gaps and new deficiencies. ### How does the learning plan prioritize study resources? The plan filters gaps using a configurable priority threshold, then sequences resources by inferred study time and technical dependencies. For example, it ensures you study containerization fundamentals before orchestration tools, respecting the logical progression of skills.