Stock Qualitative Analysis Skill

中文说明 纯小白版说明文档

Overview

A skill for producing buy‑side style qualitative stock analysis reports (定性分析) from SEC filings and other public sources. It enforces strict citations, comprehensive section coverage, and explicit placeholders for missing evidence.

Key Features

• Evidence‑first reporting with explicit citations and placeholders
• Section‑by‑section workflow aligned to assets/report-template.md
• English output when the user query is in English
• Modular data acquisition (SEC EDGAR + local PDFs)
• HTML 10‑K section extraction for faster analysis

Requirements

• Python 3
• Network access for SEC EDGAR fetching (optional)

Directory Structure

• SKILL.md: Skill definition and execution rules
• assets/report-template.md: Report template
• references/: Guardrails, validation checklist, goldenset
• scripts/: Data acquisition and extraction utilities

Quick Start

0) Install the skill in your agent

Place the stock-qualitative-analysis/ folder in the skills directory that your agent scans. For Claude Code, Codex, or OpenCode, use the tool’s configured skills path (check its docs/settings) and ensure the folder name matches stock-qualitative-analysis.

1) (Optional) Prepare sources

Local PDFs and SEC filings are both optional. If you already have files, ingest them; otherwise the Agent can fetch data during execution.

If local filings are available, prefer local PDFs first:

python3 scripts/ingest_local_pdfs.py --folder  --out ./cache/source_manifest.json

2) (Optional) Fetch SEC filings

python3 scripts/fetch_sec_edgar.py --ticker AAPL --form 10-K 10-Q --start 2022-01-01 --out ./cache/sec_edgar

Then build a unified manifest:

python3 scripts/build_source_manifest.py --ticker AAPL --forms 10-K 10-Q --start 2022-01-01 --sec-out ./cache/sec_edgar --out ./cache/source_manifest.json

3) Extract 10‑K HTML sections

python3 scripts/extract_sec_html_sections.py --html  --items 1,1a,7,7a,8 --out-dir ./cache/sections

4) Generate the report (Agent‑driven)

The Agent reads assets/report-template.md and fills each section using available sources and extracted item text. See SKILL.md for the execution rules.

English Output

If the user query is in English, the Agent must generate an English report while preserving the template structure. Section labels should be translated consistently (e.g., Conclusion / Details / Evidence).

Offline Mode

If network access is blocked (SSL/Cloudflare), use local PDFs and HTML files only. The skill supports building a manifest from local files and extracting sections from local HTML.

Troubleshooting

• SSL/Cloudflare blocked: Use local filings or configure SEC_USER_AGENT with multiple agents (comma‑separated). Example: SEC_USER_AGENT="UA1,UA2" python3 scripts/fetch_sec_edgar.py ...