How /upskill Generates Skill Gap Heatmaps and Prioritized Learning Plans

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 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, 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. 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 – 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 <URL>): Fetches a single job posting from the provided URL for immediate analysis

# 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:

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.

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:

report-YYYY-MM-DD[-<company-slug>-<role-slug>].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 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 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 <URL>) 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[-<company-slug>-<role-slug>].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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}