coinhunter/SKILL.md

---
name: Coin Hunter
description: Hunt, triage, and compare speculative crypto coins — especially meme coins, 妖币-style runners, fake-hype pumps, and possible rug/scam setups. Use when a user wants to actively search for coins with breakout potential, rank a shortlist, ask whether a coin still has "妖性", or check whether a token looks late, fragile, manipulated, or likely to be a scam.
---

# Coin Hunter

## Overview

Use this skill to help a user search for and judge **high-volatility crypto setups** without pretending certainty.

Default buckets:
- **candidate runner** — has ingredients for further speculative expansion
- **watch-only / incomplete** — interesting, but not clean enough yet
- **late / overheated** — may still move, but entry quality is already poor
- **avoid / scam-risk** — liquidity, distribution, credibility, or structure is too weak

Frame the work as **speculative pattern recognition**, not investment advice.

## Core rule

Judge a coin by **attention + liquidity + distribution + timing** first. Narrative matters, but only when it can attract and hold money.

A technically weak project can still become a runner. A sophisticated-looking project can still be dead money.

## Supported request types

Use this skill for four common modes:
- **single-coin triage** — "look at this coin"
- **active discovery** — "find me coins that could become 妖币"
- **shortlist ranking** — "which of these 5 is most interesting"
- **scam / rug check** — "is this coin just fake hype"

If the request is broad, ask at most **one compact clarifying question**. Prefer:
- chain
- theme / narrative
- risk level
- whether the user accepts microcaps or wants only reasonably tradable names

If no preference is given, default to: **liquid speculative candidates, not ultra-illiquid microcaps**.

## Workflow

### 1. Identify the mode

Decide whether the user wants:
- discovery
- triage
- comparison
- scam-check

Then bias the workflow accordingly.

### 2. Choose the data path

Use **structured market data first** when available. Use web search to discover names and collect context, not as the only source of truth.

Preferred source order:
- **Bybit** for real-time-ish price, 24h turnover, and tradability on a major venue
- **DexScreener** for meme-coin pair discovery, DEX liquidity, and small-cap flow
- **Birdeye** for Solana token activity and confirmation
- **CoinGecko** for market-cap, rank, and metadata cross-check
- **web_search** for discovery, narratives, and scam-discussion context

Private user state must live outside the skill directory under `~/.coinhunter/`, not inside `skills/coinhunter/`.
Read `references/provider-playbook.md` when choosing which source to trust first.
Read `references/user-data-layout.md` when adding or updating personal accounts, positions, watchlists, or notes.
Use `scripts/market_probe.py` for deterministic provider lookups.
Use `scripts/init_user_state.py` to initialize the private user-data directory.

### 3. Discovery mode: build a candidate list

When the user wants active search rather than analysis of a known ticker, use public web sources to build a shortlist.

Look for evidence of:
- rising attention
- listing or venue expansion
- narrative/theme alignment
- market-cap and liquidity context
- breakout discussion or unusual participation

Useful search patterns include:
- `<theme> meme coin trending`
- `<chain> meme coin watchlist`
- `new meme coin listed`
- `<coin> market cap liquidity`
- `<coin> holders tokenomics`
- `<coin> rug risk`

Do not trust a single source or a single viral thread. Build the list first, then vet the names.

Read `references/search-workflow.md` for the detailed discovery flow.

### 4. Triage mode: score the coin on six dimensions

Assess each coin qualitatively across these dimensions.

#### A. Narrative fit
Ask:
- Is the story attached to a live theme?
- Is the idea easy to repeat in one sentence?
- Does the symbol / meme / framing have social spread potential?

Strong examples:
- obvious meme identity
- attached to a live chain or hot sector
- easy cultural hook

Weak examples:
- vague utility story
- no memorable angle
- cold or stale narrative

#### B. Attention acceleration
Ask:
- Is visibility rising now?
- Is the coin spreading beyond its original niche?
- Are larger accounts, aggregators, or trading communities starting to notice it?

Treat **acceleration** as more important than absolute popularity.

#### C. Liquidity quality
Ask:
- Can a normal user realistically enter and exit?
- Is volume believable relative to market cap and attention?
- Are spreads or venue quality obviously problematic?

If the user can probably buy but may not be able to exit cleanly, score this harshly.

#### D. Distribution / holder risk
Ask:
- Is ownership too concentrated?
- Are deployer or team wallets still dangerous?
- Is there an obvious unlock or dump overhang?

Ugly distribution does not automatically kill a trade, but it makes the setup fragile.

#### E. Timing / chart state
Ask:
- Is it emerging from a base or already vertical?
- Has participation expanded recently?
- Do pullbacks hold, or do they collapse?

Prefer:
- fresh breakout from longer consolidation
- early or mid-stage expansion
- resilient retraces

Be cautious when:
- it already went parabolic
- volume fades after the first mania burst
- price action is mostly wick-and-dump behavior

#### F. Rug / scam risk
Check for:
- fake partnerships or fake listing claims
- unverifiable team paired with aggressive promotion
- suspicious contract / public warning signals
- impossible tokenomics promises
- unverified liquidity-lock claims
- nothing but shill posts and no independent discussion

One severe scam signal can outweigh several bullish ones.
Read `references/scam-signals.md` when the user specifically asks about rugs, scams, fake hype, manipulation, or exit-liquidity bait.

### 5. Classify the result

Use these buckets:

#### Candidate runner
Use when most are true:
- narrative is live
- attention is accelerating
- liquidity is usable
- timing is not obviously exhausted
- no fatal scam / exit-risk signal is present

#### Watch-only / incomplete
Use when:
- something is interesting, but evidence is incomplete
- narrative is decent but timing is unclear
- liquidity or distribution is acceptable but not clean
- it deserves monitoring more than action

#### Late / overheated
Use when:
- the move is already widely noticed
- chart is extended or near blow-off behavior
- upside may remain, but entry quality is poor
- new buyers are at risk of becoming exit liquidity

#### Avoid / scam-risk
Use when:
- liquidity quality is bad
- exit risk is high
- holder concentration is dangerous
- legitimacy claims are weak or fake
- the setup feels more fabricated than organic

## Provider execution patterns

### Known tradable coin
If the user gives a Bybit-listed ticker or asks for current price/tradability:
1. run `python3 scripts/market_probe.py bybit-ticker <SYMBOL>`
2. optionally run `python3 scripts/market_probe.py bybit-klines <SYMBOL> --interval 60 --limit 10`
3. cross-check with CoinGecko when market-cap context matters

### Meme / 妖币 discovery
If the user wants runners, meme coins, or small-cap candidates:
1. use `web_search` to gather names
2. run `python3 scripts/market_probe.py dex-search <name>` for the strongest candidates
3. if Solana, run Birdeye when API access is configured
4. use CoinGecko to verify market-cap and ranking
5. only use Bybit if the coin is also on a major CEX

### Birdeye requirement
`market_probe.py birdeye-token <address>` requires `BIRDEYE_API_KEY` in the environment. If it is not configured, say so briefly and continue with DexScreener + CoinGecko + web search.

### Private portfolio state
If the user wants account, position, watchlist, or thesis tracking for coinhunter:
1. initialize `~/.coinhunter/` with `python3 scripts/init_user_state.py`
2. store private data only there
3. never place personal holdings inside the skill folder
4. treat the skill folder as logic only, and the user-data directory as state only

## Output style

Default to **compact, decision-first** answers.

For a single coin, include:
- **Verdict**
- **Radar score** — use the 0-12 checklist when evidence is sufficient
- **Why it could run** — 2-4 bullets
- **Why it could fail** — 2-4 bullets
- **What confirms strength**
- **What kills the thesis**
- **Risk line** — clearly state this is speculative, not investment advice

For multiple coins:
1. rank the shortlist
2. mark each as candidate runner / watch-only / late / avoid
3. state the main attraction and main flaw for each

Prefer bullets, short sections, and hard judgments over long essays.
Use `references/output-templates.md` when you want a reusable answer skeleton.

## Practical heuristics

### Often bullish for speculative expansion
- the meme or story is instantly repeatable
- attention is accelerating, not just present
- volume expands with the move
- pullbacks are bought
- exchange accessibility improves
- more mainstream crypto accounts begin to mention it

### Often a sign it is late
- everyone is already talking about it
- the chart has been vertical for days
- promotion is everywhere after the main move already happened
- price keeps spiking while structure gets messier

### Often a sign to avoid
- no trustworthy liquidity information
- suspicious ownership concentration
- clearly manufactured chart behavior
- incoherent or constantly shifting explanation
- obviously botted or repetitive social activity

## What not to do

- Do not describe a coin as safe.
- Do not confuse a polished whitepaper with breakout potential.
- Do not imply expected returns.
- Do not recommend leverage.
- Do not ignore slippage and exit risk.
- Do not push microcaps on beginners unless the user explicitly asks for extreme risk.

## Optional deeper pass

If the user wants more depth, expand in this order:
1. narrative and timing
2. liquidity and market structure
3. holder / tokenomics risk
4. why it could become a runner
5. why it probably will not
6. watch triggers

## References

Read `references/provider-playbook.md` for source selection and provider roles.
Read `references/user-data-layout.md` for private state layout under `~/.coinhunter/`.
Read `references/radar-checklist.md` for a quick scoring framework.
Read `references/search-workflow.md` for active discovery.
Read `references/output-templates.md` for compact response structure.
Read `references/scam-signals.md` for sharper scam / fake-hype judgment.