SkillGap: Building an AI-Powered Career Assistant

Source: Dev.to

The Problem

Job descriptions are hard to read. They are long, full of buzzwords, and it is genuinely difficult to know if you qualify. Most people either:

• Talk themselves out of jobs they could get, or
• Apply to roles they are not ready for.

There is no quick, honest way to compare your skills to what a job actually needs. That is the problem we wanted to solve.

Our Solution

SkillGap does the comparison for you.

1. Paste a job description into the app.
2. The app checks it against your saved skill profile.
3. You receive a match score, a breakdown of your skills into three groups (Have / Missing / Bonus), and a personalized AI learning roadmap.

You get a clear, actionable plan instead of a guess. As you learn and update your profile, your results improve too.

Team Division

AI Tools We Used

Split: Claude Web for planning, Antigravity for building.

Core Architecture

Authentication

Everything in SkillGap depends on knowing who the user is.

• Implemented JWT‑based authentication (signup, login, logout, protected routes).
• Passwords are salted and hashed before reaching the database.
• JWT tokens are validated on every protected request.

Built first because every other feature depends on it.

Skill Profile CRUD

On top of auth, we built full CRUD operations for the skill profile.

• Users can add, edit, and delete skills at any time.
• Changes persist immediately, so every new analysis uses the latest profile version.

Database Design

• SQLAlchemy schema covers users, skill profiles, and analysis history.
• The history table lets users look back at past analyses and track match‑score improvements over time.
• Alembic handles migrations; each schema change is a migration file that can be reviewed, tested, and rolled back cleanly.

Matching Engine

This is the core algorithm of the product.

1. Input: Job description + user’s skill profile.
2. Process: Compare both against a curated list of tech skills.
3. Output:
   • Have: Skills the user possesses that the job wants.
   • Missing: Skills the job wants that the user does not have.
   • Bonus: Skills the user brings that the job did not ask for.

• Keyword normalization maps variations (e.g., “React”, “ReactJS”, “React.js”) to a single entry.
• Vocabulary covers frontend, backend, infrastructure, and data tools.
• Engine lives in its own module, separate from auth and profile modules → easy unit testing and future extension.

Visual Feedback

• Animated SVG ring shows the match score:
  • Green → strong match
  • Yellow → partial match
  • Red → significant gap
• Ring draws progressively on page load, giving a “calculation” feel.
• Below the ring, a three‑column view lists the exact skills behind the score.

Design & Planning with Claude Web

Before writing any code, Jing used Claude Web to work through the project design in plain language. The conversations helped:

• Pin down the core user flow.
• Decide which features to build first.
• Surface unanswered PRD questions (e.g., handling unknown skills, onboarding for new users).

Getting those decisions made early saved significant debugging time later.

AI‑Powered Learning Roadmap

1. Extraction engine identifies missing skills.
2. FastAPI backend sends those skills + original job description to the Claude API.
3. Claude returns a structured JSON roadmap:

{
  "steps": [
    {
      "skill": "Docker",
      "resources": ["Docker Docs", "Docker for Beginners (Udemy)"],
      "estimated_time": "4h",
      "explanation": "Docker is required for containerizing the microservices mentioned in the JD."
    }
    // …
  ]
}

4. React frontend parses the JSON and renders a row of cards, one per topic, creating an easy‑to‑read, actionable plan.

Not a generic list of links – a personalized, ordered plan built around the specific job needs.

Testing Strategy

Extraction Engine (Deterministic)

• Strict TDD: Tests written before implementation.
• Each module in server/tests/ has a corresponding test_.py.
• CI pipeline blocks any merge that drops pytest coverage below 80 %.

Claude Roadmap (Non‑Deterministic)

• Built an AI Assessment Test Suite that scores each response on three dimensions:
  1. Relevance – Do the resources match the missing skill?
  2. Specificity – Are the steps concrete rather than vague?
  3. Completeness – Does it cover every missing skill?
• Scores feed into an evaluation dashboard.

Security Challenges

1. Client‑side score spoofing – The match score was being calculated on the React side, allowing manipulation.
2. (Second issue omitted in original excerpt – placeholder for completeness).

Both issues were addressed by moving critical calculations to the backend and enforcing strict token validation.

Summary

SkillGap combines robust authentication, dynamic skill‑profile management, a smart matching engine, and AI‑generated learning roadmaps to give job seekers a clear, actionable path toward the roles they want. By leveraging Claude Web for planning and Antigravity for implementation, the team delivered a cohesive product while maintaining high code quality through TDD and a dedicated AI assessment framework.

Overview

We identified and fixed two critical issues in the original implementation:

1. Client‑side score manipulation – The frontend was sending a calculated score to the FastAPI backend, allowing a user to tamper with the value before it was stored.
   Solution: Move the calculation entirely to the server so any client‑provided score is ignored.

2. Unhandled SQLAlchemy exceptions – Database errors produced 500 responses that exposed full stack traces, leaking internal implementation details.
   Solution: Add a global error handler that logs the full traceback server‑side and returns a clean, safe error message to the client.

Both problems were caught during code review before reaching production.

UI Improvements

• Responsive feel: Added a focused UI pass to make the app feel snappy, especially during the Claude API call (which takes a few seconds).
• Staggered animations: Used framer‑motion to animate skill columns and roadmap cards one after another, giving a progressive reveal rather than an abrupt dump.
• Skeleton UI: While the Claude API call is in flight, the results panel displays a skeleton placeholder that matches the shape of the final content, reducing perceived wait time.

Design Workflow

1. Sketch → Claude Web → Production

   • Liuyi started with a hand‑drawn dashboard sketch.
   • The sketch was fed into Claude Web, which generated a detailed wireframe with component suggestions and layout reasoning.
   • The wireframe became the design spec for the production implementation, built with Antigravity inside the IDE.

   Result: Having a concrete reference before writing any React code led to fewer design guesses and fewer rewrites.

CI/CD Pipeline

• Every pull request runs a multi‑stage GitHub Actions pipeline before it can merge:

  1. Lint – ruff (Python) and ESLint (JS/TS)
  2. Security scan
  3. Pytest
  4. Build

• Coverage gate: Backend test coverage must stay ≥ 80 %; otherwise the pipeline fails and the PR is blocked.

• Secrets management: API keys, JWT secrets, and DB connection strings live only in GitHub Secrets and are injected at runtime.

• Deploy: The app auto‑deploys to Render when main is updated.

This enforces quality standards that are easy to skip when they exist only in documentation.

Automated Evaluation of AI‑Generated Roadmaps

1. After Claude produces a roadmap, a second LLM call evaluates it.
2. The evaluator receives the roadmap, the original missing‑skill list, and the job description, then scores the response on Relevance, Specificity, and Completeness using a fixed rubric.

Why? Using AI to evaluate AI output provides a scalable way to test non‑deterministic results, delivering consistent, structured scores that can be tracked over time. Human review is still valuable, but this automation gives a quantitative quality signal.

• Liuyi ran the full evaluation suite on real test data and fed the results back into Claude Web.
• Claude Web generated an evaluation webpage artifact: a clean summary of all scores with notes explaining high and low marks.

The page serves two purposes:

• Provides a concrete quality signal on the Claude API integration.
• Produces shareable documentation that shows exactly how the AI output was measured and what the results were.

Tooling: Claude Web vs. Antigravity

Mixing the two roles would have slowed us down. Copy‑pasting code from a chat window adds friction, and using a conversational tool for implementation loses the iterative loop that surfaces better decisions. Keeping each tool in its optimal role made both more effective.

Future Technical Upgrades

1. Semantic skill matching – Replace keyword extraction with sentence‑transformer embeddings. The current engine only matches exact keywords; semantic embeddings would recognize that “component‑based UI development” maps to React, expanding coverage to plain‑English job descriptions.
2. Resume parsing – Allow users to upload a resume and automatically build their skill profile.
3. Reverse analysis mode – Enable employers to check a candidate’s profile against a job posting.

Reflections on SkillGap

• Origin: Started as a class project, now a showcase piece.
• Modular architecture: Enabled independent work without stepping on each other’s code.
• Shared conventions: A .antigravityrules file codified conventions before they became conflicts.
• AI division of labor: Planning with Claude Web and implementation with Antigravity gave speed without sacrificing output quality.

Key takeaway: AI tools accelerate a solid engineering process, but they don’t replace the need for disciplined development practices.

Project Summary

SkillGap — Tech Stack Skill Gap Analyzer
A web app that helps job seekers identify skill gaps from job descriptions.

• Paste a JD → see your match score → get an AI‑generated learning roadmap.

Team

• Jing Ng
• Liuyi Yang

Tech Stack

Features

• JD parsing & skill‑gap scoring
• AI‑generated learning roadmaps
• Interactive dashboard with animated UI
• Automated CI/CD with linting, security scanning, testing, and coverage enforcement
• Secure secret handling & Render deployment

Screenshots

• Login page
• Sign‑up page
• Profile setup page
• Main dashboard – Skill match analysis

System Architecture

(Insert architecture diagram here)

Request Flow When a User Submits a Job Description

1. User Action – The user pastes a job description into the UI.
2. Server Processing –
   • The server compares the job description against the user’s saved skill profile.
   • It calculates a match score.
   • It sends the gap information to Claude AI.
3. AI Generation – Claude AI generates a personalized learning plan to close the identified skill gaps.
4. Result – The learning plan is returned to the frontend and displayed to the user.

Technologies Involved: Frontend (React), Backend (FastAPI), Database, Claude API

Project Structure

SkillGap/
├── client/           # React frontend (Vite, Tailwind, Zustand)
├── server/           # FastAPI backend
│   ├── tests/        # pytest test suite
│   └── …            # other backend modules
└── …                # additional top‑level files (README, .gitignore, etc.)

View on GitHub (replace # with the actual repository URL)