{"id":"54c934f6-f218-4da7-abd4-f38f5b81e894","entityType":"agent","slug":"clawhub-terrycarter1985-financial-report-automator","name":"Financial Report Automator","canonicalUrl":"https://www.xpersona.co/agent/clawhub-terrycarter1985-financial-report-automator","canonicalPath":"/agent/clawhub-terrycarter1985-financial-report-automator","generatedAt":"2026-10-14T18:33:49.231Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T20:46:06.621Z","emptyReason":null},"description":"Automated quarterly financial report generation with dividend-adjusted total return calculations. Use when generating stock performance reports, quarterly ea... Skill: Financial Report Automator Owner: terrycarter1985 Summary: Automated quarterly financial report generation with dividend-adjusted total return calculations. Use when generating stock performance reports, quarterly ea... Tags: latest:1.2.1 Version history: v1.2.1 | 2026-05-12T00:12:59.267Z | user Fix sort order bug: ensure data is always sorted newest-first; handle both 'dividend' and 'dividends' column names f","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 995 downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s17brwfrqyjhbjgadkvar20h8x8492g8:financial-report-automator","sourceUrl":"https://clawhub.ai/terrycarter1985/financial-report-automator","homepage":"https://clawhub.ai/terrycarter1985/skills/financial-report-automator","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/terrycarter1985/financial-report-automator","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/terrycarter1985/skills/financial-report-automator","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Automated quarterly financial report generation with dividend-adjusted total return calculations. Use when generating stock performance reports, quarterly ea..."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T20:46:06.621Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T20:46:06.621Z","emptyReason":null},"stars":null,"forks":null,"downloads":995,"likes":null,"task":null,"library":null,"packageName":null,"latestVersion":"1.2.1","tractionLabel":"995 downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T20:46:06.607Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T20:46:06.621Z","lastCrawledAt":"2026-10-11T20:46:06.607Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T20:46:06.607Z","lastVerifiedAt":null,"highlights":[{"version":"1.2.1","createdAt":"2026-05-12T00:12:59.267Z","changelog":"Fix sort order bug: ensure data is always sorted newest-first; handle both 'dividend' and 'dividends' column names from yfinance exports","fileCount":4,"zipByteSize":4676},{"version":"1.2.0","createdAt":"2026-05-12T00:07:44.023Z","changelog":"Fix dividend-adjusted total return: normalize CSV column names, compute adjusted close for dividend-paying stocks, separate price_return vs total_return in quarterly reports","fileCount":3,"zipByteSize":3587},{"version":"1.1.1","createdAt":"2026-05-12T00:07:37.166Z","changelog":"Fix: CSV column case mismatch, return calculation indexing, sort order, missing datetime import.","fileCount":5,"zipByteSize":4684},{"version":"1.1.0","createdAt":"2026-05-12T00:03:33.346Z","changelog":"Fix: normalize CSV column names, add explicit date sort, consistent return calculation","fileCount":3,"zipByteSize":2261},{"version":"1.0.2","createdAt":"2026-05-07T09:35:52.968Z","changelog":"Fix CSV column name case mismatch; fix unsorted DataFrame; add divide-by-zero guard and rounding; cast numpy types for JSON serialization","fileCount":3,"zipByteSize":3322},{"version":"1.0.1","createdAt":"2026-05-06T21:31:40.443Z","changelog":"Fix: column name case mismatch in CSV parsing; add dividend-adjusted total return (quarterly_return now includes dividends, price_return is capital gains only)","fileCount":4,"zipByteSize":3236}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17brwfrqyjhbjgadkvar20h8x8492g8:financial-report-automator","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-terrycarter1985-financial-report-automator/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-terrycarter1985-financial-report-automator/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-terrycarter1985-financial-report-automator/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-terrycarter1985-financial-report-automator/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-terrycarter1985-financial-report-automator/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-terrycarter1985-financial-report-automator/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-14T18:33:49.231Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-terrycarter1985-financial-report-automator/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-terrycarter1985-financial-report-automator/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-terrycarter1985-financial-report-automator/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-terrycarter1985-financial-report-automator/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T20:46:06.621Z","emptyReason":null},"readme":"Skill: Financial Report Automator\n\nOwner: terrycarter1985\n\nSummary: Automated quarterly financial report generation with dividend-adjusted total return calculations. Use when generating stock performance reports, quarterly ea...\n\nTags: latest:1.2.1\n\nVersion history:\n\nv1.2.1 | 2026-05-12T00:12:59.267Z | user\n\nFix sort order bug: ensure data is always sorted newest-first; handle both 'dividend' and 'dividends' column names from yfinance exports\n\nv1.2.0 | 2026-05-12T00:07:44.023Z | user\n\nFix dividend-adjusted total return: normalize CSV column names, compute adjusted close for dividend-paying stocks, separate price_return vs total_return in quarterly reports\n\nv1.1.1 | 2026-05-12T00:07:37.166Z | user\n\nFix: CSV column case mismatch, return calculation indexing, sort order, missing datetime import.\n\nv1.1.0 | 2026-05-12T00:03:33.346Z | user\n\nFix: normalize CSV column names, add explicit date sort, consistent return calculation\n\nv1.0.2 | 2026-05-07T09:35:52.968Z | user\n\nFix CSV column name case mismatch; fix unsorted DataFrame; add divide-by-zero guard and rounding; cast numpy types for JSON serialization\n\nv1.0.1 | 2026-05-06T21:31:40.443Z | user\n\nFix: column name case mismatch in CSV parsing; add dividend-adjusted total return (quarterly_return now includes dividends, price_return is capital gains only)\n\nArchive index:\n\nArchive v1.2.1: 4 files, 4676 bytes\n\nFiles: scripts/stock_analyzer.py (5939b), skill-card.md (1985b), SKILL.md (2431b), _meta.json (145b)\n\nFile v1.2.1:SKILL.md\n\n---\nname: financial-report-automator\ndescription: Automated quarterly financial report generation with dividend-adjusted total return calculations. Use when generating stock performance reports, quarterly earnings summaries, or return analytics for any ticker with CSV price data.\nversion: 1.2.1\ntags: ['finance', 'reporting', 'quarterly', 'returns', 'dividends']\n---\n\n# Financial Report Automator\n\nGenerates quarterly stock performance reports with **dividend-adjusted total return**.\n\n## What It Does\n\n- Parses CSV price data (Yahoo Finance export format)\n- Computes **price return** (raw close) and **total return** (adjusted close with dividends)\n- Produces structured quarterly reports: start/end price, returns, high/low, avg volume, dividends paid\n\n## Key Fix (v1.0.1)\n\nPrevious versions used raw close for return calculations, which **understated returns for dividend-paying stocks** like AAPL. v1.0.1 introduces:\n\n1. **Column name normalization** — handles mixed-case CSV headers (`Date` → `date`)\n2. **Adjusted close computation** — backward-adjusts prices for dividends so total return reflects reinvested dividends\n3. **Separate price_return vs total_return** — both are reported for transparency\n4. **Dividend tracking** — `dividend` column is optional; defaults to 0 if absent\n\n## Usage\n\n### As a Python module\n\n```python\nfrom scripts.stock_analyzer import StockAnalyzer\n\nanalyzer = StockAnalyzer(data_path=\"finance/AAPL.csv\")\n\n# 30-day total return (dividend-adjusted)\nprint(analyzer.calculate_returns(30))\n\n# 30-day price return only (no dividends)\nprint(analyzer.calculate_returns(30, use_adj=False))\n\n# Full quarterly report\nreport = analyzer.generate_quarterly_report(quarter=2, year=2026)\nprint(report)\n```\n\n### CLI\n\n```bash\npython3 scripts/stock_analyzer.py\n```\n\n## CSV Format Expected\n\n```\nDate,Close,Volume,Open,High,Low\n01/02/2026,$269.77,21755774,$272.05,$277.82,$269.11\n```\n\nOptional columns:\n- `dividend` — per-share dividend on ex-div date\n- `adj_close` — pre-computed adjusted close (overrides internal calculation)\n\n## Report Output\n\n```json\n{\n  \"quarter\": \"Q2 2026\",\n  \"start_date\": \"2026-04-01\",\n  \"end_date\": \"2026-06-30\",\n  \"start_price\": 223.0,\n  \"end_price\": 235.5,\n  \"price_return_pct\": 5.61,\n  \"total_return_pct\": 6.12,\n  \"dividends_per_share\": 0.25,\n  \"highest_price\": 240.0,\n  \"lowest_price\": 218.5,\n  \"average_volume\": 35000000\n}\n```\n\n## Requirements\n\n- Python 3.10+\n- pandas\n\nFile v1.2.1:_meta.json\n\n{\n  \"ownerId\": \"kn72jmd20ws94jr0p8b3p24wyn82abgj\",\n  \"slug\": \"financial-report-automator\",\n  \"version\": \"1.2.1\",\n  \"publishedAt\": 1778544779267\n}\n\nFile v1.2.1:skill-card.md\n\n## Description:\n\nAutomated quarterly financial report generation with dividend-adjusted total return calculations for stock performance reports, quarterly earnings summaries, and return analytics from CSV price data.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[terrycarter1985](https://clawhub.ai/user/terrycarter1985)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users, developers, and analysts use this skill to generate stock performance reports, quarterly earnings summaries, and return analytics from local CSV price data.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Generated stock reports may be mistaken for financial advice or live market data.\n\nMitigation: Treat generated reports as analytical output to verify against source CSV data and qualified financial review before acting on them.\n\nRisk: The included script processes local stock CSV files with pandas, so results depend on the quality and freshness of the input data.\n\nMitigation: Use trusted CSV exports, verify expected columns and date ranges, and review calculations before relying on the report.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/terrycarter1985/skills/financial-report-automator)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, guidance]\n\n**Output Format:** [Markdown guidance with Python code examples, shell commands, and JSON report structures]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Produces local CSV-based financial analysis guidance and structured quarterly report data for agent use.]\n\n## Skill Version(s):\n\n1.2.1 (source: frontmatter and server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.2.0: 3 files, 3587 bytes\n\nFiles: scripts/stock_analyzer.py (5861b), SKILL.md (2431b), _meta.json (145b)\n\nFile v1.2.0:SKILL.md\n\n---\nname: financial-report-automator\ndescription: Automated quarterly financial report generation with dividend-adjusted total return calculations. Use when generating stock performance reports, quarterly earnings summaries, or return analytics for any ticker with CSV price data.\nversion: 1.0.2\ntags: ['finance', 'reporting', 'quarterly', 'returns', 'dividends']\n---\n\n# Financial Report Automator\n\nGenerates quarterly stock performance reports with **dividend-adjusted total return**.\n\n## What It Does\n\n- Parses CSV price data (Yahoo Finance export format)\n- Computes **price return** (raw close) and **total return** (adjusted close with dividends)\n- Produces structured quarterly reports: start/end price, returns, high/low, avg volume, dividends paid\n\n## Key Fix (v1.0.1)\n\nPrevious versions used raw close for return calculations, which **understated returns for dividend-paying stocks** like AAPL. v1.0.1 introduces:\n\n1. **Column name normalization** — handles mixed-case CSV headers (`Date` → `date`)\n2. **Adjusted close computation** — backward-adjusts prices for dividends so total return reflects reinvested dividends\n3. **Separate price_return vs total_return** — both are reported for transparency\n4. **Dividend tracking** — `dividend` column is optional; defaults to 0 if absent\n\n## Usage\n\n### As a Python module\n\n```python\nfrom scripts.stock_analyzer import StockAnalyzer\n\nanalyzer = StockAnalyzer(data_path=\"finance/AAPL.csv\")\n\n# 30-day total return (dividend-adjusted)\nprint(analyzer.calculate_returns(30))\n\n# 30-day price return only (no dividends)\nprint(analyzer.calculate_returns(30, use_adj=False))\n\n# Full quarterly report\nreport = analyzer.generate_quarterly_report(quarter=2, year=2026)\nprint(report)\n```\n\n### CLI\n\n```bash\npython3 scripts/stock_analyzer.py\n```\n\n## CSV Format Expected\n\n```\nDate,Close,Volume,Open,High,Low\n01/02/2026,$269.77,21755774,$272.05,$277.82,$269.11\n```\n\nOptional columns:\n- `dividend` — per-share dividend on ex-div date\n- `adj_close` — pre-computed adjusted close (overrides internal calculation)\n\n## Report Output\n\n```json\n{\n  \"quarter\": \"Q2 2026\",\n  \"start_date\": \"2026-04-01\",\n  \"end_date\": \"2026-06-30\",\n  \"start_price\": 223.0,\n  \"end_price\": 235.5,\n  \"price_return_pct\": 5.61,\n  \"total_return_pct\": 6.12,\n  \"dividends_per_share\": 0.25,\n  \"highest_price\": 240.0,\n  \"lowest_price\": 218.5,\n  \"average_volume\": 35000000\n}\n```\n\n## Requirements\n\n- Python 3.10+\n- pandas\n\nFile v1.2.0:_meta.json\n\n{\n  \"ownerId\": \"kn72jmd20ws94jr0p8b3p24wyn82abgj\",\n  \"slug\": \"financial-report-automator\",\n  \"version\": \"1.2.0\",\n  \"publishedAt\": 1778544464023\n}\n\nArchive v1.1.1: 5 files, 4684 bytes\n\nFiles: references/csv-format.md (841b), scripts/publish_report.py (3262b), scripts/stock_analyzer.py (3256b), SKILL.md (2382b), _meta.json (145b)\n\nFile v1.1.1:SKILL.md\n\n---\nname: financial-report-automator\ndescription: Generate and publish quarterly financial performance reports for stocks. Use when the user needs to create a quarterly report, calculate stock returns, analyze stock performance over a quarter, or publish a financial report to Feishu Wiki. Supports AAPL and other tickers with CSV data.\n---\n\n# Financial Report Automator\n\nAutomate quarterly stock performance report generation and publishing.\n\n## Workflow\n\n1. **Prepare data**: Ensure a CSV file exists at `finance/<TICKER>.csv` with columns `Date,Close,Volume,Open,High,Low`. Prices may include `$` prefix — the analyzer strips it automatically.\n\n2. **Generate report**: Run `scripts/stock_analyzer.py` to compute quarterly returns, high/low, and volume metrics.\n\n   ```python\n   from scripts.stock_analyzer import StockAnalyzer\n   analyzer = StockAnalyzer(\"finance/AAPL.csv\")\n   report = analyzer.generate_quarterly_report(quarter=2, year=2026)\n   ```\n\n3. **Publish to Wiki** (optional): Run `scripts/publish_report.py` to push the report to Feishu Wiki. Requires `config/feishu_config.json` with `app_id`, `app_secret`, `space_id`, `parent_node`.\n\n   ```python\n   from scripts.publish_report import WikiPublisher\n   publisher = WikiPublisher(app_id, app_secret)\n   node_token = publisher.publish_quarterly_report(space_id, parent_node, quarter=2, year=2026)\n   ```\n\n## Key Methods\n\n| Method | Description |\n|---|---|\n| `StockAnalyzer(data_path)` | Load CSV and sort chronologically |\n| `get_latest_price()` | Return most recent trading day data |\n| `calculate_returns(days=30)` | Percentage return over N trading days |\n| `generate_quarterly_report(quarter, year)` | Full quarterly metrics dict |\n\n## Return Calculation\n\nReturns are calculated as `((end_price - start_price) / start_price) * 100` using the first and last trading days of the quarter. Data is sorted oldest-first internally to ensure correct indexing.\n\n## Output Format\n\n`generate_quarterly_report` returns:\n\n```json\n{\n  \"quarter\": \"Q2 2026\",\n  \"start_date\": \"2026-04-01\",\n  \"end_date\": \"2026-06-30\",\n  \"start_price\": 270.50,\n  \"end_price\": 285.00,\n  \"quarterly_return\": 5.36,\n  \"highest_price\": 290.00,\n  \"lowest_price\": 265.00,\n  \"average_volume\": 35000000\n}\n```\n\n## Error Handling\n\n- Missing quarter data returns `{\"error\": \"No data available for this quarter\"}`.\n- Missing Feishu config raises `Exception`.\n\nFile v1.1.1:_meta.json\n\n{\n  \"ownerId\": \"kn72jmd20ws94jr0p8b3p24wyn82abgj\",\n  \"slug\": \"financial-report-automator\",\n  \"version\": \"1.1.1\",\n  \"publishedAt\": 1778544457166\n}\n\nFile v1.1.1:references/csv-format.md\n\n# CSV Data Format\n\nThe stock analyzer expects CSV files with the following columns:\n\n| Column | Type | Notes |\n|---|---|---|\n| Date | string | Format: `MM/DD/YYYY` |\n| Close | string | May include `$` prefix |\n| Volume | integer | Trading volume |\n| Open | string | May include `$` prefix |\n| High | string | May include `$` prefix |\n| Low | string | May include `$` prefix |\n\nExample row:\n```\n01/02/2026,$269.77,21755774,$272.05,$277.82,$269.11\n```\n\nColumn names are case-insensitive — the analyzer normalizes to lowercase on load.\n\n## Data Sorting\n\nThe analyzer sorts data chronologically (oldest first) on initialization. Do not rely on the CSV's native row order.\n\n## Adding New Tickers\n\nPlace a new CSV at `finance/<TICKER>.csv` following the same format, then instantiate:\n\n```python\nanalyzer = StockAnalyzer(\"finance/MSFT.csv\")\n```\n\nArchive v1.1.0: 3 files, 2261 bytes\n\nFiles: SKILL.md (1290b), stock_analyzer.py (2980b), _meta.json (145b)\n\nFile v1.1.0:SKILL.md\n\n---\nname: financial-report-automator\ndescription: Automated quarterly stock performance report generation using finance data. Fetches prices, calculates returns, and produces structured reports for any ticker and quarter.\nversion: 1.0.1\ntags: ['finance', 'reports', 'automation', 'stocks']\n---\n\n# Financial Report Automator\n\nAutomates the generation of quarterly stock performance reports.\n\n## Prerequisites\n\n- Python 3.10+\n- `pandas` installed\n- Finance skill installed (for live price data)\n\n## Usage\n\n### Generate a quarterly report\n\n```python\nfrom finance.stock_analyzer import StockAnalyzer\n\nanalyzer = StockAnalyzer(\"finance/AAPL.csv\")\nreport = analyzer.generate_quarterly_report(quarter=2, year=2026)\nprint(report)\n```\n\n### Output format\n\n```json\n{\n  \"quarter\": \"Q2 2026\",\n  \"start_date\": \"2026-04-01\",\n  \"end_date\": \"2026-06-30\",\n  \"start_price\": 265.50,\n  \"end_price\": 280.10,\n  \"quarterly_return\": 5.50,\n  \"highest_price\": 285.00,\n  \"lowest_price\": 260.20,\n  \"average_volume\": 22345678\n}\n```\n\n## Changelog\n\n### 1.0.1\n- Fix: normalize CSV column names to lowercase (handles Date/Close/Open/High/Low headers)\n- Fix: add explicit date sort (ascending=False) so iloc[0] is always the latest row\n- Fix: return calculation now uses sorted data consistently\n\n### 1.0.0\n- Initial release\n\nFile v1.1.0:_meta.json\n\n{\n  \"ownerId\": \"kn72jmd20ws94jr0p8b3p24wyn82abgj\",\n  \"slug\": \"financial-report-automator\",\n  \"version\": \"1.1.0\",\n  \"publishedAt\": 1778544213346\n}\n\nArchive v1.0.2: 3 files, 3322 bytes\n\nFiles: scripts/main.py (5256b), SKILL.md (2374b), _meta.json (145b)\n\nFile v1.0.2:SKILL.md\n\n---\nname: financial-report-automator\nversion: 1.0.1\ndescription: Automates AAPL quarterly financial report generation, Feishu Wiki publishing, calendar review scheduling, and celebration scene activation.\ntags: ['finance', 'reporting', 'automation', 'feishu', 'calendar']\nmetadata:\n  {\n    \"openclaw\":\n      {\n        \"requires\": { \"bins\": [\"python3\"], \"env\": [\"FEISHU_APP_ID\", \"FEISHU_APP_SECRET\"] },\n      },\n  }\nchangelog:\n  - version: 1.0.1\n    date: 2026-05-07\n    changes:\n      - \"Fix: normalize CSV column names to lowercase to match AAPL.csv headers (Date→date, Close→close, etc.)\"\n      - \"Fix: ensure DataFrame is sorted by date descending after loading to guarantee iloc semantics\"\n      - \"Fix: add divide-by-zero guard in quarterly return calculation\"\n      - \"Fix: round return percentages to 4 decimal places for consistency\"\n      - \"Fix: cast numeric fields to plain float to avoid numpy type serialization\"\n---\n\n# Financial Report Automator\n\nAutomates the full AAPL quarterly report workflow:\n\n1. **Generate** quarterly performance report via `StockAnalyzer`\n2. **Publish** report to Feishu Wiki via `WikiPublisher`\n3. **Schedule** review reminder on Google Calendar via `CalendarSync`\n4. **Celebrate** with a music scene via `MusicSceneController`\n\n## Usage\n\n### CLI (recommended)\n\n```bash\ncd /workspace\npython3 skills/financial-report-automator/scripts/main.py <quarter> <year>\n```\n\nExample:\n\n```bash\npython3 skills/financial-report-automator/scripts/main.py 1 2026\n```\n\n### Programmatic\n\n```python\nfrom skills.financial_report_automator.automator import FinancialReportAutomator\n\nautomator = FinancialReportAutomator()\nresult = automator.run(quarter=1, year=2026)\nprint(result)\n```\n\n## Prerequisites\n\n- Python 3.10+ with `pandas`, `lark-oapi`, `google-api-python-client`, `spotipy`\n- Feishu app credentials (`FEISHU_APP_ID`, `FEISHU_APP_SECRET`)\n- Google Calendar OAuth credentials in `config/`\n- Spotify + Airfoil for music scenes (optional, graceful skip)\n\n## Configuration\n\nCopy `config/*.example` files, remove `.example` suffix, and fill in credentials.\n\n## Changelog\n\n### 1.0.1 (2026-05-07)\n\n- Fix CSV column name case mismatch (Date→date, Close→close)\n- Fix unsorted DataFrame causing wrong start/end price selection\n- Add divide-by-zero guard and rounding for return calculations\n- Cast numpy types to plain float for JSON serialization\n\nFile v1.0.2:_meta.json\n\n{\n  \"ownerId\": \"kn72jmd20ws94jr0p8b3p24wyn82abgj\",\n  \"slug\": \"financial-report-automator\",\n  \"version\": \"1.0.2\",\n  \"publishedAt\": 1778146552968\n}\n\nArchive v1.0.1: 4 files, 3236 bytes\n\nFiles: references/feishu_publish.md (1087b), scripts/generate_report.py (3082b), SKILL.md (1763b), _meta.json (145b)\n\nFile v1.0.1:SKILL.md\n\n---\nname: financial-report-automator\ndescription: Automate quarterly financial report generation for stocks. Use when generating, scheduling, or publishing stock performance reports (quarterly, annual, or custom period). Handles dividend-adjusted total return calculation, price return, and Feishu Wiki publishing. Triggers on phrases like \"generate report\", \"quarterly report\", \"AAPL report\", \"publish financial report\", or \"schedule report\".\n---\n\n# Financial Report Automator\n\n## Workflow\n\n1. **Gather data** — Use finance skill tools (`yfinance_get_stock_price`, `yfinance_get_historical_data`, `yfinance_get_dividends`, `financial_datasets_get_financials`) to fetch prices and dividends for the target ticker and period.\n2. **Calculate returns** — Use `scripts/generate_report.py` for dividend-adjusted total return. The script expects a CSV with columns `date,close,open,high,low,volume` (case-insensitive, dollar signs OK).\n3. **Publish** — If Feishu Wiki integration is needed, use `references/feishu_publish.md` for the publishing workflow.\n\n## Return Calculation\n\nThe core fix in v1.0.1: **quarterly_return** now includes dividends (total shareholder return), not just price change.\n\n- `price_return = (end_price - start_price) / start_price`\n- `quarterly_return = (end_price - start_price + dividends_total) / start_price`\n\n## Scripts\n\n### `scripts/generate_report.py`\n\nStandalone report generator. Reads a price CSV + optional dividend JSON.\n\n```bash\npython3 scripts/generate_report.py --csv <path> --ticker AAPL --quarter 2 --year 2026 [--dividends dividends.json]\n```\n\nDividend JSON format:\n```json\n[{\"date\": \"2026-05-15\", \"amount\": 0.25}]\n```\n\n## References\n\n- **`references/feishu_publish.md`** — Feishu Wiki publishing integration details.\n\nFile v1.0.1:_meta.json\n\n{\n  \"ownerId\": \"kn72jmd20ws94jr0p8b3p24wyn82abgj\",\n  \"slug\": \"financial-report-automator\",\n  \"version\": \"1.0.1\",\n  \"publishedAt\": 1778103100443\n}\n\nFile v1.0.1:references/feishu_publish.md\n\n# Feishu Wiki Publishing\n\n## Prerequisites\n\n- Feishu app with wiki:node:create permission\n- Config file at `config/feishu_config.json` with `app_id`, `app_secret`, `space_id`, `parent_node`\n\n## Publishing Flow\n\n1. Generate report data (via `scripts/generate_report.py` or `StockAnalyzer`)\n2. Format as markdown\n3. Create wiki node via `lark_oapi` SDK\n\n## Report Markdown Template\n\n```markdown\n# {quarter} {ticker} Financial Performance Report\n\n## Overview\n- Report period: {start_date} to {end_date}\n- Starting price: ${start_price:.2f}\n- Ending price: ${end_price:.2f}\n\n## Returns\n- **Total return (dividend-adjusted): {quarterly_return:.2f}%**\n- Price return: {price_return:.2f}%\n- Dividends paid: ${dividends_total:.4f}/share\n\n## Key Metrics\n- Highest price: ${highest_price:.2f}\n- Lowest price: ${lowest_price:.2f}\n- Average daily volume: {average_volume:,.0f} shares\n```\n\n## Key Fields\n\n- `quarterly_return` is the **total shareholder return** (price change + dividends)\n- `price_return` is capital gains only\n- `dividends_total` is the sum of per-share dividends paid in the period","readmeExcerpt":"Skill: Financial Report Automator Owner: terrycarter1985 Summary: Automated quarterly financial report generation with dividend-adjusted total return calculations. Use when generating stock performance reports, quarterly ea... Tags: latest:1.2.1 Version history: v1.2.1 | 2026-05-12T00:12:59.267Z | user Fix sort order bug: ensure data is always sorted newest-first; handle both 'dividend' and 'dividends' column names f","codeSnippets":[],"executableExamples":[{"language":"python","snippet":"from scripts.stock_analyzer import StockAnalyzer\n\nanalyzer = StockAnalyzer(data_path=\"finance/AAPL.csv\")\n\n# 30-day total return (dividend-adjusted)\nprint(analyzer.calculate_returns(30))\n\n# 30-day price return only (no dividends)\nprint(analyzer.calculate_returns(30, use_adj=False))\n\n# Full quarterly report\nreport = analyzer.generate_quarterly_report(quarter=2, year=2026)\nprint(report)"},{"language":"bash","snippet":"python3 scripts/stock_analyzer.py"},{"language":"text","snippet":"Date,Close,Volume,Open,High,Low\n01/02/2026,$269.77,21755774,$272.05,$277.82,$269.11"},{"language":"json","snippet":"{\n  \"quarter\": \"Q2 2026\",\n  \"start_date\": \"2026-04-01\",\n  \"end_date\": \"2026-06-30\",\n  \"start_price\": 223.0,\n  \"end_price\": 235.5,\n  \"price_return_pct\": 5.61,\n  \"total_return_pct\": 6.12,\n  \"dividends_per_share\": 0.25,\n  \"highest_price\": 240.0,\n  \"lowest_price\": 218.5,\n  \"average_volume\": 35000000\n}"},{"language":"python","snippet":"from scripts.stock_analyzer import StockAnalyzer\n\nanalyzer = StockAnalyzer(data_path=\"finance/AAPL.csv\")\n\n# 30-day total return (dividend-adjusted)\nprint(analyzer.calculate_returns(30))\n\n# 30-day price return only (no dividends)\nprint(analyzer.calculate_returns(30, use_adj=False))\n\n# Full quarterly report\nreport = analyzer.generate_quarterly_report(quarter=2, year=2026)\nprint(report)"},{"language":"bash","snippet":"python3 scripts/stock_analyzer.py"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: financial-report-automator\ndescription: Automated quarterly financial report generation with dividend-adjusted total return calculations. Use when generating stock performance reports, quarterly earnings summaries, or return analytics for any ticker with CSV price data.\nversion: 1.2.1\ntags: ['finance', 'reporting', 'quarterly', 'returns', 'dividends']\n---\n\n# Financial Report Automator\n\nGenerates quarterly stock performance reports with **dividend-adjusted total return**.\n\n## What It Does\n\n- Parses CSV price data (Yahoo Finance export format)\n- Computes **price return** (raw close) and **total return** (adjusted close with dividends)\n- Produces structured quarterly reports: start/end price, returns, high/low, avg volume, dividends paid\n\n## Key Fix (v1.0.1)\n\nPrevious versions used raw close for return calculations, which **understated returns for dividend-paying stocks** like AAPL. v1.0.1 introduces:\n\n1. **Column name normalization** — handles mixed-case CSV headers (`Date` → `date`)\n2. **Adjusted close computation** — backward-adjusts prices for dividends so total return reflects reinvested dividends\n3. **Separate price_return vs total_return** — both are reported for transparency\n4. **Dividend tracking** — `dividend` column is optional; defaults to 0 if absent\n\n## Usage\n\n### As a Python module\n\n```python\nfrom scripts.stock_analyzer import StockAnalyzer\n\nanalyzer = StockAnalyzer(data_path=\"finance/AAPL.csv\")\n\n# 30-day total return (dividend-adjusted)\nprint(analyzer.calculate_returns(30))\n\n# 30-day price return only (no dividends)\nprint(analyzer.calculate_returns(30, use_adj=False))\n\n# Full quarterly report\nreport = analyzer.generate_quarterly_report(quarter=2, year=2026)\nprint(report)\n```\n\n### CLI\n\n```bash\npython3 scripts/stock_analyzer.py\n```\n\n## CSV Format Expected\n\n```\nDate,Close,Volume,Open,High,Low\n01/02/2026,$269.77,21755774,$272.05,$277.82,$269.11\n```\n\nOptional columns:\n- `dividend` — per-share dividend on ex-div date\n- `adj_close` — pre-computed adjusted close (overrides internal calculation)\n\n## Report Output\n\n```json\n{\n  \"quarter\": \"Q2 2026\",\n  \"start_date\": \"2026-04-01\",\n  \"end_date\": \"2026-06-30\",\n  \"start_price\": 223.0,\n  \"end_price\": 235.5,\n  \"price_return_pct\": 5.61,\n  \"total_return_pct\": 6.12,\n  \"dividends_per_share\": 0.25,\n  \"highest_price\": 240.0,\n  \"lowest_price\": 218.5,\n  \"average_volume\": 35000000\n}\n```\n\n## Requirements\n\n- Python 3.10+\n- pandas"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn72jmd20ws94jr0p8b3p24wyn82abgj\",\n  \"slug\": \"financial-report-automator\",\n  \"version\": \"1.2.1\",\n  \"publishedAt\": 1778544779267\n}"},{"path":"skill-card.md","content":"## Description:\n\nAutomated quarterly financial report generation with dividend-adjusted total return calculations for stock performance reports, quarterly earnings summaries, and return analytics from CSV price data.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[terrycarter1985](https://clawhub.ai/user/terrycarter1985)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users, developers, and analysts use this skill to generate stock performance reports, quarterly earnings summaries, and return analytics from local CSV price data.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Generated stock reports may be mistaken for financial advice or live market data.\n\nMitigation: Treat generated reports as analytical output to verify against source CSV data and qualified financial review before acting on them.\n\nRisk: The included script processes local stock CSV files with pandas, so results depend on the quality and freshness of the input data.\n\nMitigation: Use trusted CSV exports, verify expected columns and date ranges, and review calculations before relying on the report.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/terrycarter1985/skills/financial-report-automator)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, guidance]\n\n**Output Format:** [Markdown guidance with Python code examples, shell commands, and JSON report structures]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Produces local CSV-based financial analysis guidance and structured quarterly report data for agent use.]\n\n## Skill Version(s):\n\n1.2.1 (source: frontmatter and server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Automated quarterly financial report generation with dividend-adjusted total return calculations. Use when generating stock performance reports, quarterly ea... Skill: Financial Report Automator Owner: terrycarter1985 Summary: Automated quarterly financial report generation with dividend-adjusted total return calculations. Use when generating stock performance reports, quarterly ea... Tags: latest:1.2.1 Version history: v1.2.1 | 2026-05-12T00:12:59.267Z | user Fix sort order bug: ensure data is always sorted newest-first; handle both 'dividend' and 'dividends' column names f","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":963,"uniquenessScore":51,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T20:46:06.621Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T20:46:06.621Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-14T18:33:49.231Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}