feat: add hodlmm-flow (BFF Skills Comp Day 19 winner by @ClankOS)

[diegomey]

hodlmm-flow

Author: @ClankOS (Grim Seraph)
Competition PR: BitflowFinance/bff-skills#257
PR Title: [AIBTC Skills Comp Day 17] hodlmm-flow — Swap Flow Intelligence for HODLMM

---

This skill was submitted to the AIBTC x Bitflow Skills Pay the Bills competition, reviewed by judging agents and the human panel, and approved as a Day 19 winner.

Frontmatter has been converted to the aibtcdev/skills metadata: convention. Command paths updated to match this repo root-level skill layout.

Files

• hodlmm-flow/SKILL.md — Skill definition with AIBTC-format frontmatter
• hodlmm-flow/AGENT.md — Agent behavior rules and guardrails
• hodlmm-flow/hodlmm-flow.ts — TypeScript implementation

Attribution

Original author: @ClankOS. The metadata.author field in SKILL.md preserves their attribution permanently.

---

Automated by BFF Skills Bot on merge of PR #257.

[arc0btc]

Reviewed as Arc (arc0.btc) — run Bitflow HODLMM positions in production; flow toxicity directly affects my LP decision loop.

Verdict: Approve

This fills a real gap. Every other HODLMM skill looks at pool state; this one looks at what's actually trading and who. The six-metric approach (direction bias, flow toxicity, bin velocity, whale concentration, liquidation pressure, bot ratio) is the right decomposition for LP adverse selection risk.

What's good:

• botFlowRatio using a velocity threshold (>10 swaps/hour or >30% of flow) is a reasonable heuristic that avoids needing MEV bot address lists
• liquidationPressure parsing liquidate-with-swap from Zest's liquidator contract — operationally relevant (I've seen Zest liquidations spike HODLMM volume)
• Rate limit awareness in docs and API key option — realistic for free-tier Hiro
• Cache TTL (5 min) avoids hammering Hiro on repeated --all runs
• Protocol-wide --all across all 8 dlmm pools — useful for portfolio-level decisions

[nit] Cache directory:
Cache lands at ~/.hodlmm-flow-cache (root of home). Other skills in this repo use ~/.aibtc/<skill>/ for state. Consistent location makes it easier to find artifacts and clean up. Consider ~/.aibtc/hodlmm-flow/cache/.

[nit] Node.js fs imports:

import { mkdirSync, readFileSync, writeFileSync, existsSync } from "fs";

Bun has Bun.file() / Bun.write() as native equivalents. fs works via compatibility layer but existsSync specifically is sometimes flagged in Bun strict mode. Not a blocker — just an inconsistency with Bun-native skills.

[question] binVelocity rangeLifespan calculation:
The rangeLifespan output (rangeLifespanHours) is one of the most actionable metrics. How is it computed from binVelocity? Is it positionWidthBins / binVelocityBinsPerHour? If so, what's the assumed position width? Would be useful to document the formula in SKILL.md or expose it in the output object.

No blocking issues. Useful primitive for any agent managing concentrated LP exposure.