resume-parser-ats 1.1.0 → 1.2.0

package/README.md

@@ -1,4 +1,4 @@
-# 📄 Resume Parser
+# 📄 Resume Parser — Agent Skill
 
 <p align="center">
   <strong>Deep resume parsing • ATS compatibility scoring • Actionable improvement insights</strong>
@@ -10,19 +10,30 @@
 
 ---
 
-A powerful agent skill that deeply parses resumes using the **OpenResume 4-step algorithm**, extracts structured information (Name, Email, Phone, Education, Work Experience, Skills, Projects), evaluates ATS (Applicant Tracking System) compatibility, and provides prioritized, actionable suggestions to improve your resume.
+An **agent skill** that deeply parses resumes using the **OpenResume 4-step algorithm**, extracts structured information (Name, Email, Phone, Education, Work Experience, Skills, Projects), evaluates ATS (Applicant Tracking System) compatibility, and provides prioritized, actionable suggestions to improve your resume.
 
 ## ✨ Features
 
 - **🔍 Deep Parsing** — Extracts 10+ fields from raw text or PDF using a feature-scoring engine
 - **📊 ATS Scoring** — Grades your resume A+ through F with detailed per-field confidence ratings
 - **💡 Smart Suggestions** — Prioritized, categorized fixes (critical → low) with before/after examples
+- **🤖 Agent Skill** — Install via `npx skills add` and use directly in your agent
 - **🛠️ CLI & MCP Server** — Use interactively from the command line or as an MCP tool
 - **⚙️ Configurable Strictness** — Lenient, moderate, or strict ATS evaluation modes
 - **🔒 Zero Dependencies on Proprietary APIs** — Runs entirely locally with no external calls
 
 ## 📦 Installation
 
+### As an Agent Skill (recommended)
+
+```bash
+npx skills add dhanushk-offl/resume-parser-skill
+```
+
+After installing, the skill is automatically available to your agent. When the agent encounters a resume-related task, it will load the skill and use it.
+
+### Manual Setup
+
 ```bash
 # Clone the repo
 git clone https://github.com/dhanushk-offl/resume-parser-skill.git
@@ -37,26 +48,34 @@ npm run build
 
 ## 🚀 Usage
 
-### As a CLI Tool
+### As an Agent Skill
+
+Once installed via `npx skills add`, the agent will automatically use this skill when you:
+
+- Ask to parse, review, or analyze a resume
+- Ask "is my resume ATS-friendly?"
+- Ask for resume improvement suggestions
+- Upload or reference a resume PDF
+
+The agent can invoke three tools:
+
+| Tool | Description |
+|------|-------------|
+| `parse_resume` | Parse a resume PDF or raw text → structured data |
+| `analyze_resume` | Parse + compute ATS compatibility score with per-field confidence |
+| `suggest_improvements` | Parse + analyze + generate prioritized improvement suggestions |
+
+### From the CLI (after manual setup)
 
 ```bash
 # Parse a resume and output structured data
-npx resume-parser parse resume.pdf
+node resume-parser-ats/scripts/parse.mjs resume.pdf
 
 # Parse + analyze ATS compatibility
-npx resume-parser analyze resume.pdf
+node resume-parser-ats/scripts/analyze.mjs resume.pdf
 
 # Full pipeline: parse + analyze + actionable suggestions
-npx resume-parser insights resume.pdf
-
-# Parse from raw text
-npx resume-parser parse "John Doe\njohn@email.com\nSoftware Engineer"
-
-# Adjust ATS strictness
-npx resume-parser analyze resume.pdf --strictness strict
-
-# Focus on specific areas
-npx resume-parser insights resume.pdf --focus ats,formatting --json
+node resume-parser-ats/scripts/insights.mjs resume.pdf --strictness strict --focus ats,formatting
 ```
 
 ### As a Library
@@ -145,7 +164,7 @@ Each attribute (Name, Email, Phone, etc.) has **feature sets** — matching func
 > *Before applying to jobs, run your resume through the parser to see what an ATS actually extracts.*
 
 ```bash
-npx resume-parser insights my-resume.pdf --strictness strict --json
+node resume-parser-ats/scripts/insights.mjs my-resume.pdf --strictness strict
 ```
 
 Identify critical issues like a missing email, unparseable name, or sections an ATS can't detect — and fix them *before* you apply.
@@ -179,10 +198,6 @@ import { fullPipeline } from "resume-parser-ats";
 
 const result = fullPipeline({ rawText: resumeText, strictness: "strict" });
 
-// result.parsed — structured data
-// result.analyzed — ATS score + field analysis
-// result.suggestions — prioritized actions
-
 // Feed to an LLM for natural-language coaching
 const prompt = `You are a resume coach. Here is the analysis:
 ${JSON.stringify(result.analyzed.data)}
@@ -206,44 +221,36 @@ Suggest improvements in a friendly, encouraging tone.`;
 - Flag common issues (missing dates, non-standard section headers)
 - Provide standardized improvement templates
 
-### 6. 🔄 Resume Migration Tool
-
-> *Convert resumes from one format to structured JSON for database ingestion.*
-
-```typescript
-import { parseResume } from "resume-parser-ats";
-
-const result = parseResume({ filePath: "legacy-resume.pdf" });
-// result.data is a clean, typed JSON object ready for your database
-```
-
 ## 🏗️ Architecture
 
 ```
-resume-parser/
-├── package.json              # Project metadata & scripts
-├── README.md                 # This file
-├── LICENSE                   # MIT License — Dhanush Kandhan
-├── AGENTS.md                 # Agent-facing configuration
-├── SKILL.md                  # Skill definition for agent consumption
-├── src/
-│   ├── index.ts              # Main entry point + fullPipeline()
+resume-parser-skill/
+├── resume-parser-ats/           # Agent skill directory
+│   ├── SKILL.md                # Skill manifest & instructions
+│   ├── scripts/                # Executable scripts for agent use
+│   │   ├── parse.mjs           # Parse a resume → JSON
+│   │   ├── analyze.mjs         # Parse + ATS scoring → JSON
+│   │   └── insights.mjs        # Full pipeline → JSON
+│   └── references/             # Detailed docs loaded on-demand
+│       └── algorithm.md        # Full algorithm specification
+├── src/                        # TypeScript source
+│   ├── index.ts                # Main entry point + fullPipeline()
 │   ├── tools/
-│   │   ├── parse-resume.ts           # Step 1-4 parsing engine
-│   │   ├── analyze-resume.ts         # ATS scoring & analysis
-│   │   └── suggest-improvements.ts   # Fix suggestions generator
+│   │   ├── parse-resume.ts
+│   │   ├── analyze-resume.ts
+│   │   └── suggest-improvements.ts
 │   └── prompts/
-│       ├── parser-prompt.ts          # Prompt templates for parsing
-│       └── insights-prompt.ts        # Prompt templates for insights
-├── mcp-server/
-│   └── server.ts             # MCP server implementation
+│       ├── parser-prompt.ts
+│       └── insights-prompt.ts
 ├── bin/
-│   └── cli.js                # CLI entry point
-└── test/
-    └── evals/                # Evaluation test suites
-        ├── parse-resume.test.js
-        ├── analyze-resume.test.js
-        └── suggest-improvements.test.js
+│   └── cli.js                  # CLI entry point
+├── mcp-server/
+│   └── server.ts               # MCP server implementation
+├── test/
+│   └── evals/                  # Evaluation test suites
+├── AGENTS.md                   # Agent configuration
+├── package.json
+└── README.md
 ```
 
 ## 🧪 Testing
@@ -251,13 +258,10 @@ resume-parser/
 ```bash
 # Run all tests
 npm test
-
-# Run evaluation suites
-node --test test/evals/parse-resume.test.js
-node --test test/evals/analyze-resume.test.js
-node --test test/evals/suggest-improvements.test.js
 ```
 
+86 tests covering parsing, analysis, and suggestion generation across all strictness levels.
+
 ## 🤝 Contributing
 
 1. Fork the repository
@@ -268,19 +272,10 @@ node --test test/evals/suggest-improvements.test.js
 
 ## ☁️ CI/CD
 
-This project uses GitHub Actions for continuous integration and npm publishing:
-
 | Workflow | Trigger | What it does |
 |----------|---------|-------------|
 | **Build & Test** | Push/PR to `master` | Lint, build, and test across Node 18/20/22 |
-| **Publish to npm** | Tag push `v*` (e.g. `v1.0.0`) | Builds and publishes to npmjs with provenance |
-
-To publish a new version:
-
-```bash
-npm version patch   # or minor, major
-git push --follow-tags
-```
+| **Publish to npm** | Tag push `v*` | Builds and publishes to npmjs with provenance |
 
 ## 📄 License
 

package/bin/cli.js

@@ -4,9 +4,9 @@
  * Resume Parser — CLI Entry Point
  *
  * Usage:
- *   resume-parser parse <file|text>          Parse a resume and output structured data
- *   resume-parser analyze <file|text>         Parse + analyze ATS compatibility
- *   resume-parser insights <file|text>       Full pipeline: parse + analyze + suggestions
+ *   resume-parser-ats parse <file|text>          Parse a resume and output structured data
+ *   resume-parser-ats analyze <file|text>         Parse + analyze ATS compatibility
+ *   resume-parser-ats insights <file|text>       Full pipeline: parse + analyze + suggestions
  */
 
 const path = require("path");
@@ -24,7 +24,7 @@ function printUsage() {
 Resume Parser CLI — Deep resume parsing with ATS insights
 
 Usage:
-  resume-parser <command> <input> [options]
+  resume-parser-ats <command> <input> [options]
 
 Commands:
   parse <file|text>       Parse a resume and output structured data
@@ -38,10 +38,10 @@ Options:
   --help                  Show this help message
 
 Examples:
-  resume-parser parse resume.pdf
-  resume-parser analyze resume.pdf --strictness strict
-  resume-parser insights resume.pdf --focus ats,formatting --json
-  resume-parser parse "John Doe\\njohn@email.com\\nSoftware Engineer"
+  resume-parser-ats parse resume.pdf
+  resume-parser-ats analyze resume.pdf --strictness strict
+  resume-parser-ats insights resume.pdf --focus ats,formatting --json
+  resume-parser-ats parse "John Doe\\njohn@email.com\\nSoftware Engineer"
 `);
 }
 

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "resume-parser-ats",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "An agent skill that deeply parses resumes, extracts structured data, and provides actionable insights to improve ATS compatibility and readability.",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
   "bin": {
-    "resume-parser": "bin/cli.js"
+    "resume-parser-ats": "bin/cli.js"
   },
   "scripts": {
     "build": "tsc",
@@ -18,6 +18,7 @@
   "files": [
     "dist/",
     "bin/",
+    "resume-parser-ats/",
     "README.md",
     "LICENSE"
   ],
@@ -27,7 +28,9 @@
     "ATS",
     "agent-skill",
     "resume-parser",
-    "career"
+    "career",
+    "skills",
+    "npx-skills"
   ],
   "author": "dhanush",
   "license": "MIT",

package/resume-parser-ats/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: resume-parser-ats
+description: >
+  Deeply parses resume PDFs using the OpenResume 4-step algorithm, extracts structured information
+  (Name, Email, Phone, Education, Work Experience, Skills, etc.), evaluates ATS compatibility,
+  and provides actionable improvement suggestions. Use when a user asks to parse, review, or
+  analyze a resume, check ATS-friendliness, or get resume improvement suggestions.
+---
+
+# Resume Parser — ATS Intelligence
+
+You are a resume parsing and ATS analysis specialist. When activated, deeply parse resumes and provide structured, actionable insights.
+
+## When to Activate
+
+- User asks to parse, review, or analyze a resume
+- User asks "is my resume ATS-friendly?"
+- User asks for resume improvement suggestions
+- User uploads or references a resume PDF
+- User wants to compare what an ATS sees vs. their intended content
+
+## Tools Available
+
+For programmatic use, install the npm package:
+
+```bash
+npm install resume-parser-ats
+```
+
+### `parse_resume` — Extract structured data from a resume
+
+```bash
+npx resume-parser-ats parse <file.pdf>
+```
+
+```javascript
+import { parseResume } from "resume-parser-ats";
+const result = parseResume({ filePath: "/path/to/resume.pdf" });
+// or: parseResume({ rawText: "John Doe\njohn@email.com..." })
+```
+
+**Input**: `{ filePath?: string, rawText?: string }`
+**Output**: Structured data with profile, education, experience, skills, projects.
+
+---
+
+### `analyze_resume` — Parse + ATS compatibility scoring
+
+```bash
+npx resume-parser-ats analyze <file.pdf> --strictness strict
+```
+
+```javascript
+import { analyzeResume } from "resume-parser-ats";
+const result = analyzeResume({ filePath: "/path/to/resume.pdf", strictness: "moderate" });
+```
+
+**Input**: `{ filePath?, rawText?, strictness?: "lenient"|"moderate"|"strict" }`
+**Output**: ATS score (0-100), letter grade (A+ to F), per-field confidence, section detection, format issues.
+
+---
+
+### `suggest_improvements` — Parse + analyze + prioritized suggestions
+
+```bash
+npx resume-parser-ats insights <file.pdf> --strictness strict --focus ats,formatting
+```
+
+```javascript
+import { suggestImprovements } from "resume-parser-ats";
+const result = suggestImprovements({ filePath: "/path/to/resume.pdf", focusAreas: ["ats", "content"] });
+```
+
+**Input**: `{ filePath?, rawText?, strictness?, focusAreas?: string[] }`
+**Output**: Overall score, grade, quick wins, prioritized suggestions (critical → low), section analysis.
+
+---
+
+## Manual Parsing Algorithm
+
+Use this algorithm when the npm package is unavailable or for understanding the parsing logic:
+
+### Step 1: Read Text Items from PDF
+
+Extract all text items from the PDF. Each item includes:
+- `text` — text content
+- `x1`, `x2` — left/right X positions (origin at bottom-left)
+- `y` — Y position from bottom
+- `bold` — whether text is bold
+- `newLine` — whether this item starts a new line
+
+### Step 2: Group Text Items into Lines
+
+1. **Merge adjacent items**: When `Distance = RightTextItem.X₁ - LeftTextItem.X₂` is less than average character width, merge them
+2. **Average character width**: Total character widths / total character count (exclude bold and newline elements)
+3. **Group by Y-coordinate**: Same Y = same line
+
+### Step 3: Group Lines into Sections
+
+**Section title detection** (must satisfy ALL 3):
+1. It is the only text item in the line
+2. It is bolded
+3. Its letters are all UPPERCASE
+
+**Fallback**: Keyword match against known headers:
+PROFILE, SUMMARY, OBJECTIVE, ABOUT, EDUCATION, ACADEMIC, DEGREES, EXPERIENCE, WORK EXPERIENCE, EMPLOYMENT, PROFESSIONAL EXPERIENCE, SKILLS, TECHNICAL SKILLS, COMPETENCIES, PROJECTS, PORTFOLIO, CERTIFICATIONS, LICENSES, HONORS, AWARDS, VOLUNTEER, COMMUNITY, LEADERSHIP, PUBLICATIONS, RESEARCH, INTERESTS, ACTIVITIES, HOBBIES
+
+Lines before any section title go into PROFILE.
+
+### Step 4: Extract Attributes via Feature Scoring
+
+Each attribute has feature sets (matching function + score). The text item with the **highest total score** wins.
+
+| Attribute | Core Feature | Regex |
+|-----------|-------------|-------|
+| Name | Only letters/spaces/periods | `/^[a-zA-Z\s\.]+$/` |
+| Email | Email format | `/\S+@\S+\.\S+/` |
+| Phone | Phone format | `/\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}/` |
+| Location | City, ST format | `/[A-Z][a-zA-Z\s]+, [A-Z]{2}/` |
+| URL | URL format | `/\S+\.[a-z]+\/\S+/` |
+
+**Name scoring example**: Only letters (+3), bolded (+2), uppercase (+2), has @ (-4), has digit (-4), has comma (-4), has slash (-4)
+
+**Subsection detection** (for Education, Work Experience):
+- Primary: vertical line gap > typical line gap × 1.4
+- Fallback: text item is bolded
+
+See [references/algorithm.md](references/algorithm.md) for the full specification.
+
+---
+
+## ATS Compatibility Scoring
+
+| Dimension | Weight |
+|-----------|--------|
+| Name extraction | 20 pts |
+| Email extraction | 20 pts |
+| Phone extraction | 10 pts |
+| Section detection | 15 pts |
+| Education parsing | 10 pts |
+| Experience parsing | 15 pts |
+| Skills parsing | 10 pts |
+
+**Grading**: A+ (90-100), A (85-89), B+ (80-84), B (75-79), B- (70-74), C+ (65-69), C (60-64), D (50-59), F (0-49)
+
+## Issue Severity Levels
+
+- **CRITICAL**: Name or email cannot be parsed → ATS will likely discard
+- **HIGH**: Key sections missing, dates unparseable, phone not found
+- **MEDIUM**: Skills not extracted cleanly, formatting merge issues
+- **LOW**: Minor inconsistencies, optional fields missing
+
+## Output Format
+
+Always provide results in this structured format:
+
+```
+## 📊 Resume Parsing Report
+
+### ATS Compatibility Score: XX/100 (Grade: X)
+
+### ✅ Successfully Parsed Fields
+| Field | Parsed Value | Confidence |
+|-------|-------------|------------|
+| Name  | John Doe    | High       |
+
+### ⚠️ Issues Found
+| # | Severity | Field | Issue | Suggestion |
+|---|----------|-------|-------|------------|
+| 1 | CRITICAL | Email | ...  | ...        |
+
+### 📝 Priority Fixes
+1. **[Fix Title]**: Description of what to change and why
+   - Before: `current state`
+   - After: `suggested state`
+
+### 📋 Section-by-Section Analysis
+#### Profile
+- Analysis notes...
+```
+
+## Important Rules
+
+1. **Always run all 4 parsing steps** — do not skip steps
+2. **Always provide the ATS compatibility score** — this is the primary metric
+3. **Every suggestion must be actionable** — not "improve formatting" but "Move the date to the same line as the company name"
+4. **Prioritize Name and Email extraction** — if they fail, flag as CRITICAL
+5. **Explain WHY** each suggestion matters in ATS terms
+6. **Compare parsed output vs. likely intended content** — surface discrepancies
+7. **Never modify the original file** — this is a read-only analysis tool
+8. **If a PDF cannot be parsed**, fall back to raw text and note the limitation
+9. **Flag when text items break unexpectedly** (e.g., phone numbers split across items)
+
+## Programmatic Access
+
+For batch processing or integration, install the npm package:
+
+```bash
+npm install resume-parser-ats
+npx resume-parser-ats parse resume.pdf
+npx resume-parser-ats analyze resume.pdf --strictness strict
+npx resume-parser-ats insights resume.pdf --focus ats,formatting --json
+```

package/resume-parser-ats/references/algorithm.md

@@ -0,0 +1,126 @@
+# OpenResume 4-Step Parsing Algorithm
+
+This document provides the full technical reference for the resume parsing algorithm.
+
+## Step 1: Read Text Items from PDF
+
+Extract all text items from the PDF using `pdfjs-dist`. Each text item includes:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `text` | string | The text content |
+| `x1` | number | Left X position |
+| `x2` | number | Right X position |
+| `y` | number | Y position (from page bottom) |
+| `bold` | boolean | Whether the text is bold |
+| `newLine` | boolean | Whether this item starts a new line |
+
+X,Y coordinates are relative to the bottom-left corner (origin 0,0).
+
+## Step 2: Group Text Items into Lines
+
+1. **Merge adjacent items** when `Distance = RightTextItem.X₁ - LeftTextItem.X₂` is less than average character width
+2. Average character width = total character widths / total character count (exclude bold and newline elements)
+3. **Group by Y-coordinate** to form lines (same Y = same line)
+
+This reconstructs the line-by-line reading order that may be lost in PDF extraction.
+
+## Step 3: Group Lines into Sections
+
+### Section Title Detection (primary heuristic — must satisfy ALL 3):
+
+1. It is the only text item in the line
+2. It is bolded
+3. Its letters are all UPPERCASE
+
+### Fallback Heuristic: Keyword matching
+
+Known section titles: PROFILE, SUMMARY, OBJECTIVE, ABOUT, EDUCATION, ACADEMIC, DEGREES, EXPERIENCE, WORK EXPERIENCE, EMPLOYMENT, PROFESSIONAL EXPERIENCE, SKILLS, TECHNICAL SKILLS, COMPETENCIES, PROJECTS, PORTFOLIO, CERTIFICATIONS, LICENSES, HONORS, AWARDS, VOLUNTEER, COMMUNITY, LEADERSHIP, PUBLICATIONS, RESEARCH, INTERESTS, ACTIVITIES, HOBBIES
+
+- Group all lines under their closest preceding section title
+- Lines before any section title go into the PROFILE section
+
+## Step 4: Extract Resume Attributes using Feature Scoring
+
+Each attribute has **feature sets** (matching function + score). Run every text item through all feature sets for an attribute. The text item with the **highest total feature score** is extracted as that attribute.
+
+### Subsection Detection (for Education, Work Experience, etc.)
+
+- **Primary**: vertical line gap > typical line gap × 1.4
+- **Fallback**: text item is bolded
+
+### Feature Scoring Tables
+
+#### Name
+
+| Feature | Score |
+|---------|-------|
+| Contains only letters, spaces or periods | +3 |
+| Is bolded | +2 |
+| Contains all uppercase letters | +2 |
+| Contains @ (may be email) | -4 |
+| Contains number (may be phone) | -4 |
+| Contains , (may be address) | -4 |
+| Contains / (may be URL) | -4 |
+
+#### Email
+
+| Feature | Score |
+|---------|-------|
+| Matches email regex `\S+@\S+\.\S+` | +5 |
+| Contains @ | +2 |
+
+#### Phone
+
+| Feature | Score |
+|---------|-------|
+| Matches phone regex `\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}` | +5 |
+
+#### Location
+
+| Feature | Score |
+|---------|-------|
+| Matches city,state regex `[A-Z][a-zA-Z\s]+, [A-Z]{2}` | +5 |
+
+#### URL
+
+| Feature | Score |
+|---------|-------|
+| Matches URL regex `\S+\.[a-z]+\/\S+` | +5 |
+
+#### School
+
+| Feature | Score |
+|---------|-------|
+| Contains school keyword (College, University, School, Institute, Academy) | +4 |
+
+#### Degree
+
+| Feature | Score |
+|---------|-------|
+| Contains degree keyword (Associate, Bachelor, Master, Doctorate, B.S., B.A., M.S., M.A., Ph.D.) | +4 |
+
+#### GPA
+
+| Feature | Score |
+|---------|-------|
+| Matches GPA regex `[0-4]\.\d{1,2}` | +5 |
+
+## ATS Compatibility Scoring Framework
+
+| Dimension | Weight |
+|-----------|--------|
+| Name extraction | 20 pts |
+| Email extraction | 20 pts |
+| Phone extraction | 10 pts |
+| Section detection | 15 pts |
+| Education parsing | 10 pts |
+| Experience parsing | 15 pts |
+| Skills parsing | 10 pts |
+
+### Issue Severity Levels
+
+- **CRITICAL**: Name or email cannot be parsed (ATS will likely discard)
+- **HIGH**: Key sections missing, dates unparseable, phone not found
+- **MEDIUM**: Skills not extracted cleanly, formatting merge issues
+- **LOW**: Minor inconsistencies, optional fields missing