agentleFS
littlebearappslittlebearapps/pitchdocs/.claude/skills/feature-benefits/SKILL.md

feature-benefits

Skill8 starsChanged 8 months agoMITView on GitHub

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?".

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 4 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read the primary manifest to understand the ecosystem:

    line 15
  2. Distinctive:

    Every feature must have a file path or function as evidence

    line 44
  3. Distinctive:

    No speculative features — if you can't point to code, it's not a feature

    line 45
  4. Very specific:

    Use 4 interactive questions to surface authentic use cases, then enrich with code evidence.

    line 71
  5. Distinctive:

    Use at least 3 different categories across your features table:

    line 105

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

FileEcosystemKey Fields
package.jsonNode.js / JavaScript / TypeScriptdependencies, scripts, bin, exports, type
pyproject.tomlPython[project.dependencies], [project.scripts], [tool.*]
Cargo.tomlRust[dependencies], [features], [[bin]]
go.modGorequire, module path
.claude-plugin/plugin.jsonClaude Code Pluginskills, 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:

  1. Apply the signal gate: Standard (workflow benefits) by default; Elevated (experiential) only with mobile/async/remote/voice signals in code
  2. Generate 3–7 draft benefits, tag claim strength: Strong (code directly enables), Medium (reasonable inference), Weak (discard)
  3. 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

TierCountCriteriaREADME Placement
Hero1–3Primary differentiators — why someone chooses THIS over alternativesOne-liner, Why section, first in features
Core4–8Expected by the target audience — missing these would be a deal-breakerFeatures table, quick start examples
Supporting9+Nice-to-have — adds polish but isn't the reason someone adoptsMentioned 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:

CategoryPatternExample 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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.