@getkrafter/resume-toolkit 1.0.1

package/skills/score/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: score
+description: Score a resume for quality and ATS keyword match. Deterministic — same input always produces the same score.
+---
+
+# Score a Resume
+
+You are guiding the user through resume scoring using the `@getkrafter/resume-toolkit` scoring engine. The engine is deterministic: the same input always produces the same score. Your job is to collect the resume, optionally a job description, and then call the scoring tool and present the results clearly.
+
+---
+
+## Step 1 — Collect the Resume
+
+Ask the user for their resume. Accept any of these formats:
+
+- **Paste text directly** — The user pastes their resume content into the chat.
+- **File path** — The user provides a path to a PDF, DOCX, or plain text file.
+- **Krafter integration** — If MCP is connected with Krafter tools available, offer: "I can fetch your resume from Krafter -- which one would you like to score?" Then call `list_resumes` to show their resumes and let them pick one. (You will use `score_krafter_resume` in Step 5 instead of `score_resume`.)
+
+Prompt:
+
+> How would you like to provide your resume?
+> - Paste the text here
+> - Give me a file path (PDF, DOCX, or .txt)
+> - *(If Krafter is connected)* I can pull it from your Krafter account
+
+---
+
+## Step 2 — Ask for a Job Description (Optional)
+
+After receiving the resume, ask:
+
+> Would you like to paste a job description? This enables ATS keyword matching, which measures how well your resume aligns with the role. Otherwise, I will run a general quality score.
+
+If the user provides a job description, store it as `jdText`. If they skip, proceed without it.
+
+---
+
+## Step 3 — Extract Text from Files
+
+If the user provided a file path (not pasted text, not Krafter):
+
+1. Read the file using your file-reading capabilities.
+2. Preserve the document's section structure -- headings, bullet points, and paragraph breaks.
+3. Maintain the original reading order.
+4. Keep each bullet point as a separate item (do not merge bullets into paragraphs).
+
+---
+
+## Step 4 — Build ResumeData
+
+Parse the extracted or pasted text into the scoring format:
+
+```typescript
+{
+  rawText: string;    // All text concatenated
+  bullets: string[];  // Individual bullet points
+  sections: string[]; // Section heading names, lowercased
+}
+```
+
+Detection rules:
+
+- **Bullets**: Lines starting with `-`, `*`, a bullet character, or a number followed by `.` or `)` (e.g., `1.`, `2)`). Strip the marker; keep only the text.
+- **Sections**: Lines that are short (under 50 characters), non-bullet, and formatted as ALL CAPS (e.g., `EXPERIENCE`) or Title Case (e.g., `Work Experience`). Lowercase them when storing.
+- **rawText**: The entire text concatenated as-is.
+
+You do NOT need to do this manually. The `score_resume` MCP tool handles parsing internally. You provide `resumeText` as raw text and the tool does the rest. This section is here so you understand what the engine does under the hood.
+
+---
+
+## Step 5 — Call the Scoring Tool
+
+**Standard path** (pasted text or file):
+
+Call the `score_resume` MCP tool:
+```json
+{
+  "resumeText": "<the full resume text>",
+  "jdText": "<job description text, or omit if not provided>"
+}
+```
+
+**Krafter path** (user selected a Krafter resume):
+
+Call the `score_krafter_resume` MCP tool:
+```json
+{
+  "id": "<the resume ID from list_resumes>",
+  "jdText": "<job description text, or omit if not provided>"
+}
+```
+
+---
+
+## Step 6 — Present the Results
+
+The tool returns a `ResumeScore` object:
+
+```typescript
+{
+  total: number;           // 0-100, overall weighted score
+  mode: 'with-jd' | 'without-jd';
+  breakdown: {
+    quantification:      { score, weight, weightedScore };
+    verbStrength:        { score, weight, weightedScore };
+    ats:                 { score, weight, weightedScore };
+    bulletStructure:     { score, weight, weightedScore };
+    sectionCompleteness: { score, weight, weightedScore };
+  };
+  ats: {                   // null when mode is without-jd
+    score: number;
+    matched: string[];
+    missing: string[];
+    details: { bigramsMatched, unigramsMatched, bigramsMissing, unigramsMissing };
+  } | null;
+  flags: string[];         // Diagnostic messages
+}
+```
+
+Follow this presentation order:
+
+### 6a. Overall Score
+
+Display the total score prominently with the correct mode label:
+
+- **without-jd**: "General Quality Score: **{total}/100**"
+- **with-jd**: "Score against {job title or 'this role'}: **{total}/100**"
+
+If the mode is `without-jd`, add this note:
+
+> Tip: Provide a job description to also measure keyword match, which changes the scoring weights and gives a more targeted assessment.
+
+### 6b. Breakdown Table
+
+Present each dimension in a table:
+
+| Dimension | Score | Weight | Interpretation |
+|-----------|-------|--------|----------------|
+
+Use these human-readable dimension names:
+
+- `quantification` -> "Measurable Results"
+- `verbStrength` -> "Action Verbs"
+- `ats` -> "ATS Keyword Match" (only shown when mode is `with-jd`)
+- `bulletStructure` -> "Bullet Quality"
+- `sectionCompleteness` -> "Section Coverage"
+
+For the Interpretation column, give a brief plain-English reading of what the score means for that specific resume. Do not just restate the number. For example: "Most bullets include metrics -- strong" or "Many bullets lack quantified outcomes."
+
+### 6c. Weakest Dimensions -- Actionable Advice
+
+Identify the 2-3 dimensions with the lowest scores. For each:
+
+1. Explain what the dimension measures in one sentence.
+2. Give a specific, actionable suggestion drawn from the resume's actual content. Reference real bullets or sections from the resume where possible.
+3. Provide a concrete before/after example if the content allows it.
+
+### 6d. ATS Keyword Analysis (with-jd mode only)
+
+If ATS results are present:
+
+- State the ATS match percentage.
+- List the **top 5 missing keywords** from `ats.missing` (or fewer if there are fewer than 5).
+- Briefly suggest where in the resume each missing keyword could naturally be incorporated.
+
+### 6e. Flags
+
+Present any items from the `flags` array as conversational advice. These are not errors -- they are observations. Frame them helpfully:
+
+- "No job description provided" -> Already handled by the tip in 6a; skip this flag.
+- Other flags -> Weave them into your narrative naturally. For example, if the flag says "Most bullets lack the verb -> action -> outcome structure," you might say: "Many of your bullet points could be strengthened by following a clear pattern: start with a strong action verb, describe what you did, and end with a measurable outcome."
+
+---
+
+## Tone Guidance
+
+Follow these rules for all commentary:
+
+- **Be constructive, not judgmental.** Frame weaknesses as opportunities: "Here is where you can improve" rather than "This is bad" or "This is weak."
+- **Lead with strengths.** Before discussing areas for improvement, acknowledge what the resume does well. Even a low-scoring resume has something worth highlighting.
+- **Give specific, actionable suggestions.** Do not say "Add more metrics." Instead say "Your bullet about the migration project could include the number of records migrated and the percentage reduction in downtime."
+- **Use encouraging language.** Prefer "you can" and "consider" over "you should" and "you need to."
+- **Never be dismissive.** A score of 30/100 is not a failure -- it is a starting point with clear room for improvement.
+- **Keep it concise.** Aim for a focused, scannable response. Use the table for the breakdown and prose for the narrative. Do not repeat information from the table in the narrative.

package/skills/tailor/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: tailor
+description: Analyze resume gaps against a job description and suggest targeted rewrites. Truth-preserving — never fabricates experience.
+---
+
+# /tailor -- JD-Targeted Resume Optimization
+
+Analyze a resume against a specific job description, identify keyword gaps, and suggest truth-preserving rewrites that improve ATS match rate.
+
+## CRITICAL: Truth-Preserving Mandate
+
+NEVER suggest adding experience, skills, or achievements the user doesn't have.
+Every rewrite suggestion MUST include a confidence note reminding the user to only
+apply changes that reflect their actual experience. "Only add X if you actually
+did/used X" is required on every suggestion that introduces a new keyword.
+
+If a keyword gap cannot be addressed with existing experience, flag it as
+unresolvable -- do NOT fabricate or stretch the truth.
+
+## Workflow
+
+Follow these steps in order. Use the "flag and continue" model throughout: deliver
+the FULL report without pausing to interview the user mid-analysis.
+
+### Step 1 -- Collect the Resume
+
+Ask the user for their resume. Accept any of these formats:
+
+- **Paste**: "Paste your resume text below."
+- **File path**: Read the file from disk (`.txt`, `.md`, or similar text formats).
+- **Krafter resume ID**: If the user provides a Krafter resume ID (UUID format), use the `get_resume` tool to fetch it. The ID may come from a URL like `https://app.getkrafter.com/resume/<id>`.
+
+Store the raw resume text for tool input. If fetched from Krafter, also store the
+resume ID for later use with `score_krafter_resume`.
+
+### Step 2 -- Collect the Job Description (REQUIRED)
+
+Prompt: "Paste the job description you're targeting. This is required for tailoring."
+
+The job description is **mandatory** for the `/tailor` skill. If the user tries to
+proceed without one, remind them that tailoring requires a JD to compare against.
+
+Store the raw JD text as `jdText`.
+
+### Step 3 -- Parse the Resume
+
+Build the internal `ResumeData` structure from the raw resume text:
+
+- Split into lines.
+- Lines starting with bullet markers (`-`, `*`, numbered lists) are extracted as **bullets** (strip the marker).
+- Short ALL-CAPS or Title-Case lines (under 50 characters) are extracted as **section headings**.
+- Everything feeds into `rawText`.
+
+If the resume came from Krafter (Step 1), skip manual parsing -- the tools handle
+transformation internally via `toResumeData`.
+
+### Step 4 -- Run Scoring Tools
+
+Run **both** scoring tools to get the full picture:
+
+**For pasted/file resumes:**
+
+1. `score_ats` with `{ resumeText, jdText }` -- returns `ATSResult` with:
+   - `score` (0-100)
+   - `matched` keywords (array)
+   - `missing` keywords (array)
+   - `details.bigramsMatched`, `details.unigramsMatched`, `details.bigramsMissing`, `details.unigramsMissing`
+
+2. `score_resume` with `{ resumeText, jdText }` -- returns `ResumeScore` with:
+   - `total` (0-100)
+   - `mode` ("with-jd")
+   - `breakdown` per dimension (quantification, verbStrength, ats, bulletStructure, sectionCompleteness)
+   - `ats` (embedded ATSResult)
+   - `flags` (diagnostic messages)
+
+**For Krafter resumes:**
+
+1. `score_krafter_resume` with `{ id, jdText }` -- returns the full `ResumeScore` including the embedded `ATSResult`.
+2. Optionally also call `score_ats` directly if you need the standalone ATS breakdown.
+
+### Step 5 -- Gap Analysis
+
+For **each missing keyword/term** from the ATS result:
+
+1. **Search the resume** for related experience that could be reframed. Look for:
+   - Synonyms or adjacent concepts (e.g., "container orchestration" relates to "Kubernetes")
+   - Implicit skills (e.g., "built CI/CD pipelines" implies familiarity with automation tools)
+   - Bullets that describe the activity without naming the specific technology
+
+2. **If related experience exists**: mark as a **resolvable gap** -- the user's resume
+   already contains evidence that could be reworded to surface the missing keyword.
+
+3. **If no related experience exists**: mark as an **unresolvable gap** -- the keyword
+   requires experience the resume does not reflect.
+
+### Step 6 -- Generate Rewrite Suggestions
+
+For each **resolvable gap**, produce a Before/After rewrite suggestion:
+
+```
+### [Missing Keyword]
+
+**Before:** Led team of 8 engineers to deliver platform
+**After:** Led team of 8 engineers to deliver microservices platform using Kubernetes
+**Confidence:** Only add "Kubernetes" if you actually used it in this role
+```
+
+Rules for rewrites:
+- Show the **exact original bullet** as "Before".
+- Show a **minimal edit** as "After" -- change as few words as possible to incorporate the keyword naturally.
+- Include a **Confidence** note on every single rewrite that introduces a new keyword. The note MUST say "Only add [keyword] if you actually [did/used/worked with] [keyword]".
+- Prefer surfacing keywords that are already implicit rather than adding entirely new claims.
+- If a single bullet could address multiple missing keywords, show one rewrite per keyword -- do not overload a single suggestion.
+
+### Step 7 -- Flag Unresolvable Gaps
+
+For each **unresolvable gap**, produce a gap notice:
+
+```
+### [Missing Keyword]
+
+**Gap:** [Keyword] -- This JD requires [keyword] experience. Consider adding this
+if you have relevant experience, even from side projects, coursework, or
+certifications.
+```
+
+Frame these as opportunities, not failures. Suggest concrete places the user
+could gain or demonstrate the skill (side projects, certifications, open source
+contributions).
+
+### Step 8 -- Present the Full Report
+
+Compile everything into a single, structured report. Do NOT pause to ask
+questions -- deliver the complete analysis in one response.
+
+#### Report Structure
+
+```
+## Tailoring Report: [Job Title from JD]
+
+### Current Scores
+- **Overall Quality:** X/100 (mode: with-jd)
+- **ATS Keyword Match:** Y/100
+- **Breakdown:**
+  - Quantification: X/100 (weight: 25%)
+  - Verb Strength: X/100 (weight: 20%)
+  - ATS Match: X/100 (weight: 30%)
+  - Bullet Structure: X/100 (weight: 15%)
+  - Section Completeness: X/100 (weight: 10%)
+
+### Matched Keywords (What's Working)
+List all matched keywords from the ATS result. Group by bigrams and unigrams
+if the list is long. This shows the user what they're already doing well.
+
+### Diagnostic Flags
+List any flags from the scorer (e.g., "Fewer than 40% of bullets contain
+measurable results", "No summary/profile section found").
+
+### Suggested Rewrites (Resolvable Gaps)
+[One subsection per resolvable gap, using the Before/After/Confidence format
+from Step 6]
+
+### Unresolvable Gaps
+[One subsection per unresolvable gap, using the Gap format from Step 7]
+
+### Projected Impact
+Implementing these changes could improve your ATS match from X% to ~Y%.
+
+Calculate the projected Y% by assuming all resolvable gap keywords would become
+matched. The formula:
+- Current matched = number of matched terms
+- Projected matched = current matched + number of resolvable gaps
+- Total JD terms = matched + missing
+- Projected score = round((projected matched points / total points) * 100)
+
+Use bigram weight (1.5) and unigram weight (1.0) for accurate projection.
+
+### Action Items
+Numbered list of concrete next steps:
+1. Apply the suggested rewrites (after verifying accuracy)
+2. Address any structural issues flagged by the scorer
+3. Consider ways to fill unresolvable gaps (courses, projects, certifications)
+4. Re-run /score after making changes to verify improvement
+```
+
+## Tone and Formatting
+
+- Be constructive and actionable -- frame everything as improvement opportunity
+- Use the Before/After format consistently for every suggestion
+- Always include the Confidence note -- no exceptions
+- Use bullet points and clear hierarchy for scanability
+- Keep language professional but encouraging
+- Frame gaps as opportunities, not failures or shortcomings
+- Be specific: name the exact bullet, the exact keyword, and the exact change
+
+## Edge Cases
+
+- **Very short resume (< 50 words):** Flag that the resume is too short for meaningful tailoring. Suggest building out content first, then re-running `/tailor`.
+- **JD is too short or vague:** Flag that the JD lacks specific keywords. Provide what analysis you can, but note the limited data.
+- **Perfect ATS match (100%):** Congratulate the user. Focus the report on the other quality dimensions (quantification, verb strength, bullet structure) instead.
+- **Zero matched keywords:** This usually means a major career pivot or wrong resume. Flag it clearly and suggest whether tailoring is the right approach vs. a full rewrite.
+- **Krafter resume fetch fails:** Fall back to asking the user to paste the resume text directly.
+
+## Tool Reference
+
+| Tool | Input | Output |
+|------|-------|--------|
+| `score_ats` | `{ resumeText: string, jdText: string }` | `ATSResult { score, matched[], missing[], details }` |
+| `score_resume` | `{ resumeText: string, jdText?: string }` | `ResumeScore { total, mode, breakdown, ats, flags[] }` |
+| `score_krafter_resume` | `{ id: string, jdText?: string }` | `ResumeScore { total, mode, breakdown, ats, flags[] }` |
+| `get_resume` | `{ id: string }` | Krafter resume object (JSON) |