Trading Skills

AI skills for better trading and investing decisions.

trading-skills is a portable, capability-first collection of SKILL.md packages for agent tools. It helps traders and investors think more clearly, prepare better, size cleaner, manage risk more explicitly, and review decisions without hindsight theater.

The point is not to generate magic signals. The point is to give AI structure: better trade prep, better risk process, better execution planning, and better post-trade learning.

The core library is analysis-first. Optional live-trade integrations can sit alongside it as separate, provider-specific skills without changing the default analytical workflows.

If this repo helps your workflow, star it.

Start Here

If you are not sure where to begin:

• New trade idea and want one go / no-go workflow: pre-trade-check
• Preparing around an upcoming report: earnings-trade-prep
• Too many names and need triage: watchlist-review
• Need to pressure-test the actual claim: thesis-validation
• Need to check if the plan is even tradable: execution-plan-check
• Need to size the trade conservatively: position-sizing
• Need to review portfolio overlap before adding: portfolio-risk-review
• Managing an open position: position-management
• Reviewing a closed trade: post-trade-debrief

Why Trading Skills

Generic AI gives you words. Trading and investing require process.

This repo is built to improve the parts of decision-making that actually matter:

• Better prep: identify what matters before the trade, not after it.
• Better risk control: make invalidation, structure, concentration, and sizing explicit.
• Better execution discipline: separate a good idea from an executable plan.
• Better review quality: turn journals and post-mortems into repeatable improvements.
• Better trust: disclose assumptions, source quality, and missing information instead of pretending certainty.

This is especially useful if you already use AI but want less confident prose and more rigorous thinking.

How It Works

The repo contains three useful layers:

• Groups: browsing categories such as market context, idea discovery, and review
• Atomic skills: reusable capabilities such as thesis-validation, risk-reward-sanity-check, or position-sizing
• Workflow skills: wrappers such as pre-trade-check and post-trade-debrief that chain the minimum necessary atomic skills

The default usage pattern is simple:

1. Start from the user’s actual context.
2. Run the smallest skill or workflow that fits the job.
3. Carry forward a compact trade context, not a pile of chat history.
4. Use external data only when the user’s material is not enough.
5. Keep trust high by disclosing what is known, assumed, and missing.

Install

The intended UX is capability-first:

npx skills add marian2js/trading-skills@pre-trade-check
npx skills add marian2js/trading-skills@position-sizing
npx skills add marian2js/trading-skills@earnings-preview

You can also install narrower capabilities directly when you already know the job you want to improve.

Example Prompts

• “Use pre-trade-check on this swing idea and tell me if it is actually ready.”
• “Use earnings-trade-prep on NVDA for next week and tell me whether this is prep-only, pre-event tradeable, or a hold-through candidate.”
• “Use portfolio-risk-review on my current book before I add more semis.”
• “Use watchlist-review on these semis for next week and tell me which names actually deserve active attention.”
• “Use thesis-validation on my semis swing thesis and tell me what evidence is real, what is assumption, and what would invalidate it.”
• “Use execution-plan-check on my plan to buy a niche ETF at the open and tell me whether the order logic is actually executable.”
• “Use position-sizing for a $125,000 account risking 0.5% with entry 412.30 and stop 406.80.”
• “Use risk-reward-sanity-check on a swing long with entry 58.20, stop 55.90, and target 65.50.”
• “Use macro-event-analysis to summarize macro event risk for the next 48 hours.”
• “Use position-management on this open long and tell me whether to hold, trim, tighten risk, or exit.”
• “Use post-trade-debrief on this closed trade and tell me the real lesson.”

See docs/examples/ for longer walkthroughs.

Trust Model

High-trust output is a product requirement. Skills should make it obvious:

• what came from the user
• what came from a provider
• how fresh the information is
• what assumptions were made
• what important information is still missing

The repo avoids hype, fake precision, and guaranteed-outcome language.

Quick Links

• Examples
• Composing skills
• Optional provider support
• Compatibility and install
• Architecture
• Contributing
• Changelog

Available Skills

The current library stays intentionally small and capability-first:

Integration Pattern

For agent systems, the cleanest pattern is:

1. gather user context first
2. run the smallest number of skills needed
3. carry forward a compact markdown trade context instead of raw transcript state
4. disclose any provider-based data that was used
5. keep execution and broker actions outside this repo

Recommended composition:

• use pre-trade-check when the user wants one readiness verdict instead of manually running each check
• use earnings-trade-prep when the main question is how to prepare for or trade around an upcoming report
• use portfolio-risk-review when the user needs a whole-book risk view before adding or maintaining exposure
• use post-trade-debrief when the user wants one post-trade learning workflow instead of manual review routing
• use watchlist-review when the user starts with too many names and needs triage first
• use catalyst-map when the user needs one event map across names, sectors, or themes
• use evidence-gap-check when the idea is interesting but the missing information is not yet prioritized
• use macro-event-analysis or earnings-preview to frame event risk
• use market-regime-analysis to classify the broader environment
• use thesis-validation to pressure-test the claim before turning it into structure
• use risk-reward-sanity-check to pressure-test structure
• use execution-plan-check to verify the order logic works in the real market
• use portfolio-concentration before final sizing if portfolio fit could block the trade
• use position-sizing only after the stop is stable
• use position-management while the trade is open
• use journal-pattern-analyzer to review a batch of trades for repeatable patterns
• use post-trade-review after the trade closes

See docs/composing-skills.md for the shared Trade Context schema and realistic chaining examples.

Docs

• Architecture
• Examples
• Compatibility and install
• Composing skills
• Optional provider support
• Repo conventions
• Skill design principles
• Skill template
• New skill checklist
• Versioning and releases
• Release checklist
• Provider support

Validation

Run the repository checks with one command:

make validate

Regenerate the machine-readable catalog and README skill index after metadata changes:

make catalog

The current checks cover:

• every skill directory contains SKILL.md
• frontmatter fields exist and match the directory name
• descriptions are specific enough to be useful
• catalog metadata matches the skill folders
• README skill index stays in sync with the catalog
• local references in SKILL.md files exist
• README and docs markdown links stay valid
• forbidden artifacts do not leak into tracked files
• public skill names do not leak provider branding
• provider references linked from skills exist
• skill-local markdown stays aligned with the user-data-first workflow
• skill directories stay lean by excluding fixtures/ and sample-output.md

Run skill-doctor locally with:

make doctor

The CI workflow also runs the published marian2js/skill-doctor GitHub Action on the full repository and fails only on analyzer errors.