CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Purpose

This repository provides AI skills for producing dated, source-backed equity research analysis for Korean (KRX) and U.S. markets. Skills work with both Codex ($CODEX_HOME/skills/, default ~/.codex/skills/) and Claude Code ($CLAUDE_HOME/skills/, default ~/.claude/skills/).

Commands

Validate skills (checks SKILL.md format, JS syntax, chart generation; warns if openai.yaml missing):

bash ./scripts/validate-skills.sh        # Linux/macOS
.\scripts\validate-skills.ps1            # Windows PowerShell

Install a single skill (Codex):

bash ./scripts/install-skill.sh kr-stock-analysis
bash ./scripts/install-skill.sh kr-order-backlog-analysis
bash ./scripts/install-skill.sh kr-stock-update
bash ./scripts/install-skill.sh kr-portfolio-monitor
bash ./scripts/install-skill.sh kr-portfolio-guard
bash ./scripts/install-skill.sh us-stock-analysis
bash ./scripts/install-skill.sh kr-naver-browse
bash ./scripts/install-skill.sh kr-naver-blogger
bash ./scripts/install-skill.sh kr-naver-insight
bash ./scripts/install-skill.sh kr-web-browse
bash ./scripts/install-skill.sh kr-analyst-report-discover
bash ./scripts/install-skill.sh kr-analyst-report-fetch
bash ./scripts/install-skill.sh kr-analyst-report-insight
bash ./scripts/install-skill.sh kr-foreign-analyst
bash ./scripts/install-skill.sh kr-market-sentiment
bash ./scripts/install-skill.sh kr-chatgpt-review
bash ./scripts/install-skill.sh kr-research-site
bash ./scripts/install-skill.sh us-earnings-review

Install all skills (Codex):

bash ./scripts/install-all-skills.sh

Install a single skill (Claude Code):

bash ./scripts/install-claude-skill.sh kr-stock-analysis
bash ./scripts/install-claude-skill.sh kr-order-backlog-analysis
bash ./scripts/install-claude-skill.sh kr-stock-update
bash ./scripts/install-claude-skill.sh kr-portfolio-monitor
bash ./scripts/install-claude-skill.sh kr-portfolio-guard
bash ./scripts/install-claude-skill.sh us-stock-analysis
bash ./scripts/install-claude-skill.sh kr-naver-browse
bash ./scripts/install-claude-skill.sh kr-naver-blogger
bash ./scripts/install-claude-skill.sh kr-naver-insight
bash ./scripts/install-claude-skill.sh kr-web-browse
bash ./scripts/install-claude-skill.sh kr-analyst-report-discover
bash ./scripts/install-claude-skill.sh kr-analyst-report-fetch
bash ./scripts/install-claude-skill.sh kr-analyst-report-insight
bash ./scripts/install-claude-skill.sh kr-foreign-analyst
bash ./scripts/install-claude-skill.sh kr-market-sentiment
bash ./scripts/install-claude-skill.sh kr-chatgpt-review
bash ./scripts/install-claude-skill.sh kr-research-site
bash ./scripts/install-claude-skill.sh us-earnings-review

Install all skills (Claude Code):

bash ./scripts/install-all-claude-skills.sh

Regenerate the analysis artifact index (git add the new example first — the index covers only git-tracked files so its links never 404 on a fresh clone):

node scripts/build-artifact-index.js            # writes docs/ARTIFACTS.md
node scripts/build-artifact-index.js --check    # fails if the committed index is stale

Run a bundled script directly (Node.js, no npm install needed):

node skills/kr-stock-analysis/scripts/chart-basics.js --input examples/kr/chart-sample.json --png-out chart.png
node skills/kr-stock-analysis/scripts/peer-valuation.js --input examples/kr/peer-sample.json
node skills/kr-stock-analysis/scripts/fetch-kr-chart.js --ticker 066970 --range 3mo
node skills/kr-stock-analysis/scripts/portfolio-snapshot.js --input examples/kr/portfolio-sample.json
node skills/kr-stock-dart-analysis/scripts/normalize-browser-dart-export.js --input examples/kr-stock-dart-analysis/dart-browser-export-sample.json --output dart-text.txt
OPENDART_API_KEY=<key> node skills/kr-stock-dart-analysis/scripts/fetch-opendart.js --ticker 010950 --year 2025 --report-code 11011 --output analysis-example/kr/S-Oil/
node skills/kr-stock-dart-analysis/scripts/fetch-nps-holdings.js --lookback-days 90 --output /tmp/nps-holdings/   # reads OPENDART_API_KEY from .env or env
node skills/kr-order-backlog-analysis/scripts/render-order-backlog.js --input examples/kr-order-backlog-analysis/backlog-sample.json --png-out /tmp/order-backlog.png --summary-out /tmp/order-backlog-summary.json
node skills/kr-stock-analysis/scripts/valuation-chart.js --input examples/kr-stock-analysis/valuation-band-sample.json --png-out valuation.png
node skills/kr-naver-browse/scripts/browse-naver.js --test
node skills/kr-naver-blogger/scripts/build-query-set.js --company "엘앤에프" --ticker 066970 --output /tmp/queries.json
node skills/kr-naver-blogger/scripts/discover-bloggers.js --company "엘앤에프" --ticker 066970 --output /tmp/bloggers.json
node skills/kr-naver-insight/scripts/fetch-blog-posts.js --input /tmp/bloggers.json --company "엘앤에프" --output /tmp/posts.json
node skills/kr-naver-insight/scripts/summarize-insights.js --input /tmp/posts.json --output /tmp/insights.md
node skills/kr-analyst-report-discover/scripts/discover-reports.js --company "엘앤에프" --ticker 066970 --output /tmp/analyst-index.json
node skills/kr-analyst-report-fetch/scripts/fetch-reports.js --input /tmp/analyst-index.json --output /tmp/analyst-extracted.json
node skills/kr-analyst-report-insight/scripts/summarize-reports.js --input /tmp/analyst-extracted.json --output /tmp/analyst-digest.md
node skills/kr-foreign-analyst/scripts/fetch-analyst-coverage.js --company "삼성전자" --ticker 005930 --output /tmp/foreign-coverage.json --allow-empty
node skills/kr-foreign-analyst/scripts/summarize-analyst-views.js --input /tmp/foreign-coverage.json --output /tmp/foreign-views.md
node skills/kr-market-sentiment/scripts/fetch-market-indicators.js --manual examples/kr-market-sentiment/manual-indicators.json --output /tmp/kr-sentiment/indicators.json
node skills/kr-market-sentiment/scripts/score-sentiment-bottom.js --input /tmp/kr-sentiment/indicators.json --output /tmp/kr-sentiment/sentiment-report.md --json-out /tmp/kr-sentiment/score.json
node skills/kr-chatgpt-review/scripts/chatgpt-review.js login                                   # once: log in to ChatGPT by hand in the dedicated browser
node skills/kr-chatgpt-review/scripts/chatgpt-review.js review --memo analysis-example/kr/<company>/memo.md
node skills/kr-research-site/scripts/build-site.js --out site-dist                 # only memos listed in site/published.json; add --production in CI
node skills/kr-research-site/scripts/serve-site.js --dir site-dist --port 8080
node skills/kr-research-site/scripts/indexnow-ping.js --current site-dist/urls.json --previous previous-urls.json --dry-run
node skills/kr-naver-blog-publish/scripts/memo-to-post.js --memo analysis-example/us/Alphabet/memo.md --mode teaser   # Naver summary + canonical link

Architecture

Skill Structure

Each skill under skills/<name>/ follows this layout:

• SKILL.md — frontmatter (name:, description:) + full skill prompt (workflow, rules, source hierarchy, output spec)
• agents/openai.yaml — Codex agent interface config (display_name, short_description, allow_implicit_invocation)
• scripts/ — Node.js analysis scripts (no external npm dependencies; pure Node stdlib)
• references/ — Reference docs loaded as context: workflow.md, output-format.md, script-inputs.md, plus market-specific checklists

Bundled Scripts

All scripts accept JSON via --input and output Markdown or PNG. They use only Node stdlib (fs, https, path, zlib, Intl).

Input JSON schemas are documented in references/script-inputs.md with sample files under examples/<market>/.

Harness

scripts/harness.js automates script chaining and memo quality validation:

node scripts/harness.js --mode chart   --ticker 066970 --company "LG CNS"
node scripts/harness.js --mode dart    --ticker 066970 --company "LG CNS" --dart-input export.json
node scripts/harness.js --mode backlog --company "Sample Heavy" --backlog-input examples/kr-order-backlog-analysis/backlog-sample.json
node scripts/harness.js --mode gate    --company "LG CNS"
node scripts/harness.js --mode all     --ticker 066970 --company "LG CNS" --dart-input export.json
node scripts/harness.js --mode all     --ticker 066970 --company "엘앤에프" --with-blog
node scripts/harness.js --mode all     --ticker 066970 --company "엘앤에프" --with-blog --with-analyst
node scripts/harness.js --mode blog    --ticker 066970 --company "엘앤에프"
node scripts/harness.js --mode analyst --ticker 066970 --company "엘앤에프"
node scripts/harness.js --mode foreign --ticker 005930 --company "삼성전자"
node scripts/harness.js --mode all     --ticker 005930 --company "삼성전자" --with-foreign
node scripts/harness.js --mode regression --ticker 066970 --company "엘앤에프" --dart-input export.json
node scripts/harness.js --mode guard

The quality gate is available on demand via node scripts/harness.js --mode gate --company <name>. It is not run as part of validate-skills.sh / .ps1 (removed to keep CI tolerant of older example memos with different section templates).

Claude.ai DART Viewer Integration

• The Chrome extension lives under integrations/claude-dart-extension/.
• It targets https://dart.fss.or.kr/dsaf001/main.do* and auto-attempts extraction when the viewer page loads.
• The popup exposes Save Export and Retry instead of using a separate fallback path.
• The saved dart-browser-export.json should be normalized with skills/kr-stock-dart-analysis/scripts/normalize-browser-dart-export.js before running section extraction and coverage verification.

Skill Prompt Design

SKILL.md is the authoritative skill definition. It encodes:

1. A 6-step workflow (define scope → gather data → build snapshot → stress-test → value → write)
2. Source priority hierarchy (primary filings first, news last)
3. Operating rules (cite sources, exact dates, separate facts from inference)
4. Minimum output standard (mandatory sections every memo must include)
5. Market-specific checklists (governance structures, KRX vs. SEC filing conventions)

Analysis Examples

analysis-example/<market>/<company>.md are live example memos that demonstrate expected skill output. Per AGENTS.md: refresh prices/metrics/dates before committing, synchronize embedded PNG charts with the markdown, and use primary sources only. These examples drive the expected output shape — update them when skill output format changes.

Key Constraints

• SKILL.md frontmatter is required: must open and close with --- and contain name: and description: fields. Validation will fail otherwise.
• No npm packages: all scripts must work with node alone. Do not add require() calls for non-stdlib modules.
• Korean tickers: fetch-kr-chart.js accepts bare numeric codes (e.g. 066970) or explicit .KS/.KQ suffixes; it retries with .KS then .KQ automatically.
• Cross-platform scripts: every .sh script should have a .ps1 counterpart in scripts/ for Windows users who run scripts locally, but CI only runs on Ubuntu (Linux). The .ps1 files are no longer exercised by CI.
• PDF extraction: both kr-stock-dart-analysis and kr-analyst-report-fetch call skills/kr-stock-dart-analysis/scripts/extract-pdf-text.py via child_process, which requires python3 -m pip install pypdf on the host before running the fetch chain.
• Korean chart fonts: PNG charts (chart-basics.js, valuation-chart.js) auto-discover a Korean font on every platform — macOS (AppleSDGothicNeo by default), Linux (Noto CJK / Nanum via standard paths or fc-match :lang=ko), Windows (Malgun / Nanum / Noto KR via C:\Windows\Fonts and %LOCALAPPDATA%\Microsoft\Windows\Fonts directory scan). Rendering also needs Pillow (python3 -m pip install pillow) on Mac/Linux; Windows uses built-in GDI. When no Korean font is found (or Pillow is missing), charts fall back to a 47-jamo bitmap with incomplete Hangul coverage, and validate-skills.sh / .ps1 prints a warning per chart script. Recommended installs: Linux apt install fonts-noto-cjk / dnf install google-noto-cjk-fonts; English-locale Windows install Noto Sans KR or Malgun Gothic. Override anywhere with KR_STOCK_CHART_FONT=/path/to/font.ttf.
• Analyst-report chain: kr-analyst-report-* skills share the gstack browse binary vendored under kr-naver-browse (via kr-web-browse). Install kr-naver-browse first so the binary is resolvable. Source priority is Hankyung Consensus first, Naver Pay Research as fallback; default lookback is 365 days; login-gated reports are skipped in v1. PDFs are downloaded into a scratch tempdir, extracted, and deleted — only the extracted .txt is cached under .tmp/analyst-report-cache/text/<ticker>/.
• kr-portfolio-guard: install kr-stock-analysis first — guard scripts require("../../kr-stock-analysis/scripts/...") for price fetch and SMA/RSI math and fail loudly if absent. Real holdings live OUTSIDE the repo in a private dir (default ~/stock-analysis-private, override via .env KR_PORTFOLIO_GUARD_HOME); guard reports/ledger contain holdings and must never be passed to publish skills or committed. Scoring aggregates always carry n and the n<30 disclaimer. Weekly schedule must be LOCAL (cron / Windows Task Scheduler) — never a cloud routine.
• 수익 루프 우선 원칙 (E3, 2026-07-04 CEO 리뷰) — 2026-11 해제(guard 검증 완료): 발행 트랙(kr-daily-market-news, kr-naver-blog-publish, kr-research-site, 마켓플레이스 패키징) 투자를 재개한다. guard 결정 루프는 계속 주간으로 돈다.
• kr-research-site: install kr-naver-blog-publish first (shared parsers). The site is the canonical home (canonical URL, ads); Naver gets --mode teaser summaries linking back. Only site/published.json entries are built and the repo is PUBLIC — never list memos that mention holdings, and never put private-dir content under site/. site-dist/ is a build output (gitignored). Cloudflare Workers Builds (GitHub integration) builds it and deploys it as a static-assets Worker via root wrangler.jsonc (Worker name kr-research-site must equal wrangler.jsonc name). The public address is https://kr-research-site.pages.dev, a Pages proxy to that Worker; the old workers.dev address is disabled (workers_dev: false) and returns 404; .github/workflows/site.yml only waits for the live urls.json to match the pushed build and pings IndexNow (skipped while indexNow.key is empty).
• Site comments: pre-moderated; only the operator replies. /admin/comments/ handles status tabs (pending/approved/hidden/spam/trash), bulk actions, replies, banned words and author blocks; the transition table lives in site/analytics/engagement.mjs. Optional Worker Secrets TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID enable new-comment alerts (site/analytics/notify.mjs), which are skipped when unset. Details in site/analytics/OPERATIONS.md.
• kr-earnings-review: 실적 리뷰 요청은 skills/kr-earnings-review/SKILL.md 절차를 그대로 따른다 (collect-earnings-inputs.js 수집 → 준비도 게이트 → 파일 작성 → published.json → 검증·프리뷰 → 브랜치 커밋). 필수 입력(R1~R6)이 하나라도 없으면 .tmp/earnings/<ticker>-<period>/REVIEW-NEEDED.md를 쓰고 발행·배포 없이 사용자 검토를 받는다. 세션 시작 시 남은 REVIEW-NEEDED.md를 확인한다.
• us-earnings-review: 미국 상장사 실적 리뷰는 skills/us-earnings-review/SKILL.md를 따른다 (collect-us-earnings-inputs.js → 같은 R1~R6 게이트 → currency: "USD"·연결 US GAAP · 분기·백만 달러 analysis-data.json, 목표가는 EPS 컨센서스 × P/E 기본). 자료 부족 시 .tmp/earnings/us-<TICKER>-<period>/REVIEW-NEEDED.md로 검토 대기. 미국 무료 자료원은 과거 컨센서스를 보관하지 않으므로 발표 전 주에 snapshot을 로컬에서 돌려 둔다.
• Regression extensibility: --mode regression iterates a ROUTED_STEPS registry at the top of scripts/harness.js and runs every routed leg with artifact + section assertions. When kr-stock-plan gains a new routed skill, add a one-line entry to ROUTED_STEPS ({ name, run, requires, cleanCache, artifacts, assert }) and the regression mode picks it up automatically. A full (non-dry) regression needs network access + pypdf; validate-skills.sh only runs --dry-run so CI stays offline.

gstack

This project recommends gstack for team-wide AI-assisted workflows.

Install it globally:

git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
cd ~/.claude/skills/gstack && ./setup --team

Use the /browse skill from gstack for all web browsing. Never use mcp__claude-in-chrome__* tools.

Available gstack skills:

• /office-hours
• /plan-ceo-review
• /plan-eng-review
• /plan-design-review
• /design-consultation
• /design-shotgun
• /design-html
• /review
• /ship
• /land-and-deploy
• /canary
• /benchmark
• /browse
• /connect-chrome
• /qa
• /qa-only
• /design-review
• /setup-browser-cookies
• /setup-deploy
• /retro
• /investigate
• /document-release
• /codex
• /cso
• /autoplan
• /plan-devex-review
• /devex-review
• /careful
• /freeze
• /guard
• /unfreeze
• /gstack-upgrade
• /learn

Skill routing

When the user's request matches an available skill, ALWAYS invoke it using the Skill tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. The skill has specialized workflows that produce better results than ad-hoc answers.

Key routing rules:

• Product ideas, "is this worth building", brainstorming → invoke office-hours
• Bugs, errors, "why is this broken", 500 errors → invoke investigate
• Ship, deploy, push, create PR → invoke ship
• QA, test the site, find bugs → invoke qa
• Code review, check my diff → invoke review
• Update docs after shipping → invoke document-release
• Weekly retro → invoke retro
• Design system, brand → invoke design-consultation
• Visual audit, design polish → invoke design-review
• Architecture review → invoke plan-eng-review
• Save progress, checkpoint, resume → invoke checkpoint
• Code quality, health check → invoke health