Guide · Agent skill
How to use the Chan Theory (chanlun) agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The chanlun skill teaches an AI agent to read price charts using Chan Theory (缠论), a Chinese technical analysis method based only on price structure. It identifies candlestick fractals, strokes (bi), and pivot zones (zhongshu), then labels possible first, second and third buy or sell points. This guide shows you how to install it, ask for analysis in plain language, run the example engine, and judge what the output can and cannot tell you.
Chan Theory Pattern RecognitionHKUDS/Vibe-Trading · MIT Download the skill Quick start
- 1Get the ZIP. Download the chanlun skill ZIP from this page.
- 2Place the skill. Unzip it into ~/.claude/skills/ for all projects, or into .claude/skills/ inside one project. Alternatively, upload the ZIP in the Claude apps under Settings, Capabilities, Skills.
- 3Install Python dependencies. Run pip install czsc requests pandas in the Python environment you will use.
- 4Prepare your OHLCV data. Build a time-ordered list of bars with open, high, low, close and volume values, because the skill does not fetch market data itself.
- 5Ask for an analysis. Describe your data and the question, using terms such as strokes, pivot zones, or 一买, so the agent loads the right skill.
- 6Check the stroke structure. Ask the agent to list the completed strokes and the pivot zone, and confirm they match your chart.
- 7Test before trusting. Backtest any labelled signal with your own risk rules before using it for real decisions.
What the skill makes the agent do
The skill follows a fixed pipeline: raw candlesticks, then inclusion handling, then fractal detection, stroke detection, pivot zone construction, and finally buy/sell point judgement. The skill's documentation describes fractals (FX) as top or bottom patterns where the middle candle has the highest or lowest high or low, strokes (BI) as the price move between adjacent top and bottom fractals, and pivot zones (ZS) as overlapping price ranges formed by at least three strokes.
It labels buy and sell points in three classes: 一买/一卖 (first buy/sell at a trend reversal), 二买/二卖 (second buy/sell as a confirmation after a pullback), and 三买/三卖 (third buy/sell after a pivot breaks out and the pullback stays above or below it). It uses the czsc Python library for the detection, and it can also label stroke patterns of 3, 5, 7, 9 and 11 strokes.
Install the chanlun skill
Option A: download the chanlun ZIP from this page and unzip it into your user skills folder, ~/.claude/skills/, or into a project-specific folder, .claude/skills/ inside your project. Option B: in the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP.
The skill is code-driven, so you also need Python and the czsc library installed. The skill's own install line is shown below. Install it in the same Python environment you will use to run scripts.
- Confirm the folder is named chanlun and contains SKILL.md at its top level after unzipping.
- Keep the references folder and example_signal_engine.py alongside SKILL.md, since the skill links to them.
pip install czsc requests pandasTrigger the skill with a natural request
You do not need special syntax. The skill's description covers Chan Theory, 缠论, K-line fractals, strokes, pivot zones and the buy/sell point names, so your request should use that vocabulary. Name the market or data you have and the outcome you want.
Good requests are specific about the data and the question. For example: analyse my daily OHLCV CSV for BTC-USDT and list the strokes and the latest pivot zone; check whether the last bottom fractal is a 一买 candidate; label the 3-stroke and 5-stroke patterns in this series. Mention that you can supply the data yourself, because the skill does not fetch market data.
Understand the example code and signal output
The core workflow builds a list of RawBar objects in time order, then passes them to CZSC, which detects fractals, strokes and pivot zones. You then read the completed strokes and the unfinished bars. The snippet below is taken from the skill's quick start; the bar values are placeholders.
The signal engine outputs 1 for long, -1 for short and 0 for wait. Long conditions are a first buy signal, a 3-stroke upward divergence, or a 5-stroke first-buy-like pattern. Short conditions are the mirror cases. Near the lower edge of a pivot zone the skill treats long setups as more favourable, and near the upper edge short setups.
The skill's signal string format is {freq}_D{di}B_BUY1 for buys and {freq}_D{di}B_SELL1 for sells. A value beginning 一买_ means a buy signal fired, 一卖_ means a sell signal, and 其他_任意_任意_0 means nothing fired.
- RawBar fields: symbol, id (starting at 0), dt, freq, open, close, high, low, vol, amount.
- Supported frequencies include 1, 5, 15, 30 and 60 minutes, daily, weekly and monthly.
- The engine is a simple illustration; treat its output as a labelled pattern, not a trade instruction.
from czsc import CZSC, RawBar, Freq
from datetime import datetime
bars = [
RawBar(symbol="BTC-USDT", id=0, dt=datetime(2026,1,1),
freq=Freq.D, open=70000, close=71000,
high=72000, low=69000, vol=1000, amount=71000000),
# ... more bars in time order
]
c = CZSC(bars)
print(c.bi_list) # completed strokes
print(c.bars_ubi) # bars in the unfinished strokeWhat it needs and safety notes
The skill requires Python, the czsc library, requests and pandas, plus market OHLCV data that you supply. It runs scripts (the example signal engine is a Python file), so review example_signal_engine.py before running it, as you would with any script an agent executes. The skill's metadata states that it does not use the network, so it does not fetch prices on its own; any data you feed in is your responsibility.
Signals are pattern labels from a discretionary theory. They are not guaranteed outcomes, and acting on them can lose money. Backtest any rule and set risk controls before using it for real decisions. The reference notes also describe stop-loss placement around the first buy low for second buys, but that is guidance from the notes, not a tested strategy.
- Do not feed the skill data you have not checked for gaps, ordering, or errors; the detection depends on time-ordered bars.
- Use the skill for analysis and learning first, and keep trading decisions separate from its labels.
Tips for better results
Ask for the reference concept first if you are learning. The skill ships with notes on fractals, strokes, pivot zones and each buy/sell class, written in Chinese, so you can ask the agent to explain a term with the matching note. Ask the agent to show the stroke list before the signal list, so you can check that the structure matches what you see on the chart.
Compare the same pattern across timeframes. The skill supports multi-timeframe analysis, and a pivot zone that appears on a higher frequency is often easier to judge than one on a short frequency.
- Use time-ordered data with consistent frequency for each run.
- Ask for stroke counts (3, 5, 7, 9, 11) explicitly when you want pattern classification.
- Keep a record of each labelled point and what happened next, which is the simplest way to test whether the labels help you.
What people use it for
- Labelling candidate first, second and third buy or sell points on a historical daily price series for study.
- Listing completed strokes and the latest pivot zone for a chart you already analyse with Chan Theory.
- Building a starting point for a trading signal pipeline with czsc, then adding your own data loading and backtesting.
- Working through Chinese reference notes on fractals, strokes and pivot zones while learning the method.
Frequently asked questions
Is the chanlun skill free to use?
The skill is published under the MIT licence, which is stated on this page. The czsc library and any data source you use have their own terms, so check those separately.
What do I need to install before using the chanlun skill?
You need Python, the czsc library, requests and pandas, plus market OHLCV data supplied by you. The skill is code-driven, so the agent cannot analyse prices without these running.
Where do I put the chanlun skill folder?
Unzip the downloaded ZIP into ~/.claude/skills/ to make it available everywhere, or into .claude/skills/ inside a project to limit it to that project. In the Claude apps, you can instead upload the ZIP under Settings, Capabilities, Skills.
Does the chanlun skill predict prices or give profitable signals?
No. It labels patterns from Chan Theory, which is a discretionary method, and the labels are not guaranteed outcomes. The example engine is a simple illustration, so backtest and set risk controls before acting on any signal.
How is chanlun different from other technical analysis skills or indicators?
Chanlun is based only on price structure: fractals, strokes and pivot zones, with buy and sell points named by class. Many other indicators use formulas on price or volume alone, so the output here is structural labels rather than a single numeric value. Compare the output against your own method before choosing.
Why does the agent fail to detect any strokes or signals?
The most common causes are missing dependencies, bars not in time order, or too little data to form a pivot zone of at least three strokes. Check that czsc imports correctly, that your RawBar list is sorted by time, and that you supplied enough bars.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you already follow Chan Theory and want automated structural labels, or you are a developer or student building a czsc-based starting point that you can test yourself. Pick something else if you need a ready-made trading product, want guaranteed or profit-focused signals, or do not want to install Python and the czsc library.
Download the skill