news-for-beginners

name	news-for-beginners
description	A standalone skill that collects recent articles from a user-specified site/feed and builds a beginner-friendly news bundle. It gathers recent articles within a site boundary, synthesizes them so a beginner can follow the flow, and writes exactly three primary artifacts — source.md, index.html, viewer.png — into one output directory. Site-bound collection, a dynamic workflow, and validation are built in, so it runs standalone with no companion skill. Trigger on Korean phrases like '사이트 뉴스 초보자용으로 정리', '이 사이트 최근 소식 HTML로', 'site-news', '사이트 단위 뉴스 번들 만들어줘', a site/domain/feed URL + '최근 소식'/'뉴스 분석' + '초보자용'/'HTML로', 'source.md, index.html, viewer png 만들어줘', or '배포용 standalone 뉴스 리포트' / '뉴스 HTML 뷰어 + 썸네일'. Do NOT use for plain Markdown summaries, single-article translation, cross-site aggregation, or when the real goal is Obsidian / knowledge-comic / Telegram / NotebookLM delivery.
license	MIT
metadata	{"version":"1.3.1","author":"Hermes Agent (ported to Claude Code)","related_skills":["html-for-beginners","report-for-beginners"]}

News for Beginners — Standalone Site News Workflow

LANGUAGE NOTE: These instructions are written in English for token efficiency. The generated news bundle follows the source site's language (Korean by default for Korean sites). English here is only for efficiency; reader-facing output stays in the source language.

This is a single, deployable standalone skill. It consolidates the operational rules that were scattered across Hermes's tech-ai-news-dynamic-workflow and the dynamic-workflow / validation notes. Deploying just this one skill runs the full chain: site selection → news collection → evidence MD → HTML → viewer image.

Porting notes: ported from a Hermes .skill export into Claude Code. The directory structure (SKILL.md + references/ + scripts/ + templates/) is unchanged. The frontmatter's metadata.hermes.* was flattened, and Hermes-only browser/screenshot tools were replaced with a Playwright script (scripts/render_viewer.py). Operational rules (gates / validation / citation) are preserved verbatim.

When to Use

Use when the user asks for any of these:

• "사이트 뉴스 초보자용으로 정리", "이 사이트 최근 소식 HTML로", "site-news 번들" (organize this site's news for beginners / this site's recent news as HTML)
• a site/domain/feed URL turned into a beginner-readable news bundle (not a plain summary)
• the explicit three-artifact deliverable: source.md + index.html + viewer.png
• a deployment-ready standalone news reader page with external citations only

Do not use for: single-article translation, generic cross-site news aggregation, Markdown-only notes, or when the real goal is Obsidian / knowledge comic / Telegram / NotebookLM delivery.

Required primary outputs

Every successful run must produce exactly these three primary deliverables under one output directory:

<output_dir>/
  source.md      # evidence/rationale MD: source ledger + synthesis notes
  index.html     # standalone deployable reader-facing HTML
  viewer.png     # browser-rendered review/share image of index.html

Optional support files may exist but do not replace the three primary outputs:

<output_dir>/assets/article-images/*
<output_dir>/manifest.json
<output_dir>/qa.json

Explicit non-goals

Do not do these unless the user separately asks:

• Do not write to Obsidian.
• Do not generate or embed knowledge comics (지식만화).
• Do not update Manual Onboarding hub/list pages.
• Do not deploy to a live site or Cloudflare Pages.
• Do not send Telegram/iMessage/social delivery.
• Do not use NotebookLM as the required generation path.

Input contract

The user may provide:

• site: homepage, section URL, or domain, e.g. https://www.theverge.com/ai-artificial-intelligence
• optional feed_url: explicit RSS/Atom feed
• optional topic_filter: e.g. AI, startup, finance, policy, 전체 (all)
• optional source_window: default last 24–72h; widen only inside the same site boundary unless approved
• optional output_dir: default artifacts/site-news/<YYYYMMDD>-<site-slug>/

If no site is provided, default to TechCrunch AI:

https://techcrunch.com/category/artificial-intelligence/
https://techcrunch.com/category/artificial-intelligence/feed/

Claude Code tool mapping

This skill is tool-agnostic, but in Claude Code use these mappings:

Skill step	Claude Code tool
Current KST date for manifest/output dir	Bash: TZ=Asia/Seoul date +%Y-%m-%d (and +%Y%m%d for the slug)
Site source discovery (feeds/sitemaps)	Bash: python3 scripts/discover_site_sources.py "<site>" --json
Domain-restricted article search	WebSearch with site:<domain> queries
Fetching article body / feed XML	WebFetch on the article/feed URL
Browser rendering / dynamic pages	Chrome DevTools MCP browser tools (or the gstack skill) when feeds/search are not enough
Render viewer.png (Gate 5)	Bash: python3 scripts/render_viewer.py <output_dir>
Validate bundle (Gate 6)	Bash: python3 scripts/validate_bundle.py <output_dir> --json

Run the bundled scripts from this skill's directory (resolve scripts/ under wherever the skill is installed), e.g. python3 scripts/validate_bundle.py <output_dir> --json.

Dynamic workflow gates

Run this as a dynamic owner-plan workflow. After every gate, decide whether to continue, retry with another adapter inside the same boundary, reduce scope, ask to broaden the boundary, or stop with evidence.

plan-contract
  → discover-site-sources
  → collect-evidence
  → normalize-ledger
  → write-source-md
  → build-html
  → render-viewer-image
  → validate-bundle

Gate 0 — Mission contract

Create manifest.json (use templates/manifest.json) or equivalent working notes before writing public copy:

{
  "workflow": "news-for-beginners",
  "date": "YYYY-MM-DD",
  "site": {
    "name": "Site display name",
    "url": "https://example.com",
    "feed_url": null,
    "allowed_domains": ["example.com"],
    "collection_adapter": "feed|sitemap|domain-search|browser"
  },
  "topic_filter": "AI|tech|전체|user-specified",
  "output_dir": "artifacts/site-news/YYYYMMDD-site-slug",
  "source_window": "last 24-72h unless user specifies otherwise",
  "target_reader": "beginner/operator",
  "primary_outputs": ["source.md", "index.html", "viewer.png"],
  "excluded_outputs": ["obsidian", "knowledge-comic", "manual-site-deploy", "telegram", "notebooklm"]
}

Defaults:

• Date: current KST date via TZ=Asia/Seoul date +%Y-%m-%d (Bash).
• Site boundary: same hostname plus explicitly allowed domains/subdomains only.
• Source count: 6–12 strong current items; fewer is acceptable for thin sites.
• Language: follows the source site (Korean by default) unless the user requests otherwise.
• Visual style: calm beginner-friendly, date-aware, clear cards/boxes, not newsroom hype.

Gate 1 — Discover and collect site sources

Use scripts/discover_site_sources.py when helpful (python3 scripts/discover_site_sources.py "<site>" --json), or do the same logic with WebSearch/WebFetch.

Feed-less / externally un-indexed sites (e.g. Naver News): if the generic script returns 0 items, first consult the per-site recipes in references/site-collection-recipes.md. Naver News can be collected in one shot with the dedicated collector:

python3 scripts/collect_naver.py --with-meta --limit 12   # specific sections only: --sections 101 105

When you find a working path for a new site, add that recipe to site-collection-recipes.md (self-improvement trigger #1).

Discovery order:

1. Explicit feed URL from the user.
2. Homepage/section <link rel="alternate" type="application/rss+xml|application/atom+xml">.
3. Common feed candidates: /feed/, /rss/, /atom.xml, /feed.xml, /category/artificial-intelligence/feed/, /tag/ai/feed/.
4. Sitemap candidates: /sitemap.xml, /sitemap_index.xml, /news-sitemap.xml.
5. Domain-restricted web search, e.g. WebSearch query site:example.com AI OR artificial intelligence.
6. Browser inspection (Chrome DevTools MCP / gstack) only when feeds/sitemaps/search do not expose enough article URLs.

For every candidate collect:

• title
• URL
• publisher/domain
• publication date or observed date
• discovery path: feed / sitemap / domain-search / browser
• factual summary
• supported claims
• caveat / uncertainty
• og:image or article hero image URL when available

Reject candidates that:

• are outside the allowed site boundary;
• cannot be retrieved;
• are duplicates/canonical duplicates;
• are too old for the source window, unless widening is part of the plan;
• do not support a concrete claim;
• are index/tag/search pages rather than articles.

If the site is thin, do not pad with other publishers. Widen the date window inside the same site, produce a smaller honest bundle, or ask permission to broaden.

Non-negotiable source and citation rules

• Never cite a local file as a public source.
• Public citations must be external article/source URLs.
• Local files may be inputs, caches, manifests, or working evidence only.
• Public HTML must not expose local paths, HEAD/status checks, build notes, handoff notes, or process labels.
• Claims in the explainer must trace to at least one collected external source.
• Separate confirmed facts from interpretation.
• Do not overclaim beyond the source text.

Forbidden public-copy/process terms include:

source_bound
provisional
do_not_publish
HEAD 요청            (HEAD request)
검증 대기            (pending validation)
로컬 파일            (local file)
Evidence window
QA/HANDOFF
/Users/

Gate 2 — Normalize source ledger

Group articles by story role, not collection order. Choose 3–5 groups. Suggested group labels (use the output language — Korean labels for Korean sites):

• Model & product changes (모델·제품 변화)
• Platform & distribution channels (플랫폼·배포 채널)
• Infrastructure & cost (인프라·비용)
• Policy, regulation & safety (정책·규제·안전)
• Capital, M&A & strategic assets (자본·M&A·전략 자산)
• Organization, jobs & operational risk (조직·일자리·운영 리스크)
• Research, benchmarks & open source (연구·벤치마크·오픈소스)
• User & market reaction (사용자·시장 반응)

For each group define:

• shared signal
• why a beginner should care
• sources supporting it
• uncertainty or caveat

Gate 3 — Write source.md

Use templates/source.md. source.md is an internal evidence artifact, not the public article. It must contain:

1. run metadata: date, site, topic filter, source window, output dir
2. source ledger table with external URLs
3. rejected/excluded items and reasons
4. grouped signal map
5. synthesis notes for HTML
6. image ledger, if images were collected
7. QA notes

Gate 4 — Build index.html

You must copy templates/index.html (news-summary, cool-blue v1.3 design), fill its placeholders, and save the result as <output_dir>/index.html. The template's CSS and filter <script> are fixed — do not touch them; fill only the {{...}} slots. For the placeholder list, repeating-block HTML patterns, and image/topic rules, follow references/template-guide.md. (The previous design is preserved in templates/index.legacy-warm.html.)

Template structure (regions to fill):

1. topline — site name (H1), date, one-line intro (LEDE). "Read the date first" is the core of this design.
2. news-nav — section shortcut anchors + article count (FILTER_STATUS).
3. content-grid — feature story + subtle-band (today's overall summary TODAY_SUMMARY/TODAY_DETAIL + condensed signal map = the filter buttons).
4. Related news groups — same-issue bundles (with a group strip if images exist).
5. Article cards — all collected articles (thumbnail if an image exists, otherwise text-only).

There is no hero/topic toolbar. Filtering is handled only by the signal buttons (data-filter) in the subtle-band, wired to the same topic words on the cards/group-cards via data-topic.

Standalone rules (invariant):

• Starts with <!doctype html>, ends with </html>.
• Inline CSS (included in the template), no build step.
• No local absolute paths or banned process terms.
• Link only to external sources.
• Images always live under assets/article-images/ as local relative paths.

Image/card layout rule (template-guide summary)

• When using a source image, always download it locally into assets/article-images/ and reference it by relative path. No hotlinking (the prototype's demo AP images are illustrative only).
• If an image is missing or the download fails → make that card/feature/group-strip text-only (card text-only / feature-card text-only + remove the media block). No empty <img> or broken src.
• Every <img> needs a meaningful alt.
• Use topic words consistently between the signal buttons' data-filter and the cards/group-cards' data-topic, or the filter will not work.
• Keep the template's 3-column grid (repeat(3, minmax(0,1fr))) so a 2-item group does not stretch to 50%; only mobile collapses to 1 column.

Gate 5 — Render viewer.png

viewer.png must be a browser-rendered image of index.html, not a hand-written placeholder.

Preferred methods (in order):

1. python3 scripts/render_viewer.py <output_dir> — bundled Playwright renderer, full-page by default. For very tall pages add --hero-only to capture the top/hero region (~1440×1600).
2. Chrome DevTools MCP browser tools (navigate to the file:// URL of index.html, screenshot the page) when Playwright is unavailable.
3. Capture either a full-page PNG or a top/hero viewer PNG around 1440×1600 if the page is too tall.

Record the render mode in qa.json or final notes.

Gate 6 — Validate bundle

Run python3 scripts/validate_bundle.py <output_dir> --json or equivalent checks.

Minimum checks:

• source.md, index.html, and viewer.png exist and are non-empty.
• index.html starts with <!doctype html> and contains closing </html>.
• public HTML contains no /Users/ or banned process terms.
• public HTML contains at least one external source link.
• local image references resolve.
• source.md contains external URLs.
• browser check shows no broken images, no horizontal overflow, and no console errors when browser tools are available.
• viewer.png is a valid PNG with plausible dimensions.

The final response must list the three primary output paths and the real validation evidence. Do not claim live deployment unless the user separately requested deployment and it was actually performed.

Failure handling

• Thin source set: state the limitation in source.md, not as public-process noise in the HTML.
• Image failures: continue with text-only cards and record failures in source.md/qa.json.
• Viewer rendering failure: fix the renderer path first; do not substitute a placeholder.
• Validation failure: repair and rerun validation before finalizing.

Self-improvement

This skill is designed to fix itself at runtime. When one of the triggers below fires during a run, follow the cycle in references/self-improvement.md (record → diagnose/suggest fix → apply boundary → verify → prevent regression).

Improvement triggers: (1) doc/run mismatch — a command/path/dependency differs from reality; (2) fold a user correction into the quality bar — "that shouldn't happen" becomes a SKILL.md rule/pitfall, not just chat; (3) a recurring pitfall — confusing "summary-only standalone" with "executable full bundle"; since viewer.png is primary, the render script/run path is mandatory; (4) insufficient validation — only a syntax check with no sample run; (5) security/portability — raw secrets, residual Claude/Hermes-only API names, local absolute paths (/Users/) leaking into public output, unauthorized side effects (rm -rf/deploy/DB); (6) ambiguous scope — unclear trigger / site-vs-topic / optional-vs-required.

The 8 quality bars (trigger · non-goal · step · file · pitfall · validation · dependency · side-effect boundary) and the detailed cycle are in references/self-improvement.md. Trigger #1 found in the Naver run (generic discoverer returns 0) was patched with site-collection-recipes.md + collect_naver.py.

Common pitfalls

1. Citing a local path publicly.
2. Padding a thin site with unrelated publishers without approval.
3. Listing articles one-by-one without explaining the flow.
4. Publishing internal process labels.
5. Letting 2-card image/text groups stretch to 50% width.
6. Treating viewer.png as optional; it is a primary output.
7. On sites where the generic discoverer returns 0 (e.g. Naver), do not keep retrying feeds only — consult references/site-collection-recipes.md or a dedicated collector (collect_<site>.py) first.
8. Do not confuse "summary-only standalone" with "executable full bundle" — all three primary outputs (source.md / index.html / viewer.png) must actually be produced and validated for it to be standalone.
9. On sites whose article URLs are not indexed by external search (WebSearch), do not get stuck on site: queries — switch to a path that fetches the site's own SSR section pages directly.