# news-for-beginners
> A standalone Claude Code skill that collects recent articles from a user-specified site/feed and builds a **beginner-friendly news bundle** (`source.md` + `index.html` + `viewer.png`).
Version **1.3.0** · Runs standalone (no companion skill required).
## What does it do?
Within a site boundary, it gathers recent articles, synthesizes them so a beginner can follow the flow, and writes exactly three primary artifacts into a single output directory.
- `source.md` — collection ledger/source-of-truth (internal)
- `index.html` — standalone deployable news page (cool-blue news-summary design, includes topic filter)
- `viewer.png` — preview thumbnail
## Requirements (runtime)
- **python3** — most bundled scripts use only the standard library.
- **playwright + Chromium** — required only to render `viewer.png` (Gate 5). Install: `pip install playwright && playwright install chromium`. If absent, Gate 5 can fall back to another render path such as Chrome DevTools MCP (placeholders are forbidden, however).
- (Collection targets depend on feeds/sites) an environment with bash network access, or WebFetch/WebSearch.
## Installation
Place this directory (or the unzipped `.skill` bundle) under the Claude Code skills directory.
```bash
# Example: place it under the user skills directory
cp -R news-for-beginners ~/.claude/skills/
# Or unpack the .skill bundle
unzip news-for-beginners-v1.3.0.skill -d ~/.claude/skills/
```
Claude Code auto-scans the skill. Keep the directory name `news-for-beginners` so it matches the `name` in SKILL.md.
## Usage (triggers)
- "사이트 뉴스 초보자용으로 정리" (organize site news for beginners), "이 사이트 최근 소식 HTML로" (recent site news as HTML)
- "사이트 단위 뉴스 번들 만들어줘" (build a site-level news bundle)
- A site/domain/feed URL + "최근 소식"/"뉴스 분석" (recent news / news analysis) + "초보자용"/"HTML로" (for beginners / as HTML)
- Naver news: "네이버 뉴스 만들어줘" (build Naver news) → collected at once by the bundled `collect_naver.py`
## Layout
```
news-for-beginners/
├─ SKILL.md # Skill body (gates/rules/validation)
├─ README.md # This file (distribution)
├─ CHANGELOG.md # Version history
├─ references/
│ ├─ deployment-packaging.md # Standalone packaging rules
│ ├─ template-guide.md # index.html placeholder contract (v1.3)
│ ├─ site-collection-recipes.md # Per-site collection recipes (Naver, etc.)
│ └─ self-improvement.md # Quality criteria + self-improvement triggers
├─ scripts/
│ ├─ discover_site_sources.py # Generic feed/sitemap collection
│ ├─ collect_naver.py # Naver-specific collection (section page SSR)
│ ├─ validate_bundle.py # Bundle validation (Gate 6)
│ └─ render_viewer.py # viewer.png render (Playwright, Gate 5)
└─ templates/
├─ index.html # Active template (cool-blue news-summary v1.3)
├─ index.legacy-warm.html # Previous warm design (reference)
├─ manifest.json # Execution metadata template
└─ source.md # Ledger/source-of-truth template
```
## How it works (gates)
```
plan-contract → discover-site-sources → collect-evidence → normalize-ledger
→ write-source-md → build-html → render-viewer-image → validate-bundle
```
A dynamic workflow that, after each gate, decides whether to continue, retry, narrow scope, or abort. Validation (`validate_bundle.py`) checks: the three primary artifacts exist, `<!doctype html>` is present, forbidden process terms (e.g. `/Users/`) are absent, external links exist, local images are valid, and the PNG is valid.
## License
`license: internal` (declared in SKILL.md). Fill the empty license slot before redistributing.
## See also
- Changelog: `CHANGELOG.md`
- Template placeholders / image and topic rules: `references/template-guide.md`
- Per-site collection: `references/site-collection-recipes.md`