একাধিক রিপোজিটরিতে এজেন্ট স্কিল শেয়ার করার নিয়ম

একাধিক রিপোজিটরিতে এজেন্ট স্কিল শেয়ার করার উপায়

একাধিক রিপোজিটরিতে এজেন্ট স্কিল শেয়ার করার জন্য ফাইল কপি করা বন্ধ করুন এবং সেটির ওপর নির্ভরতা তৈরি করুন। একটি স্কিল রিপোজিটরি রাখুন, সেটিকে ট্যাগ করুন এবং প্রতিটি প্রজেক্টকে একটি নির্দিষ্ট ট্যাগ পিন করতে দিন। এরপর প্রতিটি স্কিলের জন্য একটি করে smoke test যোগ করুন এবং প্রতিটি ভার্সন আপডেটকে ঠিক সেভাবেই রিভিউ করুন যেভাবে আপনি কোনো ডিপেন্ডেন্সি আপডেট রিভিউ করেন।

এর চারটি অংশ রয়েছে: একটি শেয়ারড সোর্স অফ ট্রুথ, প্রতিটি রিপোজিটরির জন্য একটি পিন করা ভার্সন, প্রতিটি স্কিলের জন্য একটি smoke test এবং একটি রিভিউ পাথ। নিচের অংশগুলোতে ব্যাখ্যা করা হয়েছে কেন প্রতিটি অংশ প্রয়োজন, 2026 সালে রিলিজ হওয়া টুলগুলো এ বিষয়ে কী কাজ করে এবং কীভাবে কোনো বাইরের সার্ভিস ছাড়াই একটি self-hosted git remote-এ পুরো বিষয়টি তৈরি করা যায়।

একটি এজেন্ট স্কিল হলো এমন একটি ফোল্ডার যাতে একটি SKILL.md ফাইল এবং প্রয়োজনীয় স্ক্রিপ্ট ও রেফারেন্স ফাইল থাকে। যদি এই ইউনিটটি আপনার কাছে নতুন হয়, তবে প্রথমে এজেন্ট স্কিল কী এবং SKILL.md কীভাবে কাজ করে তা পড়ে নিন। এই পৃষ্ঠাটি মূলত সেই ইউনিটের সাপ্লাই চেইন নিয়ে আলোচনা করে।

দক্ষতা যেখানে থাকে এবং তা শেয়ার করা কেন কঠিন

Claude Code তিনটি জায়গা থেকে দক্ষতা (skills) লোড করে এবং skills documentation-এ প্রতিটি পাথ উল্লেখ করা আছে।

• ~/.claude/skills/<skill-name>/SKILL.md হলো ব্যক্তিগত। এটি আপনার সব প্রজেক্টে লোড হয়, অন্য কারো প্রজেক্টে নয়।
• .claude/skills/<skill-name>/SKILL.md হলো প্রজেক্ট লেভেলের। যে কেউ এই রিপোজিটরি চেক আউট করলে এটি লোড হয়।
• <plugin>/skills/<skill-name>/SKILL.md একটি প্লাগইনের ভেতরে থাকে। প্লাগইনটি যেখানেই এনাবল করা থাকে, সেখানেই এটি লোড হয়।

মাঝেরটি টিমের জন্য সবচেয়ে কার্যকর, কারণ এটি কমিট করা থাকে এবং যে কেউ রিপোজিটরি ক্লোন করলে এটি পেয়ে যায়। এখানেই সমস্যার শুরু। .claude/skills/-এর একটি দক্ষতা একটি রিপোজিটরির অধীনে থাকে। আপনার যদি আটটি রিপোজিটরি থাকে, তবে দক্ষতাটি আটবার কপি করতে হয়।

ফ্রন্টম্যাটার (frontmatter) এক্ষেত্রে কোনো সাহায্য করে না। Agent Skills স্পেসিফিকেশন ছয়টি কি (key) অনুমোদন করে এবং ডিস্ট্রিবিউশন পাথগুলো অন্য কোনো কি ব্যবহার করলে তালিকার প্রিন্ট আউট দেখায়:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

লক্ষ্য করুন কী অনুপস্থিত: এখানে কোনো version কি নেই। ফাইলের ভেতরে এমন কিছু নেই যা রেকর্ড করে কোন কপিটি নতুন। এটি যুক্তিসঙ্গত, কারণ দক্ষতা একটি প্যাকেজের চেয়ে বরং একটি ডকুমেন্ট। এর মানে হলো ভার্সনিং বা সংস্করণ নিয়ন্ত্রণের বিষয়টি ফাইলের বাইরের স্তর থেকে আসতে হবে এবং সেই স্তরটি পরিচালনার দায়িত্ব আপনার।

সমস্যা এক: আটটি কপি যা নীরবে ভিন্ন হয়ে যায়

প্রথম দিনে কপি-পেস্ট কাজ করে। কিন্তু ষাট দিন পর এটি ব্যর্থ হয়। কেউ একজন payments রিপোজিটরিতে একটি ভুল নির্দেশনা সংশোধন করে, কিন্তু অন্য সাতটিতে কোনো পরিবর্তন করে না। অন্য কেউ orders-তে pagination সংক্রান্ত একটি নিয়ম যোগ করে। এখন একই স্কিলের নাম দুটি ভিন্ন রিভিউ প্রদান করে, যা নির্ভর করে এজেন্ট কোন ডিরেক্টরি থেকে শুরু হয়েছে তার ওপর, এবং কোনো ডেভেলপারই এটি জানে না।

এই ব্যর্থতাটি নীরব কারণ এতে কোনো error state নেই। একটি স্কিল হলো গদ্য। একটি পুরনো নির্দেশনা আত্মবিশ্বাসের সাথে ভুল উত্তর তৈরি করে, যা অত্যন্ত ব্যয়বহুল। এজেন্টের মধ্যে এমন কিছু নেই যা আপনার কপিকে অন্য কারো কপির সাথে তুলনা করবে, তাই একমাত্র সংকেত হলো যখন কোনো ব্যক্তি লক্ষ্য করেন যে দুটি রিপোজিটরি একে অপরের সাথে অমিল।

সমস্যা দুই: কোনো ভার্সন পিন করা নেই

একটি টিম যখন দক্ষতা বা স্কিলগুলোকে এক জায়গায় রাখে, তখনও শেয়ার করার সাধারণ পদ্ধতি হলো কপি করা: একটি সেটআপ স্ক্রিপ্ট, অনবোর্ডিং ডকুমেন্টে থাকা একটি curl লাইন, অথবা এমন একটি শেল অ্যালিয়াস যা একটি ফোল্ডারকে সিঙ্ক করে। এই সব পদ্ধতিই বর্তমানে ব্রাঞ্চের শীর্ষে যা আছে, তা-ই ইনস্টল করে।

এর মানে হলো, একই অ্যাপ্লিকেশনের একই কমিটে কাজ করা দুইজন ডেভেলপার ভিন্ন ভিন্ন ইন্সট্রাকশন অনুযায়ী চলতে পারেন, কারণ তারা ভিন্ন ভিন্ন দিনে সিঙ্ক করেছেন। এর মানে আরও একটি বিষয়, একটি খারাপ এজেন্ট রান হওয়ার পর যে প্রশ্নটি সবচেয়ে গুরুত্বপূর্ণ, তার উত্তর আপনি দিতে পারবেন না: কোন ভার্সনের স্কিল এটি তৈরি করেছে? কোনো রেকর্ড করা রিভিশন ছাড়া রানটি পুনরায় তৈরি করা সম্ভব নয়, তাই বাগ রিপোর্টটি কার্যকর হয় না।

সমস্যা তিন: দক্ষতাটি এখনও কাজ করছে কি না তা কেউ জানে না

একটি দক্ষতার কোনো কম্পাইলার নেই। এটি মূলত একটি মডেলের উদ্দেশ্যে দেওয়া নির্দেশাবলি, তাই ফাইলের প্রতিটি বাইট অপরিবর্তিত থাকলেও এটি কাজ করা বন্ধ করে দিতে পারে। মডেল আপগ্রেডের ফলে দীর্ঘ নির্দেশাবলি অনুসরণের ক্ষেত্রে মডেলের সক্ষমতা পরিবর্তিত হতে পারে। দক্ষতাটি যে কমান্ড লাইন টুল ব্যবহার করে, সেটি কোনো ফ্ল্যাগ (flag) রিনেম করতে পারে। রেফারেন্স ফাইলে থাকা কোনো URL 440 (404) এরর দিতে শুরু করতে পারে এবং এজেন্ট তখন সেই এরর পেজ থেকেই কাজ চালিয়ে যেতে পারে।

এই ধরনের কোনো ক্ষেত্রেই বড় ধরনের কোনো ব্যর্থতা দেখা দেয় না। এজেন্ট এখনও উত্তর দিয়ে যায়। সমস্যা হলো, গত মাসের তুলনায় উত্তরটি এখন নিম্নমানের, যা প্রতিটি পুল রিকোয়েস্ট (pull request) পর্যালোচনার সময় শনাক্ত করা বেশ কঠিন।

2026 সালে যে টুলগুলো আসছে তা যা সমাধান করে

বর্তমানে বেশ কিছু সমাধান পাওয়া যাচ্ছে, তবে ভার্সন কোথায় রাখা উচিত তা নিয়ে মতভেদ রয়েছে।

Lockfiles. Vercel Labs-এর skills কমান্ড লাইন টুলটি (vercel-labs/skills, MIT লাইসেন্সপ্রাপ্ত, 5 আগস্ট 2026 অনুযায়ী v1.5.22) একটি গিট রিপোজিটরি থেকে আপনার এজেন্টের প্রত্যাশিত ডিরেক্টরিতে স্কিল ইনস্টল করে। এটি সত্তরটিরও বেশি এজেন্টের লেআউট চেনে। npx skills add <repo> ইনস্টল করে, npx skills update আপগ্রেড করে এবং npx skills list আপনার কাছে কী আছে তা দেখায়। কী ইনস্টল করা আছে তার রেকর্ড প্রতি রিপোজিটরির পরিবর্তে প্রতি ব্যবহারকারীর জন্য একবার রাখা হয়। সেই প্রজেক্টে একটি ওপেন রিকোয়েস্ট (issue 283) রয়েছে যেখানে একটি skills install কমান্ডের দাবি করা হয়েছে, যা লক ফাইল থেকে সমস্ত ট্র্যাক করা স্কিল পুনরায় ইনস্টল করবে যাতে দ্বিতীয় একটি মেশিনেও একই সেট থাকে। সেই রিকোয়েস্টটিকে একটি স্ট্যাটাস রিপোর্ট হিসেবে পড়ুন। লকফাইলের ধারণাটি চূড়ান্ত হয়েছে। এর প্রতি-প্রজেক্ট অংশটি এখনও তৈরি করা হচ্ছে।

Specs and tests. SkillSpec অন্য একটি দৃষ্টিভঙ্গি গ্রহণ করে। এটি একটি SKILL.md-কে বিশ্বাসযোগ্য গদ্যের পরিবর্তে যাচাই করার মতো একটি চুক্তি হিসেবে বিবেচনা করে। এর লক্ষ্য হলো স্কিলগুলোকে "অনুসরণযোগ্য, পরীক্ষযোগ্য এবং প্রমাণযোগ্য" করে তোলা। skillspec doctor <path> রিপোর্ট করে যে একটি এজেন্ট কোথায় থ্রেডটি ড্রপ করার সম্ভাবনা রাখে। skillspec boundary map <path> রিপোর্ট করে যে স্কিলটি কী কী অ্যাক্সেস করতে পারে এবং skillspec boundary assess <path> সেই ফলাফলগুলোকে ঝুঁকির ভিত্তিতে র‍্যাঙ্ক করে। এটি একটি Rust ক্রেট, যা MIT বা Apache 2.0 লাইসেন্সপ্রাপ্ত এবং 29 জুলাই 2026 অনুযায়ী 0.2.2 ভার্সনে রয়েছে। নতুন ভার্সনের পরিবর্তে পিন করা ভার্সনটি ইনস্টল করুন:

cargo install skillspec --version 0.2.2 --locked
skillspec --version

--locked সেই ডিপেন্ডেন্সি ভার্সনগুলো দিয়ে বিল্ড করে যা দিয়ে ক্রেটটি পাবলিশ করা হয়েছিল, ফলে বিল্ডটি আপনার অজান্তে পরিবর্তিত হয় না। skillspec --version-এর আউটপুট 0.2.2 হওয়া উচিত। ভিন্ন কোনো সংখ্যা আসার মানে হলো আপনার PATH-এ থাকা কোনো পুরনো বাইনারি কাজ করছে।

Vendor practice. গুগল google/skills-এ কীভাবে স্কিল তৈরি করে তা কিভাবে এটি এজেন্টের স্কিল তৈরি, পরীক্ষা এবং স্কেল করে শীর্ষক একটি পোস্টে বর্ণনা করেছে। স্কেলিংয়ের বিষয়গুলো বাদ দিলে এর প্রক্রিয়াটি সাধারণ কন্টিনিউয়াস ইন্টিগ্রেশন (CI)। মার্জ হওয়ার আগে প্রতিটি স্কিল ফ্রন্টম্যাটার মেটাডেটা, লাইনের সংখ্যা, ডিরেক্টরি লেআউট এবং নামকরণের জন্য লিন্টার (linter) পরীক্ষা পার করে। কোনো URL 4-0-4 (404) রিটার্ন করলে লিঙ্ক চেকার বিল্ডটি ব্যর্থ করে দেয়, যা এজেন্টের তৈরি করা কাল্পনিক লিঙ্কগুলো ধরে ফেলে। লেখকদের অবশ্যই স্কিলের পাশাপাশি একটি ইভালুয়েশন প্রম্পট স্যুট এবং স্কোরিং রুব্রিক সরবরাহ করতে হবে। এরপর নিয়মিত ইভালুয়েশন জবগুলো পুরো লাইব্রেরির ওপর সাপ্তাহিক ভিত্তিতে চালানো হয় যাতে রিগ্রেশন ধরা পড়ে। প্রতিটি স্কিলের একজন নির্দিষ্ট মালিক থাকেন, যার দায়িত্ব হলো মান কমে গেলে তা ঠিক করা।

তিনটি উত্তরের অন্তর্নিহিত প্যাটার্ন

আপনাকে এর মধ্যে যেকোনো একটি বেছে নিতে হবে না। এগুলোর নিচে একটি একক কাঠামো রয়েছে এবং সাধারণ git ব্যবহার করেই আপনি তার সবকিছু পেতে পারেন।

1. তথ্যের একটি একক উৎস (One source of truth)। প্রতিটি দক্ষতার জন্য একটি নির্দিষ্ট জায়গা থাকে এবং প্রতিটি রিপোজিটরি কপি রাখার পরিবর্তে সেই মূল জায়গাকে রেফার করে।
2. প্রতিটি রিপোজিটরির জন্য একটি পিন করা ভার্সন। প্রতিটি প্রজেক্ট তার ব্যবহৃত সঠিক রিভিশন রেকর্ড করে রাখে, ফলে আপগ্রেড করার অর্থ হলো সেই প্রজেক্টে একজন লেখক এবং তারিখসহ একটি নতুন কমিট করা।
3. প্রতিটি দক্ষতার জন্য একটি স্মোক টেস্ট। একটি রানযোগ্য চেক যা প্রমাণ করে যে দক্ষতাটি এখনও তার প্রতিশ্রুতি অনুযায়ী ফলাফল দিচ্ছে।
4. একটি রিভিউ পাথ। কোনো শেয়ারড দক্ষতায় পরিবর্তন আনা হলে তা রিভিউ প্রক্রিয়ার মধ্য দিয়ে যায় এবং প্রতিটি কনজিউমার তা গ্রহণ করার আগে একটি ডিফারেন্স (diff) দেখতে পায়।

এটিই হলো ডিপেন্ডেন্সির মূল কাঠামো। টুলিং তৈরি হওয়ার আগেই দক্ষতাগুলো শেয়ারড আর্টিফ্যাক্ট হিসেবে দ্রুত জনপ্রিয় হয়ে উঠেছে, তাই আপনার ইতিমধ্যে নির্ভরযোগ্য টুলিং ব্যবহার করাই সবচেয়ে নিরাপদ উপায়।

একটি ছোট দলের জন্য self-hosted git remote-এর লেআউট

একটি রিপোজিটরিতে শুধুমাত্র দক্ষতা বা স্কিলগুলো রাখা হয়। এতে অন্য কিছু থাকে না, তাই এর ইতিহাস নির্দেশনার একটি changelog হিসেবে কাজ করে।

agent-skills/
  skills/
    api-review/
      SKILL.md
    release-notes/
      SKILL.md
  tests/
    api-review.sh
    release-notes.sh
  CHANGELOG.md

Releases হলো tags। annotated tags ব্যবহার করুন, কারণ এগুলোতে একটি বার্তা এবং তারিখ থাকে। বার্তাটি এমনভাবে লিখুন যাতে একজন ব্যবহারকারী বুঝতে পারেন কেন এই bump বা আপডেটটি প্রয়োজন:

git tag -a v1.4.0 -m "api-review: require pagination on list endpoints"
git push origin v1.4.0

আপনার remote যদি Gitea, Forgejo, GitLab অথবা আপনার নিজস্ব VPS-এ SSH-এর মাধ্যমে কোনো bare repository হয়, তবে নিচের কোনো কিছুই পরিবর্তিত হবে না। এখানে সবকিছুই হলো git এবং একটি symlink।

git submodule দিয়ে পিন করা

একটি submodule আপনার রিপোজিটরির ভেতরে অন্য একটি রিপোজিটরির নির্দিষ্ট একটি commit রেকর্ড করে রাখে। এই রেকর্ডটিই হলো পিন। প্রতিটি ব্যবহারকারী প্রজেক্টে:

git submodule add https://git.example.com/team/agent-skills.git vendor/agent-skills
git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills checkout v1.4.0
mkdir -p .claude/skills
ln -s ../../vendor/agent-skills/skills/api-review .claude/skills/api-review
git add .gitmodules vendor/agent-skills .claude/skills/api-review
git commit -m "Pin shared agent skills to v1.4.0"

symlink-ই এই প্রক্রিয়াটি কার্যকর করে। প্রজেক্ট লেভেলে একটি skill entry ডিস্কের অন্য কোনো ডিরেক্টরির symlink হতে পারে এবং Claude Code তা অনুসরণ করে লক্ষ্যবস্তু থেকে SKILL.md পড়ে নেয়। ফলে skill-টি একটি সাধারণ প্রজেক্ট skill হিসেবে লোড হয়, কিন্তু এর বাইটগুলো আপনার বেছে নেওয়া commit-এ submodule-এর ভেতরে থাকে।

পিনটি যাচাই করুন:

git submodule status

একটি সঠিক লাইনের শুরুতে একটি স্পেস, তারপর commit, তারপর পাথ এবং সবশেষে নিকটতম ট্যাগ থাকে:

 4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602 vendor/agent-skills (v1.4.0)

শুরুতে - থাকার অর্থ হলো submodule-টি কখনোই initialised করা হয়নি, তাই .claude/skills/api-review কোনো কিছুকে নির্দেশ করছে না এবং skill-টি নীরবে লোড হচ্ছে না। git submodule update --init দিয়ে এটি ঠিক করুন। শুরুতে + থাকার অর্থ হলো চেক-আউট করা commit-টি রেকর্ড করা commit থেকে আলাদা, অর্থাৎ সেই ডেভেলপার এমন সব নির্দেশনা চালাচ্ছেন যা অন্য কারো কাছে নেই। নতুন clone-এর জন্য git clone --recurse-submodules প্রয়োজন এবং এই লাইনটি README-তে থাকা উচিত, কারণ সাধারণ clone-এর ক্ষেত্রে vendor/agent-skills খালি থাকে এবং কোনো error দেখায় না।

আপগ্রেড করা একটি সচেতন প্রক্রিয়া, আর এটাই এর মূল উদ্দেশ্য:

git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills diff v1.4.0 v1.5.0 -- skills/
git -C vendor/agent-skills checkout v1.5.0
git add vendor/agent-skills
git commit -m "Bump shared agent skills to v1.5.0"

diff লাইনটি হলো রিভিউ পাথ। এটি সেই একই পরিবর্তন দেখায় যা অন্য সব ব্যবহারকারী রিপোজিটরি দেখতে পাবে এবং এটি pull request-এর সাথে সামঞ্জস্যপূর্ণ।

পরিবর্তে একটি প্লাগইন মার্কেটপ্লেস ব্যবহার করে পিনিং

আপনি যদি প্রত্যেক ডেভেলপারকে submodule শিখতে বাধ্য করতে না চান, তবে Claude Code প্লাগইন সিস্টেম আপনার জন্য ডিস্ট্রিবিউশনের কাজটি করে দেবে এবং এটি একটি self-hosted রিমোটের সাথে কাজ করে। skills রিপোজিটরিতে .claude-plugin/marketplace.json-এ একটি ক্যাটালগ রাখুন:

{
  "name": "acme-agents",
  "owner": { "name": "Platform team", "email": "platform@example.com" },
  "plugins": [
    {
      "name": "team-skills",
      "description": "Shared review and release skills",
      "version": "1.4.0",
      "source": {
        "source": "url",
        "url": "https://git.example.com/team/agent-skills.git",
        "ref": "v1.4.0",
        "sha": "4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602"
      }
    }
  ]
}

এখানে দুটি ভিন্ন সোর্স কাজ করছে এবং এদের গুলিয়ে ফেলা একটি সাধারণ ভুল। মার্কেটপ্লেস সোর্স, অর্থাৎ যেখান থেকে ক্যাটালগটি আনা হয়, সেটি branch বা tag-এর জন্য ref গ্রহণ করে এবং sha গ্রহণ করে না। ক্যাটালগের ভেতরের একটি প্লাগইন সোর্স উভয়ই গ্রহণ করে, এবং যখন দুটিই সেট করা থাকে, তখন sha কার্যকর পিন হিসেবে কাজ করে। তাই exact-commit পিনটি ক্যাটালগ এন্ট্রিতে থাকা উচিত।

প্রতিটি কনজিউমিং রিপোজিটরি তখন তাদের কমিট করা .claude/settings.json-এ মার্কেটপ্লেসটি ঘোষণা করে:

{
  "extraKnownMarketplaces": {
    "acme-agents": {
      "source": {
        "source": "url",
        "url": "https://git.example.com/team/agent-skills.git",
        "ref": "v1.4.0"
      }
    }
  },
  "enabledPlugins": {
    "team-skills@acme-agents": true
  }
}

যে টিমমেট প্রজেক্ট ফোল্ডারটিকে বিশ্বাস করেন, তাকে মার্কেটপ্লেসটি ইনস্টল করার জন্য প্রম্পট দেখানো হবে এবং কোনো উইকি পেজের নির্দেশনা ছাড়াই প্লাগইনটি তাদের জন্য সক্রিয় হয়ে যাবে। এরপর স্কিলগুলো /team-skills:api-review-এ সাড়া দেবে, কারণ প্লাগইন স্কিলগুলো প্লাগইন নামের ভিত্তিতে namespaced থাকে এবং একই নামের কোনো প্রজেক্ট স্কিলের সাথে সংঘর্ষ হয় না। নতুন একটি tag পুশ করার পর, কনজিউমাররা /plugin marketplace update acme-agents দিয়ে রিফ্রেশ করবে এবং ইনস্টল সামারি চাইলে /reload-plugins রান করবে।

একটি স্কিলের জন্য স্মোক টেস্ট লেখা

একটি স্মোক টেস্ট হলো এমন একটি স্ক্রিপ্টেড এজেন্ট রান, যা একটি পরিচিত ত্রুটিযুক্ত ফিক্সচারের বিপরীতে চালানো হয় এবং এতে একটি অ্যাসারশন থাকে। Claude Code নন-ইন্টারেক্টিভভাবে -p দিয়ে চলে এবং সেখানে ব্যবহারকারীর ইনভোক করা স্কিল কাজ করে: প্রম্পট স্ট্রিংয়ে /skill-name বসিয়ে দিলে রান শুরু হওয়ার আগেই তা এক্সপ্যান্ড হয়ে যায়।

#!/usr/bin/env bash
set -euo pipefail

claude -p "/api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
  --allowedTools "Read" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["rule_ids"]}' \
  | jq -e '.structured_output.rule_ids | index("pagination-required")' > /dev/null

fixtures/orders-api.md হলো একটি ছোট ফাইল যাতে একটি ইচ্ছাকৃত ত্রুটি রাখা হয়েছে। অ্যাসারশনটি হলো, স্কিলটিকে অবশ্যই সেই ত্রুটির নাম উল্লেখ করতে হবে। যখন এর ফিল্টার null তৈরি করে, তখন jq -e নন-জিরো এক্সিট কোড দেয়; তাই যে স্কিলটি এই সিড করা ত্রুটি ধরতে ব্যর্থ হয়, সেই স্ক্রিপ্টটিও ব্যর্থ হয়। রান ব্যর্থ হলে claude নিজে নন-জিরো এক্সিট কোড দেয় এবং set -euo pipefail যেকোনো ব্যর্থতাকে একটি ফেইলড টেস্ট হিসেবে গণ্য করে।

মডেল প্রতিটি রানের সময় তার উত্তরের ভাষা পরিবর্তন করতে পারে, তাই পুরো বাক্যের ওপর ভিত্তি করে অ্যাসার্ট করবেন না। স্কিলটি যে আইডেন্টিফায়ারটি প্রদান করবে বা আপনি যে স্কিমা চেয়েছেন তার কোনো ফিল্ডের ওপর ভিত্তি করে অ্যাসার্ট করুন। রান যাতে সাশ্রয়ী হয় সেজন্য ফিক্সচারটি ছোট রাখুন।

CI-তে --bare যোগ করুন। এটি ছাড়া, claude -p সেই একই কনটেক্সট লোড করে যা একটি ইন্টারেক্টিভ সেশনে থাকে, যার মধ্যে হুক, প্লাগইন এবং মেশিন থেকে পাওয়া CLAUDE.md অন্তর্ভুক্ত থাকে; ফলে কোনো সহকর্মীর ব্যক্তিগত কনফিগারেশন ফলাফলে পরিবর্তন আনতে পারে। বেয়ার মোড (bare mode) সমস্ত অটো-ডিসকভারি এড়িয়ে যায়, যার অর্থ এটি আপনার টেস্ট করা স্কিলটিকেও এড়িয়ে যাবে, তাই সেটিকে স্পষ্টভাবে লোড করুন। বেয়ার মোড আপনার সাবস্ক্রিপশন লগইনও পড়ে না, তাই এনভায়রনমেন্টে আগে ANTHROPIC_API_KEY সেট করে নিন:

claude --bare -p "/team-skills:api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
  --plugin-dir vendor/agent-skills \
  --allowedTools "Read" \
  --output-format json

--output-format stream-json ব্যবহার করলে, রানের প্রথম ইভেন্টটি রিপোর্ট করে কোন প্লাগইনগুলো লোড হয়েছে এবং যেগুলো লোড হয়নি সেগুলোর জন্য একটি plugin_errors অ্যারে বহন করে। যদি plugin_errors খালি না থাকে তবে CI জবটি ফেইল করিয়ে দিন। এটি এমন কোনো পিন (pin) ধরে ফেলে যা এমন কোনো রিভিশনের দিকে নির্দেশ করে যা আর নেই; অন্যথায় এজেন্ট আপনার হাউস রুলসগুলো নীরবে উপেক্ষা করছে বলে মনে হতে পারে।

একটি শেয়ারড স্কিল হলো এক্সিকিউটেবল ইনস্ট্রাকশন

দুটি বৈশিষ্ট্য একে আক্ষরিক অর্থে কার্যকর করে তোলে এবং যখন ফাইলটি অন্য কোনো টিম থেকে আসে, তখন উভয়ই গুরুত্বপূর্ণ হয়ে ওঠে।

প্রথমত, একটি SKILL.md মডেল কোনো কিছু পড়ার আগেই শেল কমান্ড চালাতে পারে। বডিতে নিচের মতো একটি লাইন প্রি-প্রসেসিং হিসেবে কাজ করে:

- Current branch: !`git rev-parse --abbrev-ref HEAD`

এই কমান্ডটি স্কিল লোড করা মেশিনে চলে এবং এর আউটপুট মডেলের প্রাপ্ত টেক্সটের প্লেসহোল্ডারকে প্রতিস্থাপন করে। তিনটি ব্যাকটিকের পর ! দিয়ে খোলা একটি ফেন্সড ব্লক একইভাবে একাধিক কমান্ড চালায়। রানটাইমে এর কোনোটিই অনুমোদনের প্রয়োজন হয় না। একটি শেয়ারড স্কিল পড়ার অর্থ হলো এর কমান্ড সাবস্টিটিউশনগুলোও পড়া।

দ্বিতীয়ত, ফ্রন্টম্যাটার টুলগুলোকে আগে থেকেই অনুমোদন দিতে পারে। allowed-tools তালিকাভুক্ত টুলগুলোকে কোনো পারমিশন প্রম্পট ছাড়াই ব্যবহারের অনুমতি দেয়, যদি সেই টার্নে স্কিলটি ইনভোক করা হয়। একটি প্রজেক্ট স্কিলের ক্ষেত্রে, কেউ যখন ফোল্ডারের জন্য ওয়ার্কস্পেস ট্রাস্ট ডায়ালগ গ্রহণ করে, তখন এই অনুমতি কার্যকর হয়। Claude Code ডকুমেন্টেশনে এর ফলাফল স্পষ্টভাবে বলা হয়েছে: কোনো রিপোজিটরি ট্রাস্ট করার আগে প্রজেক্ট স্কিলগুলো রিভিউ করুন, কারণ একটি স্কিল নিজেই নিজেকে বিস্তৃত টুল অ্যাক্সেস দেওয়ার ক্ষমতা রাখে।

তাই একটি স্কিল আপডেটকে ঠিক ডিপেন্ডেন্সি আপডেটের মতোই গুরুত্ব দিন। মেকানিজম যেখানেই অনুমতি দেয়, সেখানেই সঠিক কমিট হ্যাশ ব্যবহার করে পিন করুন, কারণ ট্যাগ পরিবর্তন করা সম্ভব এবং ব্রাঞ্চের সংজ্ঞা অনুযায়ীই তা পরিবর্তিত হয়। একটি লক-ডাউন মেশিনে, সেটিংসে "disableSkillShellExecution": true ব্যবহার করলে তা প্রতিটি কমান্ড সাবস্টিটিউশনকে রান না করে আক্ষরিক টেক্সট [shell command execution disabled by policy] হিসেবে প্রতিস্থাপন করে এবং ম্যানেজড সেটিংসের মাধ্যমে প্রয়োগ করলে ব্যবহারকারী তা ওভাররাইড করতে পারেন না। বান্ডেলড এবং ম্যানেজড স্কিলগুলো এই সেটিংয়ের আওতামুক্ত।

একটি স্কিল কী পড়ছে, সে বিষয়েও একই সতর্কতা অবলম্বন করা উচিত। যে স্কিল env চালায় বা কোনো কনফিগ ফাইল খোলে, তা যা কিছু খুঁজে পায় তা মডেলের কনটেক্সটে নিয়ে আসে, যা keeping secrets out of the agents you run-এ আলোচিত ব্যর্থতার কারণ। যে স্কিল কোনো পেজ ফেচ করে বা কুয়েরি চালায়, তা বাইরের দিকে উন্মুক্ত হওয়ার মতোই একটি ঝুঁকি, কারণ সংগৃহীত টেক্সট কনটেক্সটে এমনভাবে আসে যেন তা আপনার লেখা ইনস্ট্রাকশন। তাই point an agent at your own SearXNG instance for web search করার আগে এই বাউন্ডারি সম্পর্কে পড়ে নেওয়া জরুরি।

ভার্সন পরিবর্তনের সময় যা যা পড়তে হবে

• প্রতিটি SKILL.md বডির ডিফারেন্স (diff), কারণ এই টেক্সটটিই সেই নির্দেশনা যা আপনার এজেন্ট অনুসরণ করবে।
• প্রতিটি কমান্ড সাবস্টিটিউশন, কারণ স্কিল লোড হওয়ার সময় এগুলো আপনার মেশিনে রান করে।
• allowed-tools-এ যেকোনো পরিবর্তন, কারণ এই লাইনটি কোনো প্রম্পট ছাড়াই টুল ব্যবহারের অনুমতি দেয়।
• ট্যাগটির পেছনে থাকা টেস্ট রান। যদি শেয়ার করা রিপোজিটরি তার নিজস্ব স্মোক টেস্ট CI-তে রান করে, তবে আপনি যে ট্যাগটি পিন করছেন তার সাথে একটি গ্রিন রান সংযুক্ত থাকা উচিত।

একজন রিভিউয়ার যিনি দশ মিনিটে পুরো ডিফারেন্স পড়তে পারেন না, তিনি এমন একটি স্কিল দেখছেন যা প্রয়োজনের চেয়ে বেশি বড় হয়ে গেছে। এটিকে ভাগ করুন। একই যুক্তি আপনার এজেন্টদের পড়া রিপোজিটরি ডকুমেন্টগুলোর ক্ষেত্রেও প্রযোজ্য: স্থায়ী নিয়মগুলো AGENTS.md এবং HUMAN.md বিভাজন-এ বর্ণিত ফাইলগুলোতে রাখুন এবং আর্কিটেকচারাল যুক্তিগুলো এজেন্টদের জন্য লেখা DESIGN.md-এ রাখুন, আর স্কিলগুলোকে সুনির্দিষ্ট কার্যপদ্ধতি হিসেবে সীমাবদ্ধ থাকতে দিন।

যখন কোনো মডেল বা টুলের পরিবর্তনের কারণে স্কিল কাজ করা বন্ধ করে দেয়

কেউ কোনো কিছু এডিট না করলেও একটি স্কিলের অভ্যন্তরীণ অনেক কিছু পরিবর্তিত হতে পারে। মডেল আপগ্রেডের ফলে দীর্ঘ নির্দেশনা অনুসরণের নির্ভরযোগ্যতা বদলে যায়, তাই যে স্কিলটি আগে মডেলের নবম ধাপ পর্যন্ত পৌঁছাতে পারত, তা এখন আর সেখানে পৌঁছাতে ব্যর্থ হতে পারে। কোনো কমান্ড লাইন টুল হয়তো তার ফ্ল্যাগ পরিবর্তন করে, ফলে এজেন্ট পুরনো ফ্ল্যাগটি রান করে, এরর মেসেজ পড়ে এবং তাৎক্ষণিকভাবে নতুন উপায় বের করার চেষ্টা করে। কোনো রেফারেন্সড URL হয়তো 404 এরর দিতে শুরু করে। এজেন্ট হারনেস কীভাবে স্কিল নির্বাচন করে তা পরিবর্তিত হতে পারে, যার ফলে যে description আগে সফল হতো, তা এখন আর কাজ করে না। যখন কোনো প্রসিডিউর এভাবে মাঝপথে শেষ হয়ে যায়, তখন কোনো ভার্সন বাম্প (version bump) দিয়ে তা ঠিক করা যায় না। বরং নির্দেশনায় এমন কাঠামোর প্রয়োজন হয় যা শেষ ধাপগুলো সম্পন্ন করতে বাধ্য করে, আর এই পদ্ধতিটিই the unlazy skill and its Depth Tree method-এর মূল ভিত্তি।

এই কারণেই এই ব্যবস্থায় স্মোক টেস্ট অত্যন্ত গুরুত্বপূর্ণ। প্রতিটি স্কিলের টেস্ট শিডিউল অনুযায়ী এবং কোড পুশ করার সময় রান করুন। এই কারণেই Google তাদের পুরো লাইব্রেরির ওপর সাপ্তাহিক ভিত্তিতে ইভালুয়েশন জব চালায়। দশটি স্কিল আছে এমন একটি টিমের জন্য ছোট একটি VPS-এ সাপ্তাহিক ক্রন জব (cron job) চালানোই যথেষ্ট। ডেভেলপার জানার আগেই আপনার কাছে ত্রুটির খবর পৌঁছানোর এটিই একমাত্র উপায়।

পোর্টেবিলিটিও এক্ষেত্রে সহায়ক। Agent Skills স্পেসিফিকেশন ফ্রন্টম্যাটারকে ছয়টি কি (key)-এর মধ্যে সীমাবদ্ধ রাখে। ফলে এই স্পেসিফিকেশন অনুযায়ী লেখা স্কিল আপনি যে টুলের জন্য তৈরি করেছেন, তার বাইরেও অন্যান্য টুলে লোড করা যায়। অন্যদিকে, হারনেস-নির্দিষ্ট প্রতিটি কি (key) যোগ করা মানে আপনি একটি নির্দিষ্ট ভেন্ডরের ওপর বাজি ধরছেন। মডেল পরিবর্তনের পরেও টিকে থাকতে পারে এমন স্কিল লেখা একটি আলাদা দক্ষতা, যা making a skill work on any model-এ বিস্তারিত আলোচনা করা হয়েছে।

FAQ

আমি কীভাবে একটি এজেন্ট স্কিল একাধিক রিপোজিটরিতে শেয়ার করব?

স্কিলটিকে একটি আলাদা git রিপোজিটরিতে রাখুন, সেখানে রিলিজ ট্যাগ করুন এবং প্রতিটি ব্যবহারকারী প্রজেক্টে ফাইল কপি না করে একটি নির্দিষ্ট ট্যাগ রেফারেন্স করুন। দুটি পদ্ধতিতে এটি করা যায়। একটি git submodule নির্দিষ্ট কমিট রেকর্ড করে এবং .claude/skills/<name> থেকে একটি symlink ব্যবহার করলে তা সাধারণ প্রজেক্ট স্কিল হিসেবে লোড হয়। একটি প্লাগইন মার্কেটপ্লেস /plugin-এর মাধ্যমে একই কাজ করে, যেখানে ব্যবহারকারী রিপোজিটরির .claude/settings.json-এ ভার্সনটি পিন করা থাকে। উভয় পদ্ধতিই git হিস্ট্রিতে ভার্সনটি সংরক্ষণ করে, ফলে কোনো নির্দিষ্ট এজেন্ট রান কোন ইনস্ট্রাকশন থেকে এসেছে তা আপনি নিশ্চিত করতে পারবেন।

আমি কি কোনো এজেন্ট স্কিলকে নির্দিষ্ট ভার্সনে পিন করতে পারি?

SKILL.md-এর ভেতর থেকে এটি সম্ভব নয়, কারণ সেই ফ্রন্টম্যাটারে কোনো version কি (key) নেই। পিন করার বিষয়টি ফাইলের বাইরের স্তর থেকে আসতে হয়। একটি git submodule ডিজাইন অনুযায়ীই নির্দিষ্ট কমিট পিন করে। Claude Code প্লাগইন মার্কেটপ্লেসে, একটি প্লাগইন সোর্স ব্রাঞ্চ বা ট্যাগের জন্য ref এবং নির্দিষ্ট কমিটের জন্য sha গ্রহণ করে, এবং উভয়ই উপস্থিত থাকলে sha প্রাধান্য পায়। মার্কেটপ্লেস সোর্সটি শুধুমাত্র ref গ্রহণ করে। কমিট পিন ব্যবহার করা শ্রেয়, কারণ ট্যাগ রিভিউ করার পরেও পরিবর্তন করা সম্ভব।

একটি স্কিল স্মোক টেস্টে কী যাচাই করা উচিত?

স্থিতিশীল কোনো কিছুর ওপর ভিত্তি করে যাচাই করুন। স্কিলটিকে একটি পরিচিত ত্রুটিযুক্ত ফিক্সচারের বিপরীতে নন-ইন্টারেক্টিভভাবে চালান, তারপর আউটপুটে নির্দিষ্ট কোনো আইডেন্টিফায়ার আছে কি না তা পরীক্ষা করুন, যেমন কোনো রুল আইডি যা স্কিলটির রিপোর্ট করার কথা। --output-format json এবং --json-schema ব্যবহার করে স্ট্রাকচার্ড আউটপুট চাইলে চেকটি নির্ভুল হয় এবং মান অনুপস্থিত থাকলে jq -e স্ক্রিপ্টটিকে ফেইল করিয়ে দেয়। কখনোই পুরো বাক্যের ওপর ভিত্তি করে অ্যাসার্ট করবেন না, কারণ মডেল প্রতিবার রান করার সময় তার উত্তরের শব্দ পরিবর্তন করতে পারে।

অন্য টিমের রিপোজিটরি থেকে শেয়ার করা স্কিল ইনস্টল করা কি নিরাপদ?

এটিকে একটি কোড ডিপেন্ডেন্সি হিসেবে বিবেচনা করুন, কারণ এটি কার্যকরযোগ্য নির্দেশনা। একটি SKILL.md লোড হওয়ার সময় ! কমান্ড সাবস্টিটিউশন ফর্মের মাধ্যমে শেল কমান্ড চালাতে পারে এবং ফ্রন্টম্যাটারের allowed-tools ফিল্ড কোনো প্রম্পট ছাড়াই টুলগুলোকে প্রি-অ্যাপ্রুভ করতে পারে। প্রতিটি আপডেটের সময় ডিফারেন্স (diff) পড়ুন, ব্রাঞ্চের পরিবর্তে নির্দিষ্ট কমিটে পিন করুন এবং আপনার নিজের টিমের নিয়ন্ত্রণাধীন সোর্স ব্যবহার করাকে অগ্রাধিকার দিন। ম্যানেজড মেশিনে, সেটিংসে "disableSkillShellExecution": true ব্যবহার করলে কমান্ড সাবস্টিটিউশন পুরোপুরি বন্ধ হয়ে যায়।

শেয়ার করা স্কিল কি Claude Code ছাড়া অন্য এজেন্টে কাজ করবে?

এটি নির্ভর করে আপনি কোন ফ্রন্টম্যাটার ব্যবহার করছেন তার ওপর। Agent Skills স্পেসিফিকেশন ছয়টি কি (key) সংজ্ঞায়িত করে: name, description, license, compatibility, metadata এবং allowed-tools। এই কিগুলোর মধ্যে সীমাবদ্ধ স্কিলগুলো সেই সব টুলে লোড হবে যারা এই স্পেসিফিকেশন মেনে চলে, এবং সেগুলো কোনো পরিবর্তন ছাড়াই Claude Code-এও লোড হবে। হারনেস-নির্দিষ্ট কি এবং স্পেসিফিকেশনের বাইরের বডি ফিচারগুলো অন্য জায়গায় উপেক্ষা করা হয় বা বাতিল হয়ে যায়, তাই ব্যাপকভাবে শেয়ার করতে চান এমন স্কিলে সেগুলো রাখা থেকে বিরত থাকুন।