Add brave-answer skill: synthesized cited answers via Brave Answers API

[hui-zheng]

Summary

Adds brave-answer, wrapping the Brave Answers API for one-shot synthesized answers with numbered citations. Companion to brave-search.

Closes #30

Files

• brave-answer/SKILL.md — frontmatter, setup, usage, common mistakes
• brave-answer/answer.js — streaming SSE client, citation parser, numbered references output
• brave-answer/package.json — "type": "module", no runtime dependencies
• README.md — skill row, requirements line, Claude Code symlink lines (user + project)

API specifics

• POST https://api.search.brave.com/res/v1/chat/completions
• Auth via x-subscription-token header
• Always streams (citations require stream: true per docs)
• Parses <citation>{json}</citation> → [N] markers + a --- Sources --- block
• Strips <enum_item> and <usage> tags silently

Flags

• --research — multi-search deep mode (slow, can take minutes)
• --country <code> / --language <code> — locale (defaults: US / en, matching brave-search convention)
• --raw — debug; prints raw API content with tags

Conscious deviations from brave-search

A couple of intentional small departures, flagged so they don't read as oversights:

• Frontmatter description is longer than brave-search's one-liner — leans into trigger keywords ("what is X", "summarize Y", current-events Q&A) so the skill router picks it over brave-search when the user wants a synthesized answer. Happy to tighten if you'd prefer a shorter description.
• SKILL.md has a Common Mistakes section that brave-search doesn't — covers the BRAVE_ANSWER_API_KEY-vs-BRAVE_API_KEY trap and --research runtime gotcha, both of which agents tripped on during testing.

Code style, arg parsing, error handling, install ritual, country defaults, env-var pattern, README integration all mirror brave-search.

Sample output

WebGPU is a modern, low-level web API that enables high-performance graphics
rendering and general-purpose GPU computing in browsers...[1][3][7]

--- Sources ---
[1] https://gpuweb.github.io/gpuweb/explainer/
    WebGPU is a proposed Web API to enable webpages to use the system's GPU...
[3] https://multilogin.com/glosssary/webgpu-browser/
    WebGPU is a modern graphics API designed to provide high-performance...
[7] https://threejsroadmap.com/blog/webgl-vs-webgpu-explained
    WebGPU is a next-generation graphics API designed from the ground up...

Test plan

• Smoke-tested with real API key against several questions (locale, --raw, missing-arg-value error path)
• Reviewer pass: SSE chunk-boundary parsing safe (content fully accumulated before regex), ESM module type explicit, country/language defaults consistent between code and docs

🤖 Generated with Claude Code

[hui-zheng]

Out of draft. Changes since the initial draft (force-pushed as a single squashed commit):

• Setup wording corrected — verified against Brave's pricing page. The plan is "Answers" with $5/mo free credits, not a literally-named "Free Answers subscription". SKILL.md and the subscribe step updated.
• --country / --language defaults now match the docs — answer.js was sending null (API default) while the docs claimed US / en. Now defaults to US/en and always passes them, matching brave-search convention. Country uppercased like search.js.
• package.json "author" field added for parity with brave-search.
• Common Mistakes section + verbose frontmatter description kept — flagged as conscious deviations in the PR description above. Happy to tighten either if you'd prefer one-liner consistency with the rest of the skills.

Live smoke test ran clean against the real Answers endpoint.

[hui-zheng]

Caught a real bug while smoke-testing --research end-to-end after the cleanup pass. Force-pushed an amended commit:

• enable_citations: true + enable_research: true is rejected by the API (HTTP 422: "Research mode doesn't support 'enable_citations' option"). answer.js was always sending both. Now omits enable_citations when --research is set.
• Research mode emits a different output shape: synthesized answer wrapped as <answer>{"answer": "..."}</answer> JSON, no per-claim <citation> tags, plus <queries> / <analyzing> / <thinking> / <progress> / <blindspots> planning metadata. Renamed parseCitations() → parseAnswer() and taught it both shapes; metadata tags stripped in either mode.
• SKILL.md --research description updated to flag (1) cost — a single research call ran ~$0.60 in smoke testing, well past the $5/mo free credits on a few uses, and (2) no citations in research mode.

Tested both modes against the live API:

• Standard: "what is the latest Node.js LTS" → answer + 4 numbered citations
• Research: same Bun question as the issue Proposal: add brave-answer skill (Brave Answers API for sourced Q&A) #30 baseline → ~67s, clean prose, no metadata leak

Force-push is one squashed commit on top of upstream/main.