nepse-trading-skill 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/AGENTS.md +50 -0
  2. package/README.md +229 -2
  3. package/install.sh +70 -0
  4. package/nepse_common/__init__.py +1 -0
  5. package/nepse_common/costs.py +107 -0
  6. package/nepse_common/data.py +277 -0
  7. package/nepse_common/indicators.py +80 -0
  8. package/nepse_common/report.py +37 -0
  9. package/package.json +40 -4
  10. package/skills/nepse-corporate-actions-calculator/SKILL.md +94 -0
  11. package/skills/nepse-corporate-actions-calculator/references/corporate_actions.md +81 -0
  12. package/skills/nepse-corporate-actions-calculator/scripts/corporate_actions.py +79 -0
  13. package/skills/nepse-cost-tax-calculator/SKILL.md +89 -0
  14. package/skills/nepse-cost-tax-calculator/references/costs_and_tax.md +102 -0
  15. package/skills/nepse-cost-tax-calculator/scripts/cost_calculator.py +59 -0
  16. package/skills/nepse-daily-analyst/SKILL.md +137 -0
  17. package/skills/nepse-daily-analyst/scripts/daily_analysis.py +244 -0
  18. package/skills/nepse-dividend-screener/SKILL.md +93 -0
  19. package/skills/nepse-dividend-screener/references/dividend_guide.md +83 -0
  20. package/skills/nepse-dividend-screener/scripts/dividend_screener.py +86 -0
  21. package/skills/nepse-fundamental-analyst/SKILL.md +105 -0
  22. package/skills/nepse-fundamental-analyst/references/sector_frameworks.md +102 -0
  23. package/skills/nepse-fundamental-analyst/references/valuation_guide.md +76 -0
  24. package/skills/nepse-fundamental-analyst/scripts/valuation.py +121 -0
  25. package/skills/nepse-ipo-analyzer/SKILL.md +96 -0
  26. package/skills/nepse-ipo-analyzer/references/ipo_guide.md +95 -0
  27. package/skills/nepse-ipo-analyzer/scripts/ipo_calendar.py +74 -0
  28. package/skills/nepse-liquidity-macro-monitor/SKILL.md +91 -0
  29. package/skills/nepse-liquidity-macro-monitor/references/liquidity_framework.md +91 -0
  30. package/skills/nepse-liquidity-macro-monitor/references/policy_calendar.md +70 -0
  31. package/skills/nepse-market-breadth-analyzer/SKILL.md +91 -0
  32. package/skills/nepse-market-breadth-analyzer/references/breadth_methodology.md +52 -0
  33. package/skills/nepse-market-breadth-analyzer/scripts/breadth.py +151 -0
  34. package/skills/nepse-market-regime-detector/SKILL.md +103 -0
  35. package/skills/nepse-market-regime-detector/references/nepse_cycle_history.md +52 -0
  36. package/skills/nepse-market-regime-detector/references/regime_methodology.md +65 -0
  37. package/skills/nepse-market-regime-detector/scripts/market_regime.py +130 -0
  38. package/skills/nepse-market-rules/SKILL.md +82 -0
  39. package/skills/nepse-market-rules/references/glossary.md +40 -0
  40. package/skills/nepse-market-rules/references/trading_rules.md +98 -0
  41. package/skills/nepse-market-rules/scripts/price_bands.py +101 -0
  42. package/skills/nepse-momentum-screener/SKILL.md +110 -0
  43. package/skills/nepse-momentum-screener/references/screen_methodology.md +78 -0
  44. package/skills/nepse-momentum-screener/scripts/screen_momentum.py +130 -0
  45. package/skills/nepse-news-sentiment-analyst/SKILL.md +97 -0
  46. package/skills/nepse-news-sentiment-analyst/references/news_framework.md +100 -0
  47. package/skills/nepse-news-sentiment-analyst/scripts/news_sentiment.py +157 -0
  48. package/skills/nepse-portfolio-manager/SKILL.md +98 -0
  49. package/skills/nepse-portfolio-manager/references/portfolio_framework.md +87 -0
  50. package/skills/nepse-portfolio-manager/scripts/portfolio_review.py +124 -0
  51. package/skills/nepse-position-sizer/SKILL.md +107 -0
  52. package/skills/nepse-position-sizer/references/sizing_for_nepse.md +90 -0
  53. package/skills/nepse-position-sizer/scripts/position_sizer.py +138 -0
  54. package/skills/nepse-pre-trade-gate/SKILL.md +105 -0
  55. package/skills/nepse-pre-trade-gate/references/gate_checks.md +80 -0
  56. package/skills/nepse-pre-trade-gate/scripts/pre_trade_gate.py +127 -0
  57. package/skills/nepse-sector-analyst/SKILL.md +87 -0
  58. package/skills/nepse-sector-analyst/references/nepse_sectors.md +78 -0
  59. package/skills/nepse-sector-analyst/scripts/sector_rotation.py +85 -0
  60. package/skills/nepse-technical-analyst/SKILL.md +96 -0
  61. package/skills/nepse-technical-analyst/assets/analysis_template.md +39 -0
  62. package/skills/nepse-technical-analyst/references/technical_framework.md +75 -0
  63. package/skills/nepse-technical-analyst/scripts/technical_snapshot.py +95 -0
  64. package/skills/nepse-trade-journal/SKILL.md +103 -0
  65. package/skills/nepse-trade-journal/references/review_guide.md +80 -0
  66. package/skills/nepse-trade-journal/scripts/journal.py +135 -0
  67. package/workflows/README.md +89 -0
package/AGENTS.md ADDED
@@ -0,0 +1,50 @@
1
+ # AGENTS.md
2
+
3
+ Agent skills for the Nepal Stock Exchange (NEPSE), for Claude Code, Codex, Gemini CLI and other Agent Skills clients. `CLAUDE.md` and `GEMINI.md` point here. See `README.md` for the catalogue and `workflows/README.md` for multi-skill workflows.
4
+
5
+ ## Rules for working in this repository
6
+
7
+ Scripts run from `~/.nepse-skills` (the link `./install.sh` creates). Run `./install.sh` once before using the skills, even inside this repository.
8
+
9
+ 0. **Every analysis starts with `nepse-daily-analyst`** (`~/.nepse-skills/skills/nepse-daily-analyst/scripts/daily_analysis.py --account-size <capital>`). An analysis must always include: market regime and breadth, news and sentiment, sector, the candidate's trigger status, pending events, size for the user's capital, and both timing sections (when to buy, when to sell). Ask for the capital if it is not known.
10
+
11
+ 1. **Never answer NEPSE rules, tax or commission from memory.** They changed several times in 2026. Read `~/.nepse-skills/skills/nepse-market-rules/references/trading_rules.md` and `~/.nepse-skills/skills/nepse-cost-tax-calculator/references/costs_and_tax.md`, and search the web for anything newer than their "verified" date when a decision depends on it.
12
+ 2. **Run the script, then interpret.** Numbers come from scripts; judgment comes from the references. Do not estimate what a script can compute.
13
+ 3. **Every analysis ends with what was not checked** and the disclaimer: unofficial data, educational, not investment advice.
14
+ 4. **Never place, simulate or promise an order.** The human trades in TMS.
15
+ 5. **Holdings and the journal are private.** They live in `state/` (git-ignored). Do not commit them or send them to any outside service.
16
+ 6. **Net numbers only.** Any profit, target or reward-to-risk shown to the user includes charges and capital gains tax.
17
+
18
+ ## Structure
19
+
20
+ ```
21
+ nepse_common/ data.py (all URLs and parsing), indicators.py, costs.py (all rates), report.py
22
+ skills/<name>/ SKILL.md (frontmatter name = folder name), references/, scripts/, assets/
23
+ tests/ offline pytest suite
24
+ ```
25
+
26
+ Scripts add the repository root to `sys.path` and import `nepse_common`. They use the standard library only.
27
+
28
+ ## Conventions for a new or changed skill
29
+
30
+ - `SKILL.md`: YAML frontmatter with `name` and a `description` that says when to trigger; then Overview, When to Use, Prerequisites, Workflow (numbered steps with commands), Output, Key Principles, Resources.
31
+ - Scripts: `argparse`, a pure function for the calculation (testable without network), `write_reports()` for output, `--output-dir` optional.
32
+ - Any calculation that touches money or a buy/sell decision gets a test in `tests/test_skills.py`.
33
+ - A rate or rule lives in one place: `nepse_common/costs.py` or `~/.nepse-skills/skills/nepse-market-rules/scripts/price_bands.py`. References cite the source and the date checked.
34
+ - Data access goes through `nepse_common/data.py` only.
35
+
36
+ ## Commands
37
+
38
+ ```bash
39
+ python3 -m pytest tests -q
40
+ ```
41
+
42
+ ```bash
43
+ python3 ~/.nepse-skills/skills/nepse-market-regime-detector/scripts/market_regime.py
44
+ ```
45
+
46
+ ## Known limits
47
+
48
+ - Data feeds are unofficial (Merolagani, ShareHub) and may break. Fix in `nepse_common/data.py`.
49
+ - No fundamentals feed, no floorsheet, no holiday calendar.
50
+ - The last daily bar is partial during market hours (11:00 to 15:00 Nepal time, Monday to Friday).
package/README.md CHANGED
@@ -1,3 +1,230 @@
1
- # Temporary Holding Version
1
+ # nepse-trading-skill: NEPSE trading skills for AI agents
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Eighteen ready-made skills that teach Claude Code, Codex, Gemini CLI and other AI coding agents how to analyse and trade the **Nepal Stock Exchange (NEPSE)**. Ask in plain words ("which share should I watch today?", "analyse NABIL", "how many kitta can I buy with Rs 30,000?") and the agent runs the right calculation on live NEPSE data, then explains the result.
4
+
5
+ ```bash
6
+ npx nepse-trading-skill
7
+ ```
8
+
9
+ One command installs all eighteen skills for every supported agent. Restart the agent and start asking.
10
+
11
+ ## What you get
12
+
13
+ - **A full daily analysis in one command**: market regime and exposure ceiling, market breadth, news and sentiment, sector rotation, a momentum screen, and for each candidate its trigger price, stop, target and size for your own capital, plus when to buy and when to sell.
14
+ - **NEPSE's real rules built in**: 15% daily price limit, index circuit breakers at 5% and 8%, T+2 settlement, lots of 10 kitta, no short selling, Monday to Friday trading since April 2026.
15
+ - **Real costs in every number**: broker commission slabs, SEBON fee, DP charge and capital gains tax (5% up to 365 days, 3.75% after), so every profit, target and break-even is net.
16
+ - **Risk control**: a position sizer that respects liquidity and concentration, and a pre-trade gate that returns PASS, WARN or BLOCK before you place an order in TMS.
17
+ - **Research helpers**: technical snapshot, valuation from quarterly reports (banks, hydropower, insurance), dividend and book-closure screen, bonus and right share calculator, IPO calendar, liquidity and NRB policy checklist, portfolio review with a tax clock, and a trade journal that scores your results in R.
18
+ - **No API key, no paid data.** Python 3.9+ standard library only, using public NEPSE data feeds (Merolagani, ShareHub) and news from ShareSansar, Kathmandu Post and OnlineKhabar.
19
+
20
+ ## Supported agents
21
+
22
+ | Agent | Where the skills are linked |
23
+ |---|---|
24
+ | Claude Code | `~/.claude/skills` |
25
+ | OpenAI Codex CLI | `~/.agents/skills` |
26
+ | Google Gemini CLI | `~/.agents/skills` |
27
+ | Other Agent Skills clients (Cursor, GitHub Copilot, OpenCode and others) | `~/.agents/skills` or `~/.claude/skills`, depending on the client |
28
+
29
+ Requires macOS or Linux and Python 3.9 or newer. `npx nepse-trading-skill` copies the package to `~/.nepse-skills` and links each skill into the folders above. Run it again to update. `npx nepse-trading-skill --uninstall` removes the links and keeps `~/.nepse-skills/state` (your journal and holdings).
30
+
31
+ ## Example questions
32
+
33
+ - "Run today's NEPSE analysis for Rs 30,000"
34
+ - "Is NEPSE in an uptrend? How much should I be invested?"
35
+ - "Which sectors are leading?"
36
+ - "Find breakout candidates in hydropower"
37
+ - "Analyse NTC. I bought 30 kitta at 943.90: when should I sell?"
38
+ - "I bought 1,000 at 450 and want to sell at 560 after 200 days. Net profit after tax?"
39
+ - "What will the price be after a 15% bonus?"
40
+ - "Which IPOs are open?"
41
+ - "Review my portfolio" (paste your MeroShare holdings)
42
+
43
+ > Educational analysis, not investment advice. Data is unofficial and can be delayed or wrong. Rules and tax rates were verified on 13 November 2026 and change often: confirm with your broker, NEPSE or SEBON before trading. The agent never places orders; you trade in TMS.
44
+
45
+ Modelled on [tradermonty/claude-trading-skills](https://github.com/tradermonty/claude-trading-skills) (same layout: `SKILL.md`, `references/`, `scripts/`, JSON and Markdown reports), rebuilt for NEPSE.
46
+
47
+ ## Skills
48
+
49
+ ### Start here
50
+
51
+ | Skill | What it does | Script |
52
+ |---|---|---|
53
+ | `nepse-daily-analyst` | One command: market, news sentiment, sectors, candidates sized for your capital, trigger status, when to buy and when to sell | `daily_analysis.py` |
54
+
55
+ ### Market rules and money
56
+
57
+ | Skill | What it does | Script |
58
+ |---|---|---|
59
+ | `nepse-market-rules` | Trading days and sessions, 15% limit, index breakers, order bands, settlement, lots, new-listing ranges; today's price bands | `price_bands.py` |
60
+ | `nepse-cost-tax-calculator` | Commission slabs, SEBON fee, DP charge, capital gains tax; buy cost, sell proceeds, round trip, break-even | `cost_calculator.py` |
61
+ | `nepse-corporate-actions-calculator` | Adjusted price, new quantity, tax and cost after bonus, right or cash dividend | `corporate_actions.py` |
62
+
63
+ ### Market direction
64
+
65
+ | Skill | What it does | Script |
66
+ |---|---|---|
67
+ | `nepse-market-regime-detector` | Index regime from trend, distribution days and follow-through days; exposure ceiling | `market_regime.py` |
68
+ | `nepse-market-breadth-analyzer` | 0-100 participation score from the live tape; share of stocks above their averages | `breadth.py` |
69
+ | `nepse-sector-analyst` | Ranks the 13 sub-indices by strength against NEPSE; rotation phase | `sector_rotation.py` |
70
+ | `nepse-news-sentiment-analyst` | Headlines and NEPSE notices scored, plus tape mood; market and per-stock news verdict | `news_sentiment.py` |
71
+ | `nepse-liquidity-macro-monitor` | Interest rates, system liquidity, NRB policy, share-loan rules; tailwind or headwind scorecard | research workflow, no script |
72
+
73
+ ### Stock selection
74
+
75
+ | Skill | What it does | Script |
76
+ |---|---|---|
77
+ | `nepse-momentum-screener` | Stage 2 leaders in tight bases: trend template, RS rank, tightness, volume dry-up, pivot | `screen_momentum.py` |
78
+ | `nepse-technical-analyst` | Trend stage, averages, RSI, MACD, ATR, levels; scenario-based analysis | `technical_snapshot.py` |
79
+ | `nepse-fundamental-analyst` | PE, PBV, ROE, earnings yield, Graham number; bank, hydropower, insurance checklists | `valuation.py` |
80
+ | `nepse-dividend-screener` | Cash yield on price, bonus habit, consistency, next book closure | `dividend_screener.py` |
81
+ | `nepse-ipo-analyzer` | Open and upcoming offerings; application, allotment, listing range, listing-day plan | `ipo_calendar.py` |
82
+
83
+ ### Risk and review
84
+
85
+ | Skill | What it does | Script |
86
+ |---|---|---|
87
+ | `nepse-position-sizer` | Kitta to buy from risk, stop, charges, liquidity and concentration limits; ATR and half-Kelly modes | `position_sizer.py` |
88
+ | `nepse-pre-trade-gate` | PASS / WARN / BLOCK on a planned buy: risk, size, reward, liquidity, chasing, regime, book closure | `pre_trade_gate.py` |
89
+ | `nepse-portfolio-manager` | Holdings CSV to net value, concentration, losers, tax clock | `portfolio_review.py` |
90
+ | `nepse-trade-journal` | Plan at entry, result at exit in R after charges and tax, statistics by setup | `journal.py` |
91
+
92
+ ## Quick start
93
+
94
+ Requirements: Python 3.9 or newer and the install step below. Nothing else to install for the scripts; `pytest` for the tests.
95
+
96
+ ```bash
97
+ python3 ~/.nepse-skills/skills/nepse-daily-analyst/scripts/daily_analysis.py --account-size 1000000 --output-dir reports/
98
+ ```
99
+
100
+ ```bash
101
+ python3 ~/.nepse-skills/skills/nepse-market-regime-detector/scripts/market_regime.py
102
+ ```
103
+
104
+ ```bash
105
+ python3 ~/.nepse-skills/skills/nepse-market-breadth-analyzer/scripts/breadth.py
106
+ ```
107
+
108
+ ```bash
109
+ python3 ~/.nepse-skills/skills/nepse-sector-analyst/scripts/sector_rotation.py
110
+ ```
111
+
112
+ ```bash
113
+ python3 ~/.nepse-skills/skills/nepse-momentum-screener/scripts/screen_momentum.py --top 100
114
+ ```
115
+
116
+ ```bash
117
+ python3 ~/.nepse-skills/skills/nepse-position-sizer/scripts/position_sizer.py --account-size 1000000 --symbol NABIL --atr-multiplier 2.5
118
+ ```
119
+
120
+ ```bash
121
+ python3 ~/.nepse-skills/skills/nepse-cost-tax-calculator/scripts/cost_calculator.py roundtrip --price 450 --sell-price 560 --qty 1000 --holding-days 200
122
+ ```
123
+
124
+ Every script prints Markdown and, with `--output-dir reports/`, saves `<name>_<timestamp>.json` and `.md`.
125
+
126
+ ## Install for Claude Code, Codex, Gemini CLI and others
127
+
128
+ The skills follow the open Agent Skills format (a folder with a `SKILL.md`). One script links them where each agent looks:
129
+
130
+ | Agent | Reads skills from |
131
+ |---|---|
132
+ | Claude Code | `~/.claude/skills` |
133
+ | Codex CLI | `~/.agents/skills` |
134
+ | Gemini CLI | `~/.agents/skills` |
135
+ | Other Agent Skills clients (Cursor, GitHub Copilot, OpenCode and others) | `~/.agents/skills` or `~/.claude/skills`, depending on the client |
136
+
137
+ From npm (no clone needed):
138
+
139
+ ```bash
140
+ npx nepse-trading-skill
141
+ ```
142
+
143
+ This copies the skills to `~/.nepse-skills` and links each one into `~/.claude/skills` and `~/.agents/skills`. Run it again to update; `npx nepse-trading-skill --uninstall` removes the links and keeps `~/.nepse-skills/state` (your journal and holdings).
144
+
145
+ From git:
146
+
147
+ ```bash
148
+ git clone https://gitlab.com/xetu/nepse.git ~/nepse-skills
149
+ ```
150
+
151
+ ```bash
152
+ ~/nepse-skills/install.sh
153
+ ```
154
+
155
+ The script links `~/.nepse-skills` to the clone and links each `nepse-*` skill folder into `~/.claude/skills` and `~/.agents/skills`. Restart the agent. Update with `git pull` in the clone; remove with `~/nepse-skills/install.sh --uninstall`.
156
+
157
+ Do not install single skills with an agent's own installer (for example `gemini skills install --path skills/nepse-...`): the scripts import `nepse_common/` from the repository root and every `SKILL.md` runs them from `~/.nepse-skills`, so a lone copied folder cannot run.
158
+
159
+ Inside this repository the skills also load as project skills (`.claude/skills` and `.agents/skills` link to `skills/`), and `AGENTS.md` (read by Codex; `CLAUDE.md` and `GEMINI.md` point to it) holds the working rules. Run `./install.sh` once here too: the commands use `~/.nepse-skills`.
160
+
161
+ ## Workflows
162
+
163
+ Defined in `workflows/README.md`:
164
+
165
+ | Workflow | When | Skills in order |
166
+ |---|---|---|
167
+ | Market regime daily | Each trading day, 10 minutes | regime → breadth → sector → news sentiment |
168
+ | Swing opportunity | When the regime allows buying | regime → sector → momentum screen → technical → fundamental check → stock news → position sizer → pre-trade gate → journal |
169
+ | Dividend income | Dividend season, monthly | liquidity → dividend screen → fundamental → corporate actions → cost and tax |
170
+ | IPO | When an offering opens or lists | IPO calendar → fundamental → rules (opening range) → cost and tax → journal |
171
+ | Portfolio review | Monthly | liquidity → regime → portfolio → technical on each holding → journal statistics |
172
+
173
+ ## Data sources
174
+
175
+ | Data | Source | Notes |
176
+ |---|---|---|
177
+ | Adjusted daily OHLCV for stocks, NEPSE and sub-indices | Merolagani chart handler | Since November 2010; adjusted for bonus and right |
178
+ | Live prices with sector, market summary, sub-indices | ShareHub live API | Updates through the session |
179
+ | Dividend history, public offerings, NEPSE company notices | ShareHub data API | |
180
+ | News headlines | ShareSansar latest, Kathmandu Post RSS, OnlineKhabar RSS | Latest 10 to 40 items each |
181
+ | Fundamentals | None free | Read from quarterly reports and pass to `valuation.py` |
182
+ | Floorsheet / broker-wise trades | None keyless found | Not covered |
183
+
184
+ Both feeds are unofficial and can change or stop without notice; `nepse_common/data.py` is the only file that knows their URLs. Responses are cached in `.cache/` (15 minutes for prices). The official `nepalstock.com.np` API needs a reverse-engineered token and is not used. For commercial use of NEPSE data, get a licence from NEPSE.
185
+
186
+ ## What was verified, and what was not
187
+
188
+ Verified against 2026 press reports on 13 November 2026:
189
+
190
+ - Trading Monday to Friday since 6 April 2026; 11:00 to 15:00; pre-open 10:30 to 10:45
191
+ - 15% daily stock limit, 5% pre-open band, 3% order band, index breakers at 5% (15-minute halt, first two hours) and 8% (closed for the day), since 20 April 2026
192
+ - Capital gains tax for individuals: 3.75% over 365 days, 5% otherwise, since 22 September 2026
193
+ - Commission slabs 0.36% to 0.24%, SEBON fee 0.015%, DP charge Rs 25
194
+ - New-listing opening range moved to a face-value basis in February 2026 (disputed)
195
+
196
+ Not confirmed from a primary source, marked in the references: the institutional capital gains tax rate (10% used), whether the 10-kitta lot floor still applies at every broker, the exact reference price of the 15% limit, bonus-share cost basis for 2026, current NRB share-loan limits after the 2083/84 monetary policy, and whether intraday trading or T+1 has started. Sector descriptions, valuation bands and regulatory thresholds in the fundamental references are general knowledge and are flagged as such.
197
+
198
+ When a rule changes, update `~/.nepse-skills/skills/nepse-market-rules/references/trading_rules.md`, the constants in `nepse_common/costs.py` and `~/.nepse-skills/skills/nepse-market-rules/scripts/price_bands.py`, then run the tests.
199
+
200
+ ## Layout
201
+
202
+ ```
203
+ nepse_common/ shared code: data.py, indicators.py, costs.py, report.py
204
+ skills/<name>/ SKILL.md, references/, scripts/ (and assets/ where used)
205
+ workflows/ multi-skill workflows
206
+ tests/ offline tests for every money and decision calculation
207
+ .claude/skills link to skills/ (Claude Code project skills)
208
+ .agents/skills link to skills/ (Codex, Gemini CLI project skills)
209
+ install.sh links the skills into ~/.claude/skills and ~/.agents/skills
210
+ AGENTS.md working rules; CLAUDE.md and GEMINI.md point to it
211
+ reports/ state/ .cache/ created at run time, git-ignored
212
+ ```
213
+
214
+ ## Tests
215
+
216
+ ```bash
217
+ python3 -m pytest tests -q
218
+ ```
219
+
220
+ 34 offline tests cover commission slabs, tax, break-even, indicators, position sizing, price bands, corporate actions, regime classification, the trend template, breadth scoring, dividend summaries, offering grouping, valuation flags, portfolio review, the journal, the gate, news scoring and parsing, and the daily analyst's trigger status and trade plan.
221
+
222
+ ## Differences from the upstream US repository
223
+
224
+ | Upstream | Here | Why |
225
+ |---|---|---|
226
+ | 74 skills | 18 | Options, futures, COT, short-selling, earnings-gap, 13F and US macro skills have no NEPSE counterpart; several upstream skills are merged (three market-direction skills into one regime detector; journal, post-mortem and coach into one journal) |
227
+ | FMP / FINVIZ / Alpaca APIs | Keyless public feeds | No NEPSE data vendor or broker API for retail |
228
+ | Fractional shares, bracket orders | Whole kitta, limit orders, manual stops | TMS has no stop or bracket orders |
229
+ | Earnings calendar | Dividend and book-closure dates | Quarterly results have no reliable free calendar feed |
230
+ | US tax lots | NEPSE charges and capital gains tax in every result | Costs are about 0.7% a round trip plus tax on the gain |
package/install.sh ADDED
@@ -0,0 +1,70 @@
1
+ #!/bin/sh
2
+ # Install the NEPSE skills for Claude Code, Codex, Gemini CLI and any agent that reads
3
+ # the Agent Skills folders (~/.claude/skills or ~/.agents/skills).
4
+ #
5
+ # ./install.sh install (links ~/.nepse-skills to this folder, links each skill)
6
+ # ./install.sh --uninstall remove the links
7
+ # npx nepse-trading-skill same, from npm: copies the package to ~/.nepse-skills first,
8
+ # because npm's own folder can be cleaned away
9
+ #
10
+ # The skills' scripts import nepse_common from the repository root, so each skill is linked,
11
+ # never copied on its own; every SKILL.md runs its scripts from ~/.nepse-skills.
12
+ set -eu
13
+
14
+ HOME_LINK="$HOME/.nepse-skills"
15
+ SELF=$0
16
+ while [ -L "$SELF" ]; do # npm runs this through a link in its bin folder
17
+ LINK=$(readlink "$SELF")
18
+ case $LINK in /*) SELF=$LINK ;; *) SELF=$(dirname "$SELF")/$LINK ;; esac
19
+ done
20
+ SRC=$(cd "$(dirname "$SELF")" && pwd -P)
21
+ case $SRC in */node_modules/*) FROM_NPM=1 ;; *) FROM_NPM=0 ;; esac
22
+ TARGETS="$HOME/.claude/skills $HOME/.agents/skills" # Claude Code; Codex, Gemini CLI and other Agent Skills clients
23
+
24
+ if [ "${1:-}" = "--uninstall" ]; then
25
+ for t in $TARGETS; do
26
+ for s in "$SRC"/skills/nepse-*/; do
27
+ dest="$t/$(basename "$s")"
28
+ [ -L "$dest" ] && rm "$dest" && echo "removed $dest"
29
+ done
30
+ done
31
+ if [ -L "$HOME_LINK" ]; then
32
+ rm "$HOME_LINK" && echo "removed $HOME_LINK"
33
+ elif [ -d "$HOME_LINK" ]; then
34
+ echo "kept $HOME_LINK: it holds your journal and holdings in state/; delete it yourself if you want"
35
+ fi
36
+ exit 0
37
+ fi
38
+
39
+ command -v python3 >/dev/null 2>&1 || { echo "python3 (3.9 or newer) is required" >&2; exit 1; }
40
+ python3 -c 'import sys; sys.exit(sys.version_info < (3, 9))' || { echo "python3 3.9 or newer is required" >&2; exit 1; }
41
+
42
+ if [ "$FROM_NPM" = 1 ]; then
43
+ [ -L "$HOME_LINK" ] && rm "$HOME_LINK" # an earlier git install: replace the link with a copy
44
+ mkdir -p "$HOME_LINK"
45
+ rm -rf "$HOME_LINK/skills" "$HOME_LINK/nepse_common" "$HOME_LINK/workflows" # state/ and .cache/ stay
46
+ cp -R "$SRC/." "$HOME_LINK/"
47
+ elif [ "$SRC" != "$HOME_LINK" ]; then
48
+ if [ -e "$HOME_LINK" ] && [ ! -L "$HOME_LINK" ]; then
49
+ echo "$HOME_LINK exists and is not a link; move it away first" >&2
50
+ exit 1
51
+ fi
52
+ ln -sfn "$SRC" "$HOME_LINK"
53
+ fi
54
+
55
+ count=0
56
+ for t in $TARGETS; do
57
+ mkdir -p "$t"
58
+ for s in "$HOME_LINK"/skills/nepse-*/; do
59
+ name=$(basename "$s")
60
+ dest="$t/$name"
61
+ if [ -e "$dest" ] && [ ! -L "$dest" ]; then
62
+ echo "skipped $dest: a folder with that name already exists" >&2
63
+ continue
64
+ fi
65
+ ln -sfn "$HOME_LINK/skills/$name" "$dest"
66
+ count=$((count + 1))
67
+ done
68
+ done
69
+ echo "Linked $count skill folders into: $TARGETS"
70
+ echo "Scripts run from $HOME_LINK. Restart your agent to load the skills."
@@ -0,0 +1 @@
1
+ """Shared code for the NEPSE trading skills: data, indicators, costs, reports."""
@@ -0,0 +1,107 @@
1
+ """NEPSE transaction costs and capital gains tax.
2
+
3
+ Rates as researched on 2026-11-13 (see skills/nepse-cost-tax-calculator/references).
4
+ They change by SEBON / Finance Ministry decision: check before relying on them.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ # (upper bound of trade value in Rs, commission rate). The slab rate applies to the whole amount.
10
+ COMMISSION_SLABS = [
11
+ (50_000, 0.0036),
12
+ (500_000, 0.0033),
13
+ (2_000_000, 0.0031),
14
+ (10_000_000, 0.0027),
15
+ (float("inf"), 0.0024),
16
+ ]
17
+ MIN_COMMISSION = 10.0
18
+ SEBON_FEE_RATE = 0.00015 # 0.015% of trade value, both sides
19
+ DP_CHARGE = 25.0 # per scrip per transaction day, both sides
20
+ # Resident individual, listed shares, gazetted 2026-09-22.
21
+ CGT_LONG = 0.0375 # held more than 365 days
22
+ CGT_SHORT = 0.05 # held 365 days or less
23
+ CGT_INSTITUTION = 0.10 # not confirmed from a primary source
24
+ LONG_TERM_DAYS = 365
25
+ TICK = 0.1
26
+
27
+
28
+ def commission(amount: float) -> float:
29
+ for limit, rate in COMMISSION_SLABS:
30
+ if amount <= limit:
31
+ return max(round(amount * rate, 2), MIN_COMMISSION)
32
+ raise ValueError("unreachable")
33
+
34
+
35
+ def cgt_rate(holding_days: int, investor: str = "individual") -> float:
36
+ if investor == "institution":
37
+ return CGT_INSTITUTION
38
+ return CGT_LONG if holding_days > LONG_TERM_DAYS else CGT_SHORT
39
+
40
+
41
+ def buy_cost(price: float, qty: int) -> dict:
42
+ """Total payable for a buy, with the per-share cost (WACC of this lot)."""
43
+ if price <= 0 or qty <= 0:
44
+ raise ValueError("price and qty must be positive")
45
+ amount = price * qty
46
+ comm, sebon = commission(amount), round(amount * SEBON_FEE_RATE, 2)
47
+ total = amount + comm + sebon + DP_CHARGE
48
+ return {
49
+ "amount": round(amount, 2),
50
+ "commission": comm,
51
+ "sebon_fee": sebon,
52
+ "dp_charge": DP_CHARGE,
53
+ "total_payable": round(total, 2),
54
+ "cost_per_share": round(total / qty, 4),
55
+ }
56
+
57
+
58
+ def sell_proceeds(
59
+ price: float,
60
+ qty: int,
61
+ cost_per_share: float,
62
+ holding_days: int = 0,
63
+ investor: str = "individual",
64
+ cgt_override: float | None = None,
65
+ ) -> dict:
66
+ """Net receivable for a sell. cost_per_share is the all-in buy cost (WACC)."""
67
+ if price <= 0 or qty <= 0 or cost_per_share < 0:
68
+ raise ValueError("price and qty must be positive, cost_per_share not negative")
69
+ amount = price * qty
70
+ comm, sebon = commission(amount), round(amount * SEBON_FEE_RATE, 2)
71
+ charges = comm + sebon + DP_CHARGE
72
+ gain = amount - charges - cost_per_share * qty
73
+ rate = cgt_override if cgt_override is not None else cgt_rate(holding_days, investor)
74
+ tax = round(max(gain, 0) * rate, 2) # no tax on a loss; losses are not netted across scrips
75
+ net = amount - charges - tax
76
+ return {
77
+ "amount": round(amount, 2),
78
+ "commission": comm,
79
+ "sebon_fee": sebon,
80
+ "dp_charge": DP_CHARGE,
81
+ "taxable_gain": round(gain, 2),
82
+ "cgt_rate_pct": round(rate * 100, 3),
83
+ "cgt": tax,
84
+ "net_receivable": round(net, 2),
85
+ "net_profit": round(net - cost_per_share * qty, 2),
86
+ }
87
+
88
+
89
+ def round_trip(buy_price: float, sell_price: float, qty: int, holding_days: int = 0, investor: str = "individual") -> dict:
90
+ buy = buy_cost(buy_price, qty)
91
+ sell = sell_proceeds(sell_price, qty, buy["cost_per_share"], holding_days, investor)
92
+ return {
93
+ "buy": buy,
94
+ "sell": sell,
95
+ "net_profit": sell["net_profit"],
96
+ "net_return_pct": round(sell["net_profit"] / buy["total_payable"] * 100, 3),
97
+ "gross_return_pct": round((sell_price / buy_price - 1) * 100, 3),
98
+ }
99
+
100
+
101
+ def breakeven_price(buy_price: float, qty: int) -> float:
102
+ """Lowest sell price (to the Rs 0.10 tick) at which net profit is not negative."""
103
+ cost = buy_cost(buy_price, qty)["cost_per_share"]
104
+ price = round(buy_price, 1)
105
+ while sell_proceeds(price, qty, cost)["net_profit"] < 0:
106
+ price = round(price + TICK, 1)
107
+ return price