market-notes
Skill3 starsChanged 4 months agoMITView on GitHub
Per-pair thesis notes with timestamps and optional expiration. Shared context for any market skill to surface alongside its verdict (cycle theses, watch levels, planned setups). Stores notes as JSON, one file keyed by ticker.
In this repository47 other files it gives its agents.
- AGENTS.mdAGENTS.md
- beadsSkill
- backtest-engineSkill
- backtest-pipelineSkill
- backtest-trend-minerSkill
- bug-scanSkill
- daily-trade-pickSkill
- execution-kraken-perpsSkill
- execution-kraken-spotSkill
- l3-conviction-scanSkill
- market-accumulationSkill
- market-basisSkill
- market-breadthSkill
- market-breakoutSkill
- market-emaSkill
- market-exhaustionSkill
- market-fibonacciSkill
- market-liquidity-sweepSkill
- market-macdSkill
- market-macroSkill
- market-moversSkill
- market-overviewSkill
- market-rsiSkill
- market-snapshotSkill
- market-squeezeSkill
- market-s-rSkill
- market-stateSkill
- market-trend-qualitySkill
- market-trendSkill
- market-valuationSkill
- market-volatilitySkill
- market-volumeSkill
- market-watchlistSkill
- portfolio-mgmtSkill
- position-watchdogSkill
- risk-engineSkill
- run-all-l2Skill
- run-all-l3Skill
- run-watchlistSkill
- strategy-accumulation-swingSkill
- strategy-breakout-confirmSkill
- strategy-exhaustion-fadeSkill
- strategy-fitness-heatmapSkill
- strategy-funding-carrySkill
- strategy-liquidity-sweepSkill
- strategy-mean-reversionSkill
- strategy-trend-followSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 22
Do not let a stored note override a fresh L3/risk verdict silently.
- Very specific: line 55
Default: skills/market-notes/data/notes.json.
- Very specific: line 114
After migration, validate no longer reports the legacy-meta error.
- Very specific: line 242
Pitfall — stale notes: When price breaches a note's invalidation level, remove the old note and add a fresh one.
≈ “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.
Files
market-notes
Per-pair free-form thesis notes with timestamps and optional expiration. The simplest possible context layer: a JSON file keyed by ticker, plus a CLI to manage it. Other skills (run-all-l2, run-all-l3, run-watchlist, position-watchdog) can pull active notes alongside their verdict so the agent brain sees "L3 says LONG conv 4 and there's a cycle-bottom-wait note for BTC" together.
Notes are personal context — the data file is gitignored and lives at skills/market-notes/data/notes.json. Shipped example: skills/market-notes/examples/notes.example.json.
When NOT to use
- For analysis or signals — this skill only stores and retrieves free-form context; it never computes a verdict. Use market-* / strategy-* skills for the actual read.
- To hold live prices, position sizes, or P&L — those belong in
position-watchdog/portfolio-mgmt. Notes go stale fast. - Do not let a stored note override a fresh L3/risk verdict silently; reconcile them together at decision time.
Quick Start
# Add a note
uv run skills/market-notes/scripts/run.py add BTCUSD "cycle bottom thesis: wait for $45-50k or 1w structure flip" --expires 30d
# List active notes (one pair or all)
uv run skills/market-notes/scripts/run.py list
uv run skills/market-notes/scripts/run.py list BTCUSD
# Include expired notes (audit)
uv run skills/market-notes/scripts/run.py list --all
# Remove a note by index
uv run skills/market-notes/scripts/run.py remove BTCUSD 0
# Drop expired notes from disk
uv run skills/market-notes/scripts/run.py prune
# Machine output
uv run skills/market-notes/scripts/run.py --json list BTCUSD
# Custom file location
uv run skills/market-notes/scripts/run.py --config /path/to/notes.json list
# Validate the storage file
uv run skills/market-notes/scripts/run.py validateData file
Default: skills/market-notes/data/notes.json. Override via:
--config PATHon every subcommandMARKET_SKILLS_NOTES_PATHenv var (absolute path)
Schema
{
"BTCUSD": [
{
"note": "cycle bottom thesis: wait for $45-50k or 1w structure flip",
"added": "2026-04-13T09:38:14+00:00",
"expires": "2026-07-12T09:38:14+00:00",
"updated": null,
"status": "thesis",
"type": "thesis",
"state": null,
"active_timeframe": null,
"dependencies": null,
"price_refs": null,
"invalidates_on": "weekly_close_above_EMA21",
"tags": []
}
]
}| Field | Required | Notes |
note | yes | Free-text thesis / observation / plan. |
added | yes | ISO timestamp, UTC. Set automatically on add. |
expires | no | ISO timestamp or null. Accepts shorthand on input: 14d, 2w, 1m, 6h. Pass --expires never to omit. |
updated | no | ISO timestamp of last edit. Not yet auto-managed — reserved for future edit command. |
status | recommended | Lifecycle state — any string accepted; RECOMMENDED vocabulary: thesis, open, setup, watchlist, hedge, starter, invalidated, post_mortem. |
type | recommended | Kind of note — any string accepted; RECOMMENDED vocabulary: thesis, setup, observation, plan, note. |
state | optional | Structural state of the underlying — any string accepted; RECOMMENDED vocabulary: coiled_range_intact, coiled_range_broken, trending_up, trending_down, range_bound, unknown. |
active_timeframe | optional | First-class timeframe the note applies to (e.g. "1d", "4h"). Distinguishes cross-TF theses like NEAR's 4h setup vs 1d macro. |
dependencies | optional | List of pair keys whose thesis this note rides on. Lets the scanner warn when a base thesis is invalidated. |
price_refs | optional | Typed price levels — canonical keys: stop, target, target_2, target_3, entry, invalidation_below, invalidation_above (must be numeric). Use price_refs.extra (free-form object) for per-timeframe ladders and non-price research metrics. |
invalidates_on | optional | Free-text condition (e.g. "weekly_close_above_EMA21", "structure_break_below_484"). |
tags | optional | Escape-hatch for ad-hoc markers that don't fit the triple ("wait", "re-scoped", etc.). |
Legacy meta field
Older notes may still carry a meta blob. New writes use the typed fields only. The CLI's migrate subcommand rewrites legacy entries in-place:
uv run skills/market-notes/scripts/run.py migrate # rewrite in place
uv run skills/market-notes/scripts/run.py migrate --dry-run # report onlyThe migration:
- Maps
meta.tagsintostatus/typevia a built-in tag dictionary (seeanalysis/notes_format._LEGACY_TAG_MAP). - Moves
meta.invalidates_on→invalidates_on. - Moves numeric
meta.stop/meta.target/meta.entry/meta.invalidation_below/meta.invalidation_above→price_refs.*. - Maps
1d_only/4h_only/1wk_onlytags →active_timeframe. - Drops unknown meta keys after warning (and keeps any leftover free-form tag in
tags).
After migration, validate no longer reports the legacy-meta error.
Expired notes remain on disk; list hides them, list --all shows them, prune removes them.
Library use (from other skills / scripts)
from analysis.notes import load_active, add_note
notes = load_active("BTCUSD") # -> list[dict], filtered to non-expired
entry = add_note("NEARUSD", "pullback-bounce trigger at $1.545", expires="14d", meta={"tags": ["setup"]})The skill's lib.py re-exports the same surface for compatibility with analysis.skill_loader.load_skill("market-notes").
Integration with other skills
| Skill | Flag | Behaviour |
run-all-l2 | --include-notes | Adds notes to per-ticker output. Off by default. |
run-all-l3 | --include-notes | Same. |
run-watchlist | --include-notes / --no-notes | Default ON for run-watchlist (it is the "morning brief" use case). |
The watchdog (position-watchdog) reads its own per-position config (skills/position-watchdog/data/watches.json) — different semantics (entry_price/position_size, stop/TP ladders). Keep them separate.
Cron integration
scripts/run.sh is a thin wrapper that activates uv and calls scripts/run.py. Cron jobs can reference it directly:
# Weekly prune of expired notes
0 6 * * 1 bash /path/to/market-skills/skills/market-notes/scripts/run.sh pruneMost use cases for notes are human-driven (add a thesis, list before acting). Cron only needs prune.
Workflows
Capture a thesis after a session:
uv run skills/market-notes/scripts/run.py add BTCUSD \
"Mayer approaching MEAN_REVERT; F&G extreme fear supports accumulation timing. Wait for weekly close > EMA21 as first sign of structure recovery, or capitulation washout below \$60k for real bottom entry." \
--expires 30d --meta '{"tags":["thesis","wait"],"invalidates_on":"weekly_close_above_EMA21"}'Survey context before a morning brief:
uv run skills/run-watchlist/scripts/run.py crypto_majors # auto-includes notesAudit expired notes before deleting:
uv run skills/market-notes/scripts/run.py list --all
uv run skills/market-notes/scripts/run.py pruneValidation
validate walks the file and reports findings as errors (hard failures) or warnings (advisory):
uv run skills/market-notes/scripts/run.py validate
# OK — 7 pair(s) with notes, 11 note(s) total, 3 warning(s)
uv run skills/market-notes/scripts/run.py validate --strict
# VALIDATION FAILED — 0 error(s), 3 warning(s)Warning vs error semantics
Errors (exit 1): structural problems — non-dict root, non-list pair value, missing/empty note,
missing added, non-string status/type/state, non-numeric canonical price_refs key,
non-dict price_refs.extra, legacy meta field.
Warnings (exit 0 unless --strict): unrecognised status/type/state string values
(not in the recommended vocabulary), unknown top-level price_refs keys (should migrate into
price_refs.extra).
--strict flag
Promotes warnings to errors for exit-code purposes. Use in CI to enforce vocabulary and
price_refs hygiene:
uv run skills/market-notes/scripts/run.py validate --strict # exit 1 if any warningsprice_refs.extra escape hatch
Per-timeframe ladders and non-price research metrics (holder concentration, funding totals,
RSI/vol percentiles) belong in price_refs.extra — a free-form JSON object that is accepted
without warnings:
{
"price_refs": {
"stop": 2.54,
"target": 3.12,
"extra": {
"entry_zone_low": 2.40,
"entry_zone_high": 2.50,
"rsi_4h": 42.3,
"funding_total_usd": 15000000
}
}
}Note content structure
Notes are a letter to future-us. Every note should answer:
- What's the thesis? Why hold, watch, or avoid this pair?
- Key structural levels — support, resistance, invalidation.
- What to watch for — catalysts or conditions that would change the thesis.
Do NOT include:
- Tier — that's in
market-watchlist. - Current prices or today's scores — go stale by next scan.
- Position details (qty, cost basis, P&L) — that's
position-watchdogandportfolio-mgmt. - Live macro values — describe the regime instead ("F&G extreme fear").
Good note patterns:
- Cycle thesis (BTC/ETH): "$45-50k target, invalidation at daily close below shakeout low"
- Open position (NEAR): "Setup type, structural stop, target, invalidation level"
- Hedge (PAXG): "Not a cycle play, buy dips to EMA50"
- Watchlist (SOL): "Cycle valuation zone, no trigger yet"
- Conviction (ZEC): "Coiled range framework with $X upside / $Y base"
Pitfall — stale notes: When price breaches a note's invalidation level, remove the old note and add a fresh one. remove uses 0-based index from list output — remove highest index first if clearing multiple.
Exit codes
0— success (no errors; warnings allowed unless--strict)1— fatal (bad--meta, file I/O error, validation error, or--strictwith warnings)2— invalid usage (missing args, unknown subcommand)
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
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.

