Digital Product Advisor Skill

An MVP Hermes Agent skill for consumer electronics product selection, starting with Bluetooth earbuds.

This repository is intentionally documentation-first. The core skill works through Markdown instructions and references; scripts are optional helpers for deterministic normalization, validation, and scoring.

MVP Scope

Supported in v0.1:

• Bluetooth earbuds / true wireless earbuds
• User-region and currency aware recommendations
• Brand-scoped comparisons such as "only Sony" or "compare Bose vs Sony"
• Budget-aware shortlists
• Product links / where-to-buy links in reports
• Scenario-based scoring and report generation
• Source-quality guidance for market research

Explicit non-goals in v0.1:

• Automatic checkout or purchasing
• Heavy marketplace scraping
• Hardcoded evergreen "best product" rankings
• Full support for GPUs, laptops, monitors, phones, or other product categories

Repo Layout

skills/digital-product-advisor/
  SKILL.md
  references/
    bluetooth-earbuds.md
    parameters.md
    scoring-framework.md
    source-quality.md
    export-policy.md
  templates/
    report-template.md
  scripts/
    normalize_request.py
    report_path.py
    score_candidates.py
    validate_candidates.py

docs/
  mvp-spec.md
  roadmap.md
  examples/
    earbuds-commuting-under-1000-rmb.md
    earbuds-brand-comparison-sony.md

tests/
  checklist.md
  fixtures/
    sample-candidates.json

Why Python scripts instead of TypeScript for MVP?

TypeScript is a good option later, especially for a standalone product-research toolkit. For this Hermes skill MVP, Python keeps setup friction lower because Hermes users are already running in a Python-centered agent environment. The scripts have no third-party dependencies and are optional.

The skill should still work even when scripts are not executed.

Installation

For local testing, copy the skill into your Hermes skills directory:

mkdir -p ~/.hermes/skills/product-research
cp -R skills/digital-product-advisor ~/.hermes/skills/product-research/

Then start Hermes with the skill:

hermes -s digital-product-advisor

One-shot test:

hermes -s digital-product-advisor chat -q "I want Bluetooth earbuds under 1000 RMB for commuting and calls. I use Android and prefer JD or Tmall. Include product links and save the report as Markdown."

After this repo is public, you may also install or inspect the skill from the raw SKILL.md URL if your Hermes version supports remote skill installation.

Quick Usage

Load the skill in Hermes, then ask something like:

I want Bluetooth earbuds under 1000 RMB for commuting and calls. I use Android and prefer JD or Tmall. Include product links.

Or:

Only compare Sony earbuds available in China around 1000-1800 RMB. I care about ANC and call quality.

To export a report, ask for Markdown output. The skill groups Bluetooth earbuds reports under reports/earbuds/ by default:

Generate the report and save it as Markdown.

Example output path:

reports/earbuds/2026-05-08-earbuds-china-under-1000-cny-commuting-calls.md

Optional Script Usage

Normalize a request:

python3 skills/digital-product-advisor/scripts/normalize_request.py   --query "Sony earbuds under 1500 RMB for commuting and calls in China"

Score candidate data:

python3 skills/digital-product-advisor/scripts/score_candidates.py   --input tests/fixtures/sample-candidates.json

Generate a grouped Markdown export path:

python3 skills/digital-product-advisor/scripts/report_path.py   --region China   --budget under-1000-cny   --use-case commuting-calls

Validate candidate data:

python3 skills/digital-product-advisor/scripts/validate_candidates.py   --input tests/fixtures/sample-candidates.json

Checks

Run the repository smoke checks:

python3 scripts/check.py

The check runner validates skill frontmatter, compiles helper scripts, validates fixture data, runs scoring, generates an export path, and tests request normalization.

Limitations

• The MVP focuses on Bluetooth earbuds only.
• Helper scripts do not fetch live prices or scrape marketplaces.
• Recommendations depend on the agent's current research tools and source quality.
• Prices, availability, and warranty terms must be verified before purchase.
• Fit and sound preferences are subjective.

See SECURITY.md for advice and data-handling disclaimers.

License

MIT