The Problem

Financial‑AI agents need ready‑to‑use “skills” (news ingest, stock lookup, sentiment, forecasting, visualisation) but building, wiring and maintaining those components from scratch is time‑consuming and error‑prone. Teams that already have an LLM‑backed agent must repeatedly copy boiler‑plate code, re‑implement database helpers, and manually keep model files in sync.

What This Does

Awesome-finance-skills ships a curated set of 8 plug‑in skill folders under skills/ (e.g. alphaear‑news, alphaear‑predictor, alphaear‑logic-visualizer). Each skill is a self‑contained Python package containing:

  • SKILL.md – metadata required by the npx skills installer.
  • scripts/ – the runtime code (e.g. database_manager.py, search_tools.py, model modules).
  • tests/ – unit tests exercising the public API (12 test files total).

Common utilities live in duplicated modules such as scripts/utils/database_manager.py (used by reporter, predictor, signal‑tracker) and scripts/utils/search_tools.py. The core forecasting model lives in skills/alphaear‑predictor/scripts/predictor/model/module.py (46 functions, 14 classes) and is mirrored across the other four predictor‑style skills.

How It Is Wired

Execution starts at the only explicit entry point:

main → skills/skill-creator/scripts/init_skill.py:320

main calls init_skill, which creates the target skill directory (skill_dir.mkdir) and copies the selected skill folder into the user’s agent workspace. From there the agent framework loads the skill’s scripts/ package.

Typical runtime flow for a data‑driven skill (e.g. alphaear‑predictor) is:

  1. Database access – skills/alphaear‑predictor/scripts/utils/database_manager.py (DatabaseManager.__init__, _init_db, save_daily_news, get_daily_news) is the most‑imported module (7 inbound imports, 0 outbound). All other skills import the same manager, giving it the widest blast radius.
  2. Search / news fetch – search_tools.py (search, _generate_hash, _wait_for_rate_limit) calls external APIs (network I/O) and performs a cryptographic hash for rate‑limit keys.
  3. Model inference – predictor/model/module.py defines forward, quantize, codebook_entropy. Calls to get_model, predict, and search appear in the internal call graph 5–8 times each, making this module a second hub.
  4. Result handling – tools/toolkits.py (e.g. fetch_hot_news, enrich_news_content) reads/writes the SQLite DB and prepares data for LLM prompts.

The import graph shows no circular dependencies (0 cycles) and 97 import edges across 139 Python modules, indicating a relatively flat hierarchy. However, the same utility code (database manager, search tools, LLM factory) is duplicated across the five “alphaear‑*” families, inflating maintenance cost.

How To Use It

# Clone the repo (use the exact URL required)
git clone https://github.com/moses-y/Awesome-finance-skills.git
cd Awesome-finance-skills

# Install a single skill into an OpenCode workspace (example)
npx skills add moses-y/Awesome-finance-skills@alphaear-news

# Or copy manually for a custom agent
python - <<'PY'
from skills.skill-creator.scripts.init_skill import init_skill
init_skill('alphaear-news', '/path/to/your/agent/skills')
PY

No requirements.txt or pyproject.toml is present, so the repository assumes the host environment already provides torch and the standard library. Configuration files are not bundled; each skill expects a SQLite DB under its own scripts/ folder (created on first run) and any required API keys must be supplied via environment variables referenced in the respective search_tools.py implementations (e.g. JINA_API_KEY).

Running the unit tests validates basic behavior:

pytest tests/alphaear‑news/test_news.py

Real‑World Use

A trading desk that runs an internal LLM can drop alphaear‑predictor into its agent’s skill path. When the agent receives a query like “Forecast AAPL price next week”, the skill:

  1. Calls search_tools.search to pull the latest news (network I/O).
  2. Stores the articles via DatabaseManager.save_daily_news.
  3. Feeds the cleaned corpus to predictor/model/module.forward for a Kronos forecast.
  4. Returns a structured JSON that downstream components render as charts.

All steps are traceable to the three hub modules identified above.

Code Health & Issues

  • High – CI missing – 139 source files, no .github/ or other CI config. Fix: add a GitHub Actions workflow that runs pytest on push/PR.
  • Medium – Broad exception handling – database_manager.py in reporter, predictor, signal‑tracker uses bare except: blocks. Fix: catch specific exceptions, log or re‑raise.
  • High – Deep nesting – Same DB manager files contain indentation depth up to 6, making logic hard to follow. Fix: refactor with early returns or guard clauses.
  • High – Duplicated code blocks – Repeated 6‑line snippets across visualiser scripts and prompts (≈5 k lines total). Fix: extract shared helpers into a common module.

Other hygiene notes: tests are present, a LICENSE exists, no secrets detected, but there is no Dockerfile or lockfile for reproducible installs.

The Bottom Line

Awesome-finance-skills delivers a ready‑made suite of finance‑focused LLM skills with clear module boundaries, but the codebase suffers from duplicated utilities, deep nesting, and a complete lack of automated CI. It is suitable for teams that need quick prototyping of finance agents and are comfortable refactoring shared helpers and adding their own CI pipeline.