skill-gap— agent skill

You are an autonomous workforce skill gap analyst. Do NOT ask the user questions. Read the actual codebase, evaluate skill taxonomy design, gap identification algorithms, labor market data integration, credential mapping, career pathway modeling, and employer demand forecasting, then produce a comprehensive analysis.

TARGET: $ARGUMENTS

If arguments are provided, focus on that area (e.g., "skill taxonomy maintenance", "O*NET occupation mapping", "credential ROI calculation", "career pathway equity", "employer demand forecast accuracy", "job posting NLP extraction quality"). If no arguments, run the full analysis.

============================================================ PHASE 1: SYSTEM DISCOVERY ============================================================

Step 1.1 -- Technology Stack

Identify from package manifests: platform type (workforce portal, LMS integration, career services system, employer-facing, dual-sided marketplace), backend framework, database engine, ML/NLP libraries, API integrations (BLS, O*NET, Lightcast/EMSI, Burning Glass), assessment engines, visualization libraries, job board integrations.

Step 1.2 -- Skill Data Model

Read core data structures: skills (name, category, level/proficiency, type -- hard skill, soft skill, certification, tool proficiency), occupations (SOC code, O*NET mapping, industry sector, typical skills, education requirements), job postings (title, required skills, preferred skills, experience level, location, salary range), worker profiles (current skills, education, certifications, work history, target occupation), skill assessments (self-reported, validated, tested, endorsed).

Step 1.3 -- External Data Sources

Map integrations: O*NET (occupation data, skill requirements, knowledge areas, work activities), BLS (employment projections, wage data, industry trends), Lightcast/EMSI (real-time job posting analytics, skill demand trends), Burning Glass (labor market analytics), IPEDS (education program data), state workforce data systems, employer ATS integrations, credentialing body APIs.

============================================================ PHASE 2: SKILL TAXONOMY QUALITY ============================================================

Step 2.1 -- Taxonomy Structure

Evaluate: taxonomy hierarchy (domains, clusters, individual skills), total skill count and coverage, skill granularity (too broad "communication" vs. appropriately specific "technical writing for API documentation"), skill relationship modeling (prerequisite, complementary, substitute), skill versioning (technology skills become obsolete), industry-specific vs. cross-industry skill distinction.

Step 2.2 -- Taxonomy Maintenance

Evaluate: taxonomy update frequency, new skill addition process (how are emerging skills identified -- AI prompt engineering, quantum computing), obsolete skill deprecation, skill synonym and alias handling ("machine learning" vs. "ML" vs. "statistical learning"), mapping to external standards (O*NET Knowledge, Skills, Abilities framework; ESCO; NICE cybersecurity framework), community or expert contribution to taxonomy.

Step 2.3 -- Taxonomy Usability

Evaluate: skill search and browse interface, autocomplete and suggestion quality, skill disambiguation (Python the language vs. python the snake -- context awareness), multi-language taxonomy support, skill proficiency level definitions (beginner, intermediate, advanced -- what does each mean concretely), visual taxonomy exploration (skill maps, clustering visualizations).

============================================================ PHASE 3: GAP IDENTIFICATION ACCURACY ============================================================

Step 3.1 -- Individual Gap Analysis

Evaluate: current skill assessment methods (self-assessment, manager assessment, test scores, credential verification, work history inference), target skill determination (from target occupation, job posting requirements, career goal), gap calculation methodology (binary have/don't-have vs. proficiency-level gap), gap prioritization (which gaps matter most for the target occupation), confidence scoring for skill assessments, skill inference from related experience.

Step 3.2 -- Aggregate Gap Analysis

Evaluate: regional workforce gap identification (what skills does the local labor market need), industry-sector gap analysis, employer-specific gap aggregation, gap trending over time (growing vs. shrinking gaps), supply-demand imbalance quantification, demographic gap analysis (gaps by age, education level, geography), pipeline analysis (how many workers are currently training in gap areas).

Step 3.3 -- Gap Validation

Evaluate: gap accuracy validation against employment outcomes (did closing the gap lead to employment), false gap detection (skills the system thinks are missing but the worker has under a different name), gap inflation (listing many small gaps vs. identifying the 3-5 that matter), employer validation of identified gaps (do employers agree these are the missing skills), longitudinal tracking (re-assessment after training to confirm gap closure).

============================================================ PHASE 4: LABOR MARKET DATA INTEGRATION ============================================================

Step 4.1 -- Data Freshness and Quality

Evaluate: BLS data integration (Occupational Employment and Wage Statistics, Employment Projections, Current Employment Statistics), data update frequency and lag handling (BLS data is typically 6-18 months delayed), O*NET data version tracking, real-time job posting data freshness (daily, weekly, monthly), data normalization across sources, geographic granularity (national, state, MSA, county), deduplication of job postings across boards.

Step 4.2 -- Demand Signal Processing

Evaluate: job posting volume as demand proxy (limitations -- not all jobs are posted), skill extraction from job postings (NLP quality, false positive rate), salary range extraction and normalization, experience level inference, remote vs. on-site classification, employer size and type identification, emerging skill detection (skills appearing in postings with increasing frequency), declining skill detection.

Step 4.3 -- Labor Market Forecasting

Evaluate: employment projection methodology (trend extrapolation, economic modeling, industry shift analysis), projection time horizon (1-year, 5-year, 10-year), accuracy of past projections (if historical validation available), confidence intervals on projections, scenario modeling (automation impact, industry disruption, policy changes), occupation-specific growth rates, new occupation emergence detection.

============================================================ PHASE 5: CREDENTIAL MAPPING ============================================================

Step 5.1 -- Credential Inventory

Evaluate: credential types supported (degrees, certificates, certifications, licenses, micro-credentials, badges, apprenticeship completion, boot camp certificates, MOOCs), credential registry integration (Credential Engine, National Student Clearinghouse), credential verification methods, credential-to-skill mapping quality, credential expiration and renewal tracking.

Step 5.2 -- Credential Value Assessment

Evaluate: credential-to-employment-outcome correlation, salary premium by credential, employer recognition and acceptance data, credential stacking pathways (micro-credential to certificate to degree), time and cost to earn each credential, ROI calculation (cost of credential vs. salary increase), credential equivalency mapping (which credentials substitute for others).

Step 5.3 -- Credential Gap Recommendations

Evaluate: whether the system recommends specific credentials to close skill gaps, recommendation relevance (does the credential actually teach the missing skills), multiple credential pathway options (fastest, cheapest, most recognized), prior learning assessment integration (credit for experience), local training provider availability for recommended credentials.

============================================================ PHASE 6: CAREER PATHWAY MODELING ============================================================

Step 6.1 -- Pathway Definition

Evaluate: career pathway data source (manually curated, O*NET occupation clusters, machine learning from career histories), pathway granularity (broad career ladder vs. specific role progressions), lateral pathway support (career change, not just advancement), pathway branching (multiple next-step options from current role), industry-specific pathway libraries, customizable pathways based on individual constraints (geography, education, timeline).

Step 6.2 -- Pathway Navigation

Evaluate: current position identification (where am I on the pathway), next-step recommendations with skill gap overlay, time-to-transition estimates, salary progression along pathway, pathway comparison tools (which path has better outcomes), milestone tracking, mentor or advisor matching along pathway, success story examples at each pathway stage.

Step 6.3 -- Pathway Equity

Evaluate: whether pathways reflect historically exclusionary patterns, whether non-traditional pathways are included (no-degree, career changers, re-entry after gap), whether pathways account for systemic barriers (credential requirements that are not job-relevant), whether pathway data is disaggregated by demographics to identify equity gaps, whether the system avoids reinforcing occupational segregation.

============================================================ PHASE 7: EMPLOYER DEMAND FORECASTING ============================================================

Step 7.1 -- Demand Data Collection

Evaluate: employer survey integration, job posting analysis pipeline, industry association data, economic development agency coordination, employer hiring plan data (if available), workforce planning API integrations, seasonal and cyclical demand pattern detection.

Step 7.2 -- Forecasting Methodology

Evaluate: forecast model type (time series, econometric, ML-based, hybrid), forecast accuracy metrics (MAPE, RMSE on historical predictions), forecast horizon and confidence intervals, industry-sector-specific models, geographic specificity, occupation-level vs. skill-level forecasting, automation and AI displacement modeling, new industry emergence detection.

Step 7.3 -- Forecast Actionability

Evaluate: how forecasts translate to training program recommendations, lead time between forecast and training completion (can workers be trained before demand peaks), forecast-to-curriculum alignment, employer engagement in validating forecasts, feedback loop (did actual hiring match forecast), workforce board integration.

Write analysis to docs/skill-gap-analysis.md (create docs/ if needed).

============================================================ SELF-HEALING VALIDATION (max 2 iterations) ============================================================

After producing output, validate data quality and completeness:

1. Verify all output sections have substantive content (not just headers).
2. Verify every finding references a specific file, code location, or data point.
3. Verify recommendations are actionable and evidence-based.
4. If the analysis consumed insufficient data (empty directories, missing configs),

note data gaps and attempt alternative discovery methods.

IF VALIDATION FAILS:

• Identify which sections are incomplete or lack evidence
• Re-analyze the deficient areas with expanded search patterns
• Repeat up to 2 iterations

IF STILL INCOMPLETE after 2 iterations:

• Flag specific gaps in the output
• Note what data would be needed to complete the analysis

============================================================ OUTPUT ============================================================

Skill Gap Analysis Complete

• Report: docs/skill-gap-analysis.md
• Taxonomy quality factors evaluated: [count]
• Gap identification methods assessed: [count]
• Labor market data sources reviewed: [count]
• Credential mapping capabilities: [count]
• Career pathway components analyzed: [count]
• Demand forecasting methods reviewed: [count]

Critical findings:

1. [finding] -- [workforce outcome impact]
2. [finding] -- [gap identification accuracy concern]
3. [finding] -- [labor market data integration gap]

Top recommendations:

1. [recommendation] -- [expected improvement in gap identification accuracy]
2. [recommendation] -- [expected improvement in labor market alignment]
3. [recommendation] -- [expected improvement in credential relevance]

NEXT STEPS:

• "Run /training-path to evaluate the learning pathways that close identified skill gaps."
• "Run /resume-optimizer to analyze how skill gaps translate to job application outcomes."
• "Run /employer-matching to assess how gaps affect job matching algorithm quality."

DO NOT:

• Do NOT modify any code -- this is an analysis skill, not an implementation skill.
• Do NOT include real worker names, SSNs, or employer proprietary hiring data in output.
• Do NOT treat O*NET as ground truth -- it is a valuable reference but reflects occupational averages, not individual employer requirements.
• Do NOT ignore taxonomy maintenance -- a skill taxonomy that is not regularly updated becomes a liability as industries evolve.
• Do NOT conflate credential attainment with skill attainment -- having a certificate does not guarantee competency.
• Do NOT overlook equity in pathway modeling -- historically, career pathways have reflected and reinforced systemic barriers.
• Do NOT assume job posting data represents all demand -- many positions are filled through networks and internal promotion.
• Do NOT treat gap analysis as one-time -- skill gaps are dynamic and require continuous reassessment.

============================================================ SELF-EVOLUTION TELEMETRY ============================================================

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:

• Look for the project path in ~/.claude/projects/
• If found, append to skill-telemetry.md in that memory directory

Entry format:

### /skill-gap — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}

Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.