agentleFS
krzysukrzysu/market-skills/skills/market-notes/SKILL.md

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.

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
  1. Distinctive:

    Do not let a stored note override a fresh L3/risk verdict silently.

    line 22
  2. Very specific:

    Default: skills/market-notes/data/notes.json.

    line 55
  3. Very specific:

    After migration, validate no longer reports the legacy-meta error.

    line 114
  4. Very specific:

    Pitfall — stale notes: When price breaches a note's invalidation level, remove the old note and add a fresh one.

    line 242

≈ “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

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 validate

Data file

Default: skills/market-notes/data/notes.json. Override via:

  • --config PATH on every subcommand
  • MARKET_SKILLS_NOTES_PATH env 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": []
    }
  ]
}
FieldRequiredNotes
noteyesFree-text thesis / observation / plan.
addedyesISO timestamp, UTC. Set automatically on add.
expiresnoISO timestamp or null. Accepts shorthand on input: 14d, 2w, 1m, 6h. Pass --expires never to omit.
updatednoISO timestamp of last edit. Not yet auto-managed — reserved for future edit command.
statusrecommendedLifecycle state — any string accepted; RECOMMENDED vocabulary: thesis, open, setup, watchlist, hedge, starter, invalidated, post_mortem.
typerecommendedKind of note — any string accepted; RECOMMENDED vocabulary: thesis, setup, observation, plan, note.
stateoptionalStructural state of the underlying — any string accepted; RECOMMENDED vocabulary: coiled_range_intact, coiled_range_broken, trending_up, trending_down, range_bound, unknown.
active_timeframeoptionalFirst-class timeframe the note applies to (e.g. "1d", "4h"). Distinguishes cross-TF theses like NEAR's 4h setup vs 1d macro.
dependenciesoptionalList of pair keys whose thesis this note rides on. Lets the scanner warn when a base thesis is invalidated.
price_refsoptionalTyped 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_onoptionalFree-text condition (e.g. "weekly_close_above_EMA21", "structure_break_below_484").
tagsoptionalEscape-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 only

The migration:

  • Maps meta.tags into status / type via a built-in tag dictionary (see analysis/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_only tags → 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

SkillFlagBehaviour
run-all-l2--include-notesAdds notes to per-ticker output. Off by default.
run-all-l3--include-notesSame.
run-watchlist--include-notes / --no-notesDefault 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 prune

Most 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 notes

Audit expired notes before deleting:

uv run skills/market-notes/scripts/run.py list --all
uv run skills/market-notes/scripts/run.py prune

Validation

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 warnings

price_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-watchdog and portfolio-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 --strict with warnings)
  • 2 — invalid usage (missing args, unknown subcommand)

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.