TOOLS OF THE TRADE — SKILL STRUCTURE & TOKEN ECONOMICSট্রেডের সরঞ্জাম — স্কিল স্ট্রাকচার ও টোকেন ইকোনমিক্স
RIFAT · SENIOR ENGINEER, NOP-STATION"My skill just hit 800 lines. And I realized: every single session now loads all of that — whether the skill is even used or not.""আমার স্কিল এখন ৮০০ লাইনে পৌঁছে গেছে। আর বুঝলাম — প্রতিটি সেশনে সব লোড হচ্ছে, স্কিলটা ব্যবহার হোক বা না হোক।"
Checklists, templates, API tables — all inlinedচেকলিস্ট, টেমপ্লেট, API টেবিল — সব ইনলাইন
HABIB · BACKEND ENGINEER"Every morning my system prompt loads 800 lines of that skill body — even on sessions where I never invoke it. That's token waste, every single time.""প্রতিদিন সকালে আমার সিস্টেম প্রম্পটে ৮০০ লাইনের সেই স্কিল বডি লোড হচ্ছে — এমনকি যেসব সেশনে কখনো ইনভোক করি না সেগুলোতেও। প্রতিবার টোকেন নষ্ট।"
The root issue: no discipline around when content is loaded. Everything is always loaded. That's the anti-pattern.মূল সমস্যা: কনটেন্ট কখন লোড হবে তা নিয়ে কোনো নিয়মকানুন নেই। সবকিছু সবসময় লোড হয়। এটাই অ্যান্টি-প্যাটার্ন।
THE PRINCIPLEনীতি
Progressive Disclosureপ্রগ্রেসিভ ডিসক্লোজার
Load the least possible up front. Reveal more only when needed.শুরুতে যত কম সম্ভব লোড করো। প্রয়োজনে আরও দেখাও।
This is a UX principle borrowed for AI skill design: don't show the whole manual the moment someone walks in the door. Give them the handle; they'll ask for the manual when they need it.এটি UI/UX থেকে ধার করা নীতি, এখন AI স্কিল ডিজাইনে প্রয়োগ: কেউ দরজায় ঢোকামাত্র পুরো ম্যানুয়াল দেখিয়ো না। হ্যান্ডেল দাও; প্রয়োজনে তারা ম্যানুয়াল চাইবে।
name, description, trigger conditions — a few lines at most. Every session pays this cost.name, description, trigger conditions — সর্বোচ্চ কয়েক লাইন। প্রতিটি সেশনেই এই খরচ দিতে হয়।
T2
SKILL.md body — loaded ON INVOKESKILL.md বডি — ইনভোকে লোড
Instructions, examples, workflow steps. Only paid when the skill is actually called.নির্দেশনা, উদাহরণ, ওয়ার্কফ্লো স্টেপ। স্কিল আসলে ডাকা হলে তবেই খরচ।
T3
Reference files & scripts — loaded ON DEMANDরেফারেন্স ফাইল ও স্ক্রিপ্ট — চাহিদায় লোড
Large checklists, API tables, templates, bundled scripts. Zero token cost unless actually read or run.বড় চেকলিস্ট, API টেবিল, টেমপ্লেট, বান্ডেলড স্ক্রিপ্ট। না পড়া/না চালানো পর্যন্ত শূন্য টোকেন খরচ।
Design rule: keep T1 as tiny as possible — those tokens are paid on every single session regardless of whether the skill fires.ডিজাইন নিয়ম: T1 যতটা সম্ভব ছোট রাখো — এই টোকেনগুলো প্রতিটি সেশনে দিতে হয়, স্কিল চালু হোক বা না হোক।
TOKEN ECONOMICSটোকেন ইকোনমিক্স
Why Tier Design Mattersকেন স্তর ডিজাইন গুরুত্বপূর্ণ
FAT SKILL (BEFORE)মোটা স্কিল (আগে)
T1 (always)T1 (সবসময়)
~6 000 tok/session~৬০০০ tok/সেশন
800-line body inlined into T1 — always loaded, regardless of use.৮০০ লাইনের বডি T1-এ ইনলাইন — সবসময় লোড, ব্যবহার হোক না হোক।
LEAN SKILL (AFTER)পাতলা স্কিল (পরে)
T1 (always)T1 (সবসময়)
~180 tok~১৮০ tok
T2 (invoke)T2 (ইনভোক)
~800 tok~৮০০ tok
T3 (demand)T3 (চাহিদায়)
0০
Router body stays short; heavy refs only load when actually needed.রাউটার বডি ছোট থাকে; ভারী রেফ শুধু দরকারে লোড হয়।
A team with 10 engineers running 3 sessions each = 30 contexts per day. Fat T1 vs lean T1 is a 33× token-cost difference on always-loaded tokens alone.১০ ইঞ্জিনিয়ারের টিম, প্রতিজন ৩টি সেশন = দৈনিক ৩০টি কনটেক্সট। মোটা T1 বনাম পাতলা T1 — শুধু always-loaded টোকেনে ৩৩× খরচের পার্থক্য।
TIER 3 — PART Aস্তর ৩ — অংশ A
Bundled Scripts — Keep Logic Out of the Bodyবান্ডেলড স্ক্রিপ্ট — লজিক বডিতে রাখো না
A skill can ship a Python or Bash script alongside its SKILL.md. Instead of inlining 150 lines of validation logic, the body simply says: "run scripts/validate.py".একটি স্কিল তার SKILL.md-এর পাশে Python বা Bash স্ক্রিপ্ট পাঠাতে পারে। ১৫০ লাইনের ভ্যালিডেশন লজিক ইনলাইন করার বদলে বডি শুধু বলে: "scripts/validate.py চালাও"।
AGENT"I see the SKILL.md says: run scripts/run.py with the collected params. Let me execute that now." ← The script body never sits in the context window unless the agent reads the file."দেখছি SKILL.md বলছে: কালেক্ট করা প্যারাম দিয়ে scripts/run.py চালাও। এখন এটি চালাই।" ← স্ক্রিপ্টের বডি কনটেক্সট উইন্ডোতে থাকে না যতক্ষণ না এজেন্ট ফাইলটি পড়ে।
The script executes when needed — the body only carries the instruction to run it. No wasted tokens on code that sits dormant.স্ক্রিপ্ট দরকার হলে চলে — বডিতে শুধু সেটি চালানোর নির্দেশ থাকে। নিষ্ক্রিয় কোডে কোনো টোকেন নষ্ট হয় না।
TIER 3 — PART Bস্তর ৩ — অংশ B
Reference Files — Move Heavy Docs Outরেফারেন্স ফাইল — ভারী ডকস বাইরে সরাও
Large checklists, API field tables, big templates — move them into references/. SKILL.md just points to them with a single line.বড় চেকলিস্ট, API ফিল্ড টেবিল, বড় টেমপ্লেট — references/-এ সরাও। SKILL.md শুধু একটি লাইনে তাদের দিকে নির্দেশ করে।
# In SKILL.md — pointing to a reference, NOT inlining it## When you need the full API field list:
Read references/api-fields.md
## When you need the release checklist:
Read references/release-checklist.md
# The files are NOT in the context window until the agent reads them.
HABIB"So the reference file costs zero tokens until I actually need it. If that session never touches the API field list — I paid nothing for it.""তাহলে রেফারেন্স ফাইল শূন্য টোকেন খরচ করে যতক্ষণ আমার আসলে দরকার না হয়। যে সেশনে API ফিল্ড লিস্ট দরকারই হয় না — সেখানে কিছুই দিতে হয়নি।"
FOLDER STRUCTUREফোল্ডার কাঠামো
The Three-Tier Layoutতিন-স্তরের কাঠামো
.claude/skills/└── my-skill/├── SKILL.md← T1 frontmatter + T2 router body├── scripts/│ ├── run.py← T3 bundled logic (never auto-loaded)│ └── validate.sh← T3 bash helper└── references/├── api-fields.md← T3 heavy reference (read on demand)├── checklist.md← T3 release checklist└── template.md← T3 output template
SKILL.md stays short — it is the router. Everything heavy lives in scripts/ or references/ and is pulled in only when the agent actually needs it.SKILL.md ছোট থাকে — এটি রাউটার। ভারী সবকিছু scripts/ বা references/-এ থাকে এবং এজেন্টের আসলে প্রয়োজন হলে তবেই টানা হয়।
~33× reduction in always-on token cost — just from moving content to the right tier. Same capability, dramatically lower overhead.~৩৩× হ্রাস সবসময়-চালু টোকেন খরচে — শুধু কনটেন্ট সঠিক স্তরে সরিয়ে। একই সক্ষমতা, নাটকীয়ভাবে কম ওভারহেড।
LIVE BUILD · STEP 1লাইভ বিল্ড · ধাপ ১
The Fat Skill — Before Refactorমোটা স্কিল — রিফ্যাক্টরের আগে
--- SKILL.md (BEFORE — 800 lines, all inlined) ---# deploy-check
description: Run pre-deployment checks for nop-station services
## Steps
1. Confirm service name and target environment
2. Run the validation logic:
... 150 lines of Python validation logic inlined here ...
3. Cross-check against the release checklist:
... 200-line checklist inlined here ...
4. Verify all API field constraints:
... 90-row API field table inlined here ...
5. Generate report using the output template:
... 80-line Markdown template inlined here ...... 280 more lines of accumulated cruft ...
Every session that mentions any deployment topic now loads all 800 lines — even if all you asked was "what port does the staging server use?"যেকোনো ডিপ্লয়মেন্ট বিষয় উল্লেখ হলেই প্রতিটি সেশন এখন সব ৮০০ লাইন লোড করে — এমনকি যদি শুধু জিজ্ঞেস করো "স্টেজিং সার্ভারের পোর্ট কত?"
• references/release-checklist.md ← the 200-line checklist • references/api-fields.md ← the 90-row field table • references/report-template.md ← the 80-line output template• references/release-checklist.md ← ২০০ লাইনের চেকলিস্ট • references/api-fields.md ← ৯০ সারির ফিল্ড টেবিল • references/report-template.md ← ৮০ লাইনের আউটপুট টেমপ্লেট
T3 content is now in separate files. None of it enters the context window until explicitly read or executed.T3 কনটেন্ট এখন আলাদা ফাইলে। এর কিছুই কনটেক্সট উইন্ডোতে প্রবেশ করে না যতক্ষণ না স্পষ্টভাবে পড়া বা চালানো হয়।
LIVE BUILD · STEP 3লাইভ বিল্ড · ধাপ ৩
The Lean SKILL.md — After Refactorপাতলা SKILL.md — রিফ্যাক্টরের পরে
--- SKILL.md (AFTER — 28 lines, router only) ---# deploy-check
description: Run pre-deployment checks for nop-station services
## Steps
1. Ask: service name and target environment (staging/prod)
2. Run validation:
Execute scripts/run.py with {"service": <name>, "env": <env>}
3. Cross-check checklist:
Read references/release-checklist.md — apply each item
4. Verify API fields if needed:
Read references/api-fields.md — check constraints for service
5. Generate report:
Read references/report-template.md — fill in results
BEFOREআগে
800 linesলাইন
→
AFTERপরে
28 linesলাইন
TEAM DISCUSSIONটিম আলোচনা
Ankan Asks a Sharp Questionঅঙ্কন একটি তীক্ষ্ণ প্রশ্ন করে
SHAZZAD · FULLSTACK ENGINEER"What if the agent forgets to read the reference file? Or skips running the script? The instructions point to them — but what enforces it?""যদি এজেন্ট রেফারেন্স ফাইল পড়তে ভুলে যায়? বা স্ক্রিপ্ট চালানো বাদ দেয়? নির্দেশনা তাদের দিকে নির্দেশ করছে — কিন্তু কে নিশ্চিত করবে?"
RIFAT"Good point. Two answers: (1) make the step wording unambiguous — say 'You MUST read references/checklist.md before generating the report.' (2) test it. Run the skill with a new session and watch what the agent does.""ভালো পয়েন্ট। দুটি উত্তর: (১) ধাপের ভাষা সুস্পষ্ট করো — বলো 'রিপোর্ট তৈরির আগে references/checklist.md পড়তেই হবে।' (২) পরীক্ষা করো। নতুন সেশনে স্কিল চালাও এবং দেখো এজেন্ট কী করে।"
The skill is a contract. Explicit imperative language ("You MUST", "Before generating") leaves no room for the agent to skip a required step.স্কিল একটি চুক্তি। স্পষ্ট আদেশমূলক ভাষা ("অবশ্যই করতে হবে", "তৈরির আগে") এজেন্টকে প্রয়োজনীয় ধাপ এড়ানোর সুযোগ দেয় না।
WATCH OUTসাবধান
Four Gotchas to Avoidচারটি ভুল এড়াও
INLINE EVERYTHINGসব ইনলাইন করা
The habit that created the 800-line problem in the first place. Every "it's easier to paste it here" becomes permanent token tax.যে অভ্যাসটি শুরুতে ৮০০ লাইনের সমস্যা তৈরি করেছিল। প্রতিটি "এখানে পেস্ট করা সহজ" স্থায়ী টোকেন কর হয়ে যায়।
FORGET THE POINTERপয়েন্টার ভুলে যাওয়া
Moving a file to references/ without updating SKILL.md to mention it. The agent never knows to read it.SKILL.md আপডেট না করে ফাইল references/-এ সরানো। এজেন্ট কখনো জানে না সেটি পড়তে হবে।
UNDOCUMENTED SCRIPTSঅডকুমেন্টেড স্ক্রিপ্ট
Shipping scripts/run.py with no usage note in SKILL.md. The agent doesn't know what args it takes or when to call it.SKILL.md-এ usage নোট ছাড়া scripts/run.py পাঠানো। এজেন্ট জানে না কী আর্গুমেন্ট লাগে বা কখন ডাকতে হয়।
DUPLICATE ACROSS TIERSস্তরে স্তরে ডুপ্লিকেট
Summarizing a reference file in SKILL.md and keeping the full file. You pay twice — and they drift out of sync.SKILL.md-এ রেফারেন্স ফাইলের সারসংক্ষেপ রাখা এবং পুরো ফাইলও রাখা। দুবার দিতে হয় — এবং তারা sync থেকে বেরিয়ে যায়।
QUICK DIAGNOSTICদ্রুত ডায়াগনস্টিক
Is My Skill Over-Loaded?আমার স্কিল কি অতিরিক্ত লোড?
✓ OK
SKILL.md body is under 50 linesSKILL.md বডি ৫০ লাইনের কম
It reads like a router, not an encyclopedia.এটি এনসাইক্লোপিডিয়ার মতো নয়, রাউটারের মতো পড়ায়।
⚠ CHECK
SKILL.md is 50–150 linesSKILL.md ৫০–১৫০ লাইন
Look for any block ≥10 lines that could move to references/.≥১০ লাইনের যেকোনো ব্লক খোঁজো যা references/-এ যেতে পারে।
✗ REFACTOR
SKILL.md is over 150 linesSKILL.md ১৫০ লাইনের বেশি
Almost certainly hiding large checklists, templates, or logic that belongs in T3.প্রায় নিশ্চিতভাবে বড় চেকলিস্ট, টেমপ্লেট, বা লজিক লুকিয়ে আছে যা T3-এ থাকা উচিত।
HABIB"I ran this check on all our skills. Six were over 150 lines. After extraction, the heaviest one went from 620 to 34 lines.""আমাদের সব স্কিলে এই চেক চালালাম। ছয়টা ১৫০ লাইনের বেশি ছিল। extraction-এর পর সবচেয়ে ভারীটা ৬২০ থেকে ৩৪ লাইনে নেমে এল।"
RECAPপুনরাবৃত্তি
The Rules of Progressive Disclosureপ্রগ্রেসিভ ডিসক্লোজারের নিয়ম
1
T1 frontmatter must be tiny — it is paid on every session.T1 ফ্রন্টম্যাটার অবশ্যই ছোট — প্রতিটি সেশনে এটি পরিশোধ করতে হয়।
2
T2 body is the router — instructions and pointers, not content.T2 বডি হলো রাউটার — নির্দেশনা ও পয়েন্টার, কনটেন্ট নয়।
3
T3 is free until used — put everything heavy here.T3 ব্যবহারের আগে বিনামূল্যে — সব ভারী জিনিস এখানে রাখো।
THREE TIERSতিনটি স্তরBUNDLED SCRIPTSবান্ডেলড স্ক্রিপ্টREFERENCE FILESরেফারেন্স ফাইলLEAN BODYপাতলা বডি
Next → Episode 5: MCP & Tools — Reaching Beyond the Skill Layer. When your agent needs to call external APIs, query databases, or run cloud commands — MCP is how you wire that up cleanly.পরবর্তী → এপিসোড ৫: MCP ও টুলস — স্কিল লেয়ারের বাইরে পৌঁছানো। যখন তোমার এজেন্টকে বাহ্যিক API কল করতে, ডেটাবেজ কোয়েরি দিতে, বা ক্লাউড কমান্ড চালাতে হয় — MCP হলো সেটি পরিষ্কারভাবে সংযুক্ত করার উপায়।