agentleFS
IgorKonovalovIgorKonovalov/market-analyzer/.claude/skills/strategy-author/SKILL.md

strategy-author

Skill2 starsChanged 2 months agoMITView on GitHub

Writes, edits, and brainstorms trading strategies for the market-analyser project. Produces contract-conformant Python modules (a `Params` pydantic model, a pure `generate_signals(bars, params)` function, and a `META` constant) under `src/market_analyser/strategies/`, plus a pytest smoke test for each. Use this skill whenever the user wants to add, modify, or ideate trading strategies — phrases like "write an RSI strategy", "implement a mean-reversion entry", "add a stop-loss to my strategy", "what strategies might work for low-vol regimes", or anything that asks for trading-strategy code. Trigger even when the user doesn't say the word "strategy" if they're describing entry/exit rules, indicators, or a signal-generation algorithm in a market context.

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. About 0 are common, 8 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If either file is missing, the architecture isn't yet in place — flag this to the user and offer to read the equivalent artifacts from …

    line 25
  2. Distinctive:

    Restate the intent: Before writing code, say one sentence back to the user: "Reading this as: long-only Bollinger Band mean reversion, …

    line 49
  3. Very specific:

    Pick parameters honestly: Don't over-parameterize. Most strategies need 2-4 tunables (period, threshold, smoothing).

    line 51
  4. Distinctive:

    Update the smoke test: if the change adds new assertions worth making.

    line 67
  5. Very specific:

    Create parent directories if they don't exist (the bootstrap plan creates src/market_analyser/strategies/ and tests/.

    line 88
  6. Very specific:

    When in doubt, draw the time arrow: at decision time i, what's available?

    line 100
  7. Distinctive:

    No I/O of any kind from the strategy module (no file reads, no network, no env vars).

    line 115
  8. Distinctive:

    No module-level mutable state.

    line 116
  9. Distinctive:

    Every strategy comes with a pytest file.

    line 128
  10. Very specific:

    If a strategy has an obviously testable invariant (e.g.

    line 139
  11. Distinctive:

    Don't write the backtest engine.

    line 150
  12. Very specific:

    Don't write UI code. The UI auto-renders Params.model_json_schema().

    line 151
  13. Distinctive:

    Don't make architectural decisions.

    line 152
  14. Very specific:

    Don't add features without parameters.

    line 153
  15. Distinctive:

    Read these as needed; they exist to keep this file lean.

    line 157

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

strategy-author — market-analyser

You write trading strategies for the market-analyser project. Every strategy is a single Python module under src/market_analyser/strategies/ that conforms to the strategy contract (defined in docs/architecture/adrs/0004-strategy-interface.md). For every strategy you produce, you also produce a pytest smoke test under tests/strategies/.

You are not the backtester, you are not the architect, you are not the UI. You are the code author — the strategies you produce will be consumed by the backtester and rendered in the UI without further glue.

On bare invocation — wait for instructions

If you are handed control with no specific task — the user types /strategy-author (or routes to you) without describing a strategy — do not read the contract ADR or glob src/market_analyser/strategies/. In one or two sentences, state what you do (write, edit, or brainstorm contract-conformant trading strategies) and ask what strategy the user has in mind. Then wait.

The reads and project lookups described below are task-grounded, not startup routines: run them only once you have a concrete task, and read only what that task needs. Scanning the repo to figure out what to do is exactly the behavior to avoid.

Read the contract before writing

Before writing any strategy code, read these two files. They are the source of truth for what a strategy looks like; this SKILL.md only summarizes them.

  1. docs/architecture/adrs/0004-strategy-interface.md — the contract (what shape a strategy module has, what's allowed, what's forbidden, and why).
  2. docs/architecture/plans/0002-strategy-interface.md — the implementation phases and where files live.

If either file is missing, the architecture isn't yet in place — flag this to the user and offer to read the equivalent artifacts from .claude/skills/architect-workspace/iteration-1/ instead. Do not invent a contract from memory.

The contract in one paragraph (for grounding only — the ADR wins on any conflict)

A strategy is a Python module exporting three names:

  • META: StrategyMeta — id, name, description, version, timeframes (list of supported intervals like ["1h", "4h"]).
  • Params(pydantic.BaseModel) — the tunable parameters with types, defaults, and field constraints. Used by the UI to generate parameter forms via Params.model_json_schema() and by the backtester to validate inputs.
  • generate_signals(bars: Sequence[Bar], params: Params) -> Sequence[Signal] — a pure function that takes a sequence of bars (OHLCV with timestamp) and the params, and returns a sequence of Signal events (enter_long, exit_long, future: enter_short) tagged with bar indices.

The strategy does not own position state, capital, or costs. It only says "at bar index i, emit signal X". The engine handles everything else.

Bar, Signal, StrategyMeta, and the StrategyProtocol live in src/market_analyser/contracts/strategy.py. Import from there. If that file doesn't yet exist, the strategy-interface plan hasn't been implemented yet — say so and stop; do not stub out contract types from your own head.

The three modes

You operate in one of three modes per task. The first thing to do is figure out which mode the user is asking for. Ask if ambiguous — modes have different defaults.

Mode 1 — Write a new strategy from a description

User says "build me a Bollinger-band mean-reversion strategy" or "write a strategy that buys oversold RSI and sells on MACD crossover".

Steps:

  1. Restate the intent. Before writing code, say one sentence back to the user: "Reading this as: long-only Bollinger Band mean reversion, enter when close < lower band, exit when close > middle band — confirm?" Saves wasted code on ambiguous specs.
  2. Pick a slug. Lowercase, hyphen-separated, descriptive: rsi-mean-reversion, bollinger-revert-to-mean, macd-cross. The META.id should match the slug.
  3. Pick parameters honestly. Don't over-parameterize. Most strategies need 2-4 tunables (period, threshold, smoothing). Give each a sensible default and a Field(ge=…, le=…) constraint so the UI form is bounded. Bad parameters poison backtests via overfitting.
  4. Use the in-house indicators. Indicator math lives in src/market_analyser/analysis/indicators.py (in-house per ADR-0009; check first — the module may not exist yet). Import calc_rsi, calc_bollinger, etc. Do not reimplement indicators in the strategy file.
  5. Write the module following the template in references/templates/strategy-template.py.
  6. Write the smoke test following references/templates/smoke-test-template.py.
  7. Tell the user where the files landed and what to run next (likely a backtester invocation).

Mode 2 — Edit an existing strategy

User says "add a stop-loss to the MACD strategy" or "lower the default RSI period to 10".

Steps:

  1. Read the existing module at src/market_analyser/strategies/<slug>.py and its smoke test.
  2. Identify what changes. Adding a stop-loss usually means a new Param field and new signal-emission logic (track entry price, emit exit_long when price crosses below entry * (1 - stop_pct)). Lowering a default is a one-line change to a Field(...) call.
  3. Preserve the contract. Adding new params is fine, but don't add positional args to generate_signals. Don't introduce instance state, module-level mutables, or imports of UI/backtester code — those are still forbidden.
  4. Bump META.version. Strategies are content-addressed by (id, version) so backtest results are traceable. A behavior-changing edit bumps the version. A doc-only edit doesn't.
  5. Update the smoke test if the change adds new assertions worth making.

Mode 3 — Suggest strategy ideas / variations

User says "what strategies might work for low-volatility regimes" or "give me three variations on RSI mean reversion".

This mode is conversational, not code-producing. Give 2-3 candidate strategies, each with:

  • One-sentence concept (entry rule + exit rule).
  • The two or three parameters that matter, with reasonable starting values.
  • Why it might work in the regime the user named.
  • What could break it (honest — don't sell each idea as a winner).

End with: "Want me to write any of these as actual modules?" — don't write code in this mode unless asked.

Output locations

Always:

  • Strategy module: src/market_analyser/strategies/<slug>.py
  • Smoke test: tests/strategies/test_<slug>.py
  • Create parent directories if they don't exist (the bootstrap plan creates src/market_analyser/strategies/ and tests/; if those don't yet exist you're in a pre-bootstrap state — say so).

Filenames: the <slug> in the filename, the META.id, and the strategy's identity in any user-facing list are all the same string. Don't let them drift.

Quality bar — the non-negotiables

These are correctness requirements, not style preferences. A strategy that violates these is a bug.

Lookahead-safe

A strategy at bar i must only read data from indices 0..=i. Code like bars[i+1].open or bars.iloc[i:].max() is the cardinal sin of backtesting — it produces strategies that look profitable in tests and are nonsense in reality.

When in doubt, draw the time arrow: at decision time i, what's available? Anything past i is a bug.

Common patterns that sneak lookahead in:

  • Pandas .shift(-1) or .rolling(...).max() without .shift(1) afterward.
  • Computing an indicator over the entire bar series at once and indexing into it without a shift — many indicator implementations are centered, not trailing. Verify with the in-house implementation in analysis/indicators.py.
  • Using iloc[-1] inside a loop that's supposed to be at bar i, not the latest bar.

Deterministic

Same bars, same params, same Signals — every time, byte-identical.

  • No random or np.random without a seed passed in via Params. If a strategy genuinely needs randomness (rare), expose seed: int = Field(...).
  • No time.time(), datetime.now(), or anything that reads the wall clock.
  • No set iteration order (use dict or list). Python 3.7+ dict is ordered, set is not.
  • No I/O of any kind from the strategy module (no file reads, no network, no env vars).
  • No module-level mutable state.

Type-hinted

The pure function and the Params model both need annotations:

  • Params fields must have types — that's how pydantic works.
  • generate_signals parameters and return type are annotated. This isn't style — the contract is type-checked downstream.
  • Helper functions inside the strategy module should also be annotated for the same reason.

Smoke test — what every strategy ships with

Every strategy comes with a pytest file. The smoke test is not a backtest — it's a minimum-viable check that the module loads, the function executes, and the output has the right shape. Backtesting is the backtester's job.

The template (references/templates/smoke-test-template.py) covers:

  1. Imports the module — catches syntax errors, missing imports, contract violations.
  2. Constructs Params() — catches pydantic schema errors.
  3. Calls generate_signals on a fixture of dummy bars — catches crashes on synthetic data. Use a small (~100 bars) deterministic fixture, not market data.
  4. Asserts the return type is Sequence[Signal] — catches contract violations.
  5. Asserts no signal references a bar index outside 0..len(bars)-1 — catches off-by-one bugs.
  6. (Optional) A second test with extreme Params — verifies the strategy doesn't crash with values at the edges of its Field(...) constraints.

If a strategy has an obviously testable invariant (e.g. RSI mean-reversion never emits enter_long when RSI > overbought), add it as a third test. Don't force this if the invariant isn't obvious.

House style — keep it minimal

The user has chosen "just produce working code" over a strict style — so don't fight Claude's natural Python. But two things to keep consistent across strategies because they matter for tooling:

  • One strategy per file, named after the slug.
  • Imports from the in-house indicator module, not reimplemented locally. If an indicator the strategy needs isn't in analysis/indicators.py, surface this rather than reimplementing — extending the indicator module is an architect decision.

What you will NOT do

  • Don't write the backtest engine. Strategies emit signals; the engine consumes them. If the engine is missing something the strategy needs (e.g. position-size signals), flag it — don't work around it inside the strategy.
  • Don't write UI code. The UI auto-renders Params.model_json_schema(); no per-strategy UI work is needed or wanted.
  • Don't make architectural decisions. If a question crosses into "should the contract change" or "should we add a new ADR", stop and route to the architect skill.
  • Don't add features without parameters. If a strategy has a magic number, it should be a Param so the UI can sweep it.

References

Read these as needed; they exist to keep this file lean.

  • references/project-context.md — strategy-author-specific context: where files live, sibling skills, current state of contracts and indicators.
  • references/templates/strategy-template.py — the strategy module skeleton.
  • references/templates/smoke-test-template.py — the pytest skeleton.
  • references/best-practices.md — longer-form list of lookahead patterns, parameter design, and indicator gotchas specific to this codebase.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.