| name | feature-benefits |
| description | Systematic codebase scanning for features and evidence-based feature-to-benefit translation. Extracts what a project does from its code and translates it into what users gain — generates features and benefits sections, "Why [Project]?" content, and feature audit reports. Use when writing a features table for a README, extracting features from code, auditing feature coverage, or answering "why should someone use this project?". |
| version | 1.0.0 |
Feature-Benefits Extraction
Scan a codebase systematically, extract concrete features with evidence, classify by impact, and translate into benefit-driven language for documentation.
7-Step Feature Extraction Workflow
Step 1: Detect Project Type
Read the primary manifest to understand the ecosystem:
| File | Ecosystem | Key Fields |
|---|
package.json | Node.js / JavaScript / TypeScript | dependencies, scripts, bin, exports, type |
pyproject.toml | Python | [project.dependencies], [project.scripts], [tool.*] |
Cargo.toml | Rust | [dependencies], [features], [[bin]] |
go.mod | Go | require, module path |
.claude-plugin/plugin.json | Claude Code Plugin | skills, commands, agents, hooks |
Also check: Makefile, Dockerfile, docker-compose.yml, .github/workflows/, wrangler.toml for deployment signals.
Step 2: Scan Signal Categories
Scan the 10 signal categories: CLI Commands, Public API, Configuration, Integrations, Performance, Security, TypeScript/DX, Testing, Middleware/Plugins, Documentation.
For each category, check file patterns, read matching files, and record what you find. For detailed file patterns and scan lists per category, load SKILL-signals.md from this skill directory.
Step 3: Extract Concrete Features with Evidence
For each signal found, create a feature entry:
Feature: [What it does — concrete, specific]
Evidence: [File path, function name, or config that proves it]
Category: [Signal category from Step 2]
Rules:
- Every feature must have a file path or function as evidence
- No speculative features — if you can't point to code, it's not a feature
- Be specific: "Zero-config TypeScript support" not "Good developer experience"
Step 3.5: Map to Jobs-to-be-Done (Hero features only)
For Hero features, frame the job: When I am [situation], I want [capability], so I can [outcome]. Classify as Functional, Emotional, or Social. Skip JTBD for Core/Supporting tiers and projects with fewer than 5 features. For full JTBD guidance, load SKILL-signals.md.
Step 3.6: Persona Inference
Infer 1–2 target personas from code signals (integration surface, execution model, entry points, deploy artifacts). Map to archetypes: Solo builder, Team lead, Platform/ops engineer, Power user/automator, Compliance-aware org. Default to "Solo builder" if ambiguous. For the full persona inference table, load SKILL-signals.md.
Step 4: User Benefits (the "Why?" Layer)
User benefits answer "Why should I care?" — the real-world reasons someone would choose this project.
Two paths available — both produce the same output format:
Path A: Auto-Scan (default)
Synthesise outcome-first benefits from Hero features + JTBD + persona:
- Apply the signal gate: Standard (workflow benefits) by default; Elevated (experiential) only with mobile/async/remote/voice signals in code
- Generate 3–7 draft benefits, tag claim strength: Strong (code directly enables), Medium (reasonable inference), Weak (discard)
- Ship only Strong + Medium benefits
Path B: Conversational ("Talk it out")
Use 4 interactive questions to surface authentic use cases, then enrich with code evidence. For the full prompt sequence, load SKILL-signals.md.
Output Format
**[Bold user outcome]** — [mechanism/how it works]. [Constraint if needed].
Each benefit requires: a specific context, an enabling mechanism, and an evidence pointer.
Step 5: Classify by Impact Tier
| Tier | Count | Criteria | README Placement |
|---|
| Hero | 1–3 | Primary differentiators — why someone chooses THIS over alternatives | One-liner, Why section, first in features |
| Core | 4–8 | Expected by the target audience — missing these would be a deal-breaker | Features table, quick start examples |
| Supporting | 9+ | Nice-to-have — adds polish but isn't the reason someone adopts | Mentioned briefly or linked to docs |
Step 6: Output Structured Feature Inventory
Output as a Markdown table with Feature, Evidence, Benefit Category, and optional JTBD columns, grouped by tier (Hero, Core, Supporting). Or use emoji+bold+em-dash bullets for direct README use.
Feature-to-Benefit Translation Framework
The Translation Pattern
[Technical feature] so you can [user outcome] — [evidence]
5 Benefit Categories
Use at least 3 different categories across your features table:
| Category | Pattern | Example Benefit |
|---|
| Time saved | "Do X in Y instead of Z" | "Generate a full README in under a minute — not an afternoon" |
| Confidence gained | "Know that X because Y" | "Every benefit traces to actual code — no marketing fluff" |
| Pain avoided | "Never worry about X" | "Never ship a repo with missing docs again" |
| Capability unlocked | "Now you can X" | "Scan any codebase and extract its selling points automatically" |
| Cost reduced | "Save X by Y" | "One plugin replaces five separate documentation tools" |
Anti-Patterns
- No "simple" or "easy" — show simplicity through a short code example
- No "powerful" without evidence — what specifically makes it powerful?
- No speculative benefits — "could save you hours" requires evidence
- No feature-as-benefit — "Has caching" is a feature; "Responses in <50ms after first request" is the benefit
- No benefit without context — every user benefit needs a specific situation
- No benefit without mechanism — every user benefit needs an enabling mechanism
- No ungrounded lifestyle claims — elevated signal gate only when code proves the mechanism
For the full translation table by signal category, badge mapping, and common patterns library, load SKILL-signals.md.
