एजेंट स्किल्स को रिपॉजिटरीज़ के बीच साझा कैसे करें

एजेंट स्किल्स को रिपॉजिटरीज़ के बीच साझा कैसे करें

एजेंट स्किल्स को रिपॉजिटरीज़ के बीच साझा करने के लिए, फाइल को कॉपी करना बंद करें और उस पर निर्भर (depend) होना शुरू करें। एक स्किल्स रिपॉजिटरी रखें, उसे टैग करें, और प्रत्येक प्रोजेक्ट को एक विशिष्ट टैग पिन करने दें। इसके बाद, प्रत्येक स्किल के लिए एक स्मोक टेस्ट जोड़ें, और हर वर्जन अपडेट (bump) की समीक्षा उसी तरह करें जैसे आप किसी डिपेंडेंसी अपडेट की करते हैं।

इसके चार भाग हैं: एक साझा सोर्स ऑफ ट्रुथ, प्रत्येक रिपॉजिटरी के लिए एक पिन किया गया वर्जन, प्रत्येक स्किल के लिए एक स्मोक टेस्ट, और एक समीक्षा प्रक्रिया। नीचे दी गई जानकारी बताती है कि प्रत्येक भाग क्यों आवश्यक है, 2026 में रिलीज होने वाले टूल्स इसके बारे में क्या करते हैं, और बिना किसी बाहरी git होस्ट या पैकेज रजिस्ट्री के, सेल्फ-होस्टेड git रिमोट पर इसे कैसे बनाया जाए। स्मोक टेस्ट इसका एकमात्र अपवाद हैं। वे Claude Code को रन करते हैं, जो प्रत्येक रिक्वेस्ट को एक मॉडल API पर भेजता है, इसलिए वह चरण अभी भी आपके सर्वर से बाहर जाता है।

एजेंट स्किल एक फोल्डर है जिसमें एक SKILL.md फाइल होती है, साथ ही उसे आवश्यक स्क्रिप्ट्स और रेफरेंस फाइलें होती हैं। यदि वह यूनिट नई है, तो पहले एजेंट स्किल क्या है और SKILL.md कैसे काम करता है पढ़ें। यह पेज उस यूनिट के चारों ओर की सप्लाई चेन के बारे में है।

कौशल कहाँ स्थित होते हैं, और साझा करना कठिन क्यों है

Claude Code अन्य स्थानों के अलावा निम्नलिखित स्थानों से कौशल (skills) लोड करता है, और skills documentation प्रत्येक path का नाम बताता है।

• .claude/skills/<skill-name>/SKILL.md प्रबंधित सेटिंग्स निर्देशिका के अंदर उद्यम (enterprise) स्थान है। यह उन मशीनों पर प्रत्येक उपयोगकर्ता के लिए लोड होता है जहाँ कोई संगठन इसे तैनात करता है।
• ~/.claude/skills/<skill-name>/SKILL.md व्यक्तिगत है। यह आपके सभी प्रोजेक्ट्स में लोड होता है और किसी और के प्रोजेक्ट में नहीं।
• .claude/skills/<skill-name>/SKILL.md प्रोजेक्ट स्तर का है। यह उस व्यक्ति के लिए लोड होता है जो उस रिपॉजिटरी को चेक आउट करता है।
• <plugin>/skills/<skill-name>/SKILL.md किसी प्लगइन के अंदर आता है। यह वहाँ लोड होता है जहाँ वह प्लगइन सक्षम (enabled) होता है।

Claude Code नेस्टेड प्रोजेक्ट निर्देशिकाओं, --add-dir के साथ प्रदान की गई निर्देशिकाओं, और आपके claude.ai खाते के लिए सक्षम कौशलों से भी कौशल लोड करता है।

प्रोजेक्ट स्तर वाला कौशल एक टीम के लिए उपयोगी होता है, क्योंकि इसे कमिट किया जाता है और जो कोई भी रिपॉजिटरी को क्लोन करता है, उसे यह मिल जाता है। यहीं से समस्या शुरू होती है। .claude/skills/ में एक कौशल एक रिपॉजिटरी से संबंधित होता है। आपके पास आठ रिपॉजिटरी हैं। इसलिए कौशल को आठ बार कॉपी किया जाता है।

फ्रंटमैटर कोई मदद नहीं करता है। Agent Skills विनिर्देश (spec) छह keys की अनुमति देता है, और वितरण पथ जो इसे लागू करते हैं, जब आप किसी अन्य का उपयोग करते हैं तो सूची प्रिंट करते हैं:

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

ध्यान दें कि क्या अनुपस्थित है: इसमें कोई version key नहीं है। फ़ाइल के अंदर कुछ भी यह रिकॉर्ड नहीं करता है कि कौन सी कॉपी नई है। यह उचित है, क्योंकि एक कौशल एक पैकेज के बजाय एक दस्तावेज़ है। इसका मतलब यह है कि वर्ज़निंग (versioning) को फ़ाइल के चारों ओर की परत से आना चाहिए, और वह परत आपका काम है।

समस्या एक: आठ प्रतियाँ जो चुपचाप अलग हो जाती हैं

Copy-paste पहले दिन काम करता है। यह साठवें दिन विफल हो जाता है। कोई व्यक्ति payments repo में एक गलत निर्देश को ठीक करता है और बाकी सात को नहीं छूता। कोई अन्य व्यक्ति orders में pagination के बारे में एक नियम जोड़ता है। अब एक ही skill name दो अलग-अलग review देता है, यह इस पर निर्भर करता है कि agent किस directory में शुरू हुआ था, और किसी भी developer को इसकी जानकारी नहीं होती।

यह विफलता silent होती है क्योंकि इसमें कोई error state नहीं होती। एक skill गद्य (prose) है। एक पुराना (stale) निर्देश एक आत्मविश्वासपूर्ण, गलत उत्तर उत्पन्न करता है, जो कि सबसे महंगा प्रकार है। agent में ऐसा कुछ भी नहीं है जो आपकी copy की तुलना किसी और की copy से करे, इसलिए एकमात्र संकेत यह है कि कोई व्यक्ति यह नोटिस करे कि दो repos आपस में असहमत हैं।

समस्या दो: किसी वर्ज़न को पिन न करना

भले ही कोई टीम अपनी skills को एक ही स्थान पर रखे, साझा करने का सामान्य तरीका एक कॉपी स्टेप है: एक setup script, onboarding doc में एक curl लाइन, या कोई shell alias जो किसी फोल्डर को सिंक करता है। ये सभी वही इंस्टॉल करते हैं जो उस समय branch के head पर मौजूद होता है।

इसका मतलब यह है कि एक ही application के एक ही commit पर काम कर रहे दो डेवलपर्स अलग-अलग निर्देश चला रहे हो सकते हैं, क्योंकि उन्होंने अलग-अलग दिनों में सिंक किया था। इसका यह भी अर्थ है कि एक खराब agent run के बाद आप उस महत्वपूर्ण प्रश्न का उत्तर नहीं दे सकते: इस skill के किस वर्ज़न ने इसे उत्पन्न किया? बिना किसी रिकॉर्ड किए गए revision के, run को reproduce नहीं किया जा सकता, इसलिए bug report पर कोई कार्रवाई नहीं की जा सकती।

समस्या तीन: किसी को यह नहीं पता कि skill अभी भी काम कर रही है या नहीं

Skill का कोई compiler नहीं होता है। यह एक model के लिए दिए गए निर्देश होते हैं, इसलिए यह संभव है कि file byte-for-byte समान रहने के बावजूद skill काम करना बंद कर दे। Model का upgrade यह बदल सकता है कि लंबे निर्देशों का पालन कितनी सटीकता से किया जाता है। Skill जिस command line tool को call करती है, वह किसी flag का नाम बदल सकता है। Reference file में मौजूद कोई URL 404 error देने लग सकता है और agent उस error page के आधार पर काम करने लगता है।

इनमें से किसी भी स्थिति में कोई स्पष्ट विफलता (loud failure) नहीं होती है। Agent अभी भी जवाब देता है। बस फर्क यह है कि जवाब पिछले महीने की तुलना में खराब होता है, जिसे एक-एक pull request के स्तर पर पहचानना बहुत कठिन होता है।

2026 में आने वाले टूल्स किन समस्याओं का समाधान करते हैं

अभी कई उत्तर सामने आ रहे हैं, और वे इस बात पर असहमत हैं कि version को कहाँ रखा जाना चाहिए।

Lockfiles. Vercel Labs का skills कमांड लाइन टूल (vercel-labs/skills, MIT लाइसेंस प्राप्त, 9 अक्टूबर 2026 तक v1.7.2) git रिपॉजिटरी से skills को उस डायरेक्टरी में इंस्टॉल करता है जहाँ आपका agent उन्हें ढूंढता है, और यह सत्तर से अधिक agents के लेआउट को समझता है। npx skills add <repo> इंस्टॉल करता है, npx skills update अपग्रेड करता है, और npx skills list दिखाता है कि आपके पास क्या है। यह दो lock files रखता है। ~/.agents/.skill-lock.json पर एक global फाइल यह रिकॉर्ड करती है कि एक user ने क्या इंस्टॉल किया है। v1.4.1 (20 फरवरी 2026) के बाद से, project scope में इंस्टॉल करने पर यह project root में skills-lock.json भी लिखता है, और टूल के source code के अनुसार इस फाइल को version control में commit किया जाना चाहिए। npx skills experimental_install इससे project की skills को restore करता है। Issue 283, जिसमें किसी दूसरी मशीन पर global lock file को restore करने के लिए skills install कमांड की मांग की गई थी, उसे 5 नवंबर 2026 को 'not planned' के रूप में बंद कर दिया गया; maintainer ने इसे issue 549 के समान अनुरोध बताया है। दोनों को status report के रूप में पढ़ें। Per-project lockfile मौजूद है। इससे restore करने वाली कमांड अभी भी released v1.7.6 में experimental लेबल के साथ है; project की main branch अब npx skills install को भी सपोर्ट करती है, जिसमें project lockfile को restore करने के लिए कोई source नहीं है।

Specs और tests. SkillSpec दूसरा दृष्टिकोण अपनाता है। यह SKILL.md को भरोसेमंद विवरण के बजाय एक contract के रूप में देखता है जिसे जांचना आवश्यक है, जिसका घोषित लक्ष्य skills को "followable, testable, और provable" बनाना है। skillspec doctor <path> रिपोर्ट करता है कि agent के thread छोड़ने की संभावना कहाँ है। skillspec boundary map <path> दिखाता है कि skill में क्या शामिल है, और skillspec boundary assess <path> जोखिम के आधार पर रिपोर्ट करता है कि यह कहाँ तक पहुँच सकता है। यह एक Rust crate है, जो MIT या Apache 2.0 के तहत dual licensed है। Version 0.2.2 को 29 जुलाई 2026 को प्रकाशित किया गया था और 10 अक्टूबर 2026 तक यह crates.io पर सबसे नया है। सबसे नए version के बजाय pinned version इंस्टॉल करें:

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

--locked उन dependency versions के साथ build होता है जिनके साथ crate प्रकाशित किया गया था, ताकि build में कोई बदलाव न आए। skillspec --version को 0.2.2 प्रिंट करना चाहिए। यदि कोई अलग नंबर आता है, तो इसका मतलब है कि आपके PATH में पहले से मौजूद कोई पुराना binary प्रभावी हो रहा है।

Vendor practice. Google ने google/skills में skills को build करने का तरीका how it builds, tests and scales agent skills पोस्ट में बताया है। यदि scale को हटा दिया जाए, तो यह प्रक्रिया सामान्य continuous integration (CI) है। हर skill merge होने से पहले frontmatter metadata, line count, directory layout और naming के लिए linters से गुजरती है। एक link checker किसी भी ऐसे URL पर build को fail कर देता है जो 404 return करता है, जिससे agent द्वारा बनाई गई काल्पनिक लिंक पकड़ी जाती है। लेखकों को skill के साथ एक evaluation prompt suite और scoring rubric प्रदान करना अनिवार्य है। इसके बाद, scheduled evaluation jobs साप्ताहिक रूप से पूरी लाइब्रेरी पर चलाई जाती हैं ताकि regressions को पकड़ा जा सके, और हर skill का एक नामित owner होता है जिससे गुणवत्ता गिरने पर उसे ठीक करने की अपेक्षा की जाती है।

तीनों उत्तरों के पीछे का पैटर्न

आपको इनमें से किसी एक को चुनने की आवश्यकता नहीं है। इनके नीचे एक ही संरचना है, और plain git आपको वह सब कुछ प्रदान करता है।

1. सत्य का एक स्रोत (One source of truth)। कौशल का केवल एक ही स्थान होता है, और प्रत्येक repository कॉपी रखने के बजाय उस स्थान को संदर्भित करती है।
2. प्रति repository एक pinned version। प्रत्येक प्रोजेक्ट उस सटीक revision को रिकॉर्ड करता है जिसका वह उपयोग करता है, इसलिए अपग्रेड करना उस प्रोजेक्ट में एक लेखक और दिनांक के साथ एक commit होता है।
3. प्रति कौशल एक smoke test। एक चलाने योग्य जाँच जो यह सिद्ध करती है कि कौशल अभी भी वही परिणाम देता है जिसका वह वादा करता है।
4. एक समीक्षा पथ (Review path)। साझा कौशल में किया गया कोई भी बदलाव समीक्षा से होकर गुजरता है, और उसे अपनाने से पहले प्रत्येक उपभोक्ता एक diff देखता है।

यह एक dependency का स्वरूप है। कौशल, उनके इर्द-गिर्द टूलिंग विकसित होने की तुलना में अधिक तेजी से साझा artifact बन गए, इसलिए जिस टूलिंग पर आप पहले से भरोसा करते हैं, वही सबसे सुरक्षित विकल्प है।

सेल्फ-होस्टेड git remote पर छोटी टीम के लिए एक लेआउट

एक रिपॉजिटरी में सभी स्किल्स (कौशल) रखे जाते हैं। इसमें अन्य कुछ भी नहीं होता, इसलिए इसका इतिहास निर्देशों के एक चेंजलॉग (changelog) की तरह पढ़ा जाता है।

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

Releases टैग्स होते हैं। Annotated tags का उपयोग करें, क्योंकि इनमें एक संदेश और तारीख होती है। संदेश को इस तरह लिखें कि उपभोक्ता को पता चले कि उसे अपडेट की आवश्यकता क्यों है:

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 कभी इनिशियलाइज़ नहीं हुआ था, इसलिए .claude/skills/api-review किसी भी चीज़ को पॉइंट नहीं करता है और skill चुपचाप लोड नहीं होती है। इसे git submodule update --init के साथ ठीक करें। शुरुआत में + का मतलब है कि चेक-आउट किया गया commit रिकॉर्ड किए गए commit से अलग है, इसलिए वह डेवलपर ऐसे निर्देश चला रहा है जो किसी और के पास नहीं हैं। नए क्लोन के लिए git clone --recurse-submodules की आवश्यकता होती है, और वह लाइन README में होनी चाहिए, क्योंकि एक साधारण क्लोन vendor/agent-skills को खाली छोड़ देता है और कोई त्रुटि नहीं दिखाता है।

अपग्रेड करना एक सोच-समझकर किया गया निर्णय है, और यही इसका मुख्य उद्देश्य है:

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 में फिट बैठता है।

इसके बजाय प्लगइन मार्केटप्लेस के साथ पिनिंग (Pinning)

यदि आप हर डेवलपर को submodules सीखने के लिए नहीं कहना चाहते हैं, तो Claude Code प्लगइन सिस्टम आपके लिए वितरण का कार्य करता है, और यह एक self-hosted remote के साथ काम करता है। 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 पिन कैटलॉग प्रविष्टि (entry) में होता है। प्रकार के नाम भी अलग-अलग हैं। कैटलॉग के अंदर, url का अर्थ है क्लोन करने के लिए एक git रिपॉजिटरी। मार्केटप्लेस स्रोत में, url का अर्थ है marketplace.json फ़ाइल का सीधा लिंक, और git रिपॉजिटरी git है।

प्रत्येक उपभोग करने वाली (consuming) रिपॉजिटरी फिर अपने कमिट किए गए .claude/settings.json में मार्केटप्लेस घोषित करती है:

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

Claude Code टीम के सदस्य के लिए मार्केटप्लेस को तब रजिस्टर करता है जब वे प्रोजेक्ट फ़ोल्डर के लिए workspace trust डायलॉग को स्वीकार कर लेते हैं, इसके लिए उन्हें बताने वाले किसी wiki पेज की आवश्यकता नहीं होती है। कैटलॉग प्रविष्टि एक relative path के बजाय एक git URL की ओर इशारा करती है, इसलिए प्लगइन केवल रिपॉजिटरी की सेटिंग्स से इंस्टॉल नहीं होता है। प्रत्येक टीम सदस्य एक बार claude plugin install team-skills@acme-agents --scope project चलाता है, और तब तक Claude Code रिपोर्ट करता है कि प्लगइन प्रोजेक्ट सेटिंग्स में सक्षम है लेकिन इंस्टॉल नहीं है। स्किल्स फिर /team-skills:api-review का उत्तर देती हैं, क्योंकि प्लगइन स्किल्स प्लगइन नाम द्वारा namespaced होती हैं और उसी नाम की प्रोजेक्ट स्किल के साथ टकरा नहीं सकती हैं। एक नया tag push करने के बाद, उपभोक्ता /plugin marketplace update acme-agents के साथ रिफ्रेश करते हैं, फिर यदि इंस्टॉल सारांश (summary) ऐसा करने के लिए कहता है तो /reload-plugins चलाते हैं।

एक skill के लिए smoke test लिखना

Smoke test एक scripted agent run है जिसे एक ज्ञात fault वाले fixture पर चलाया जाता है, जिसमें एक assertion शामिल होता है। Claude Code -p के साथ non-interactively चलता है, और वहाँ एक user-invoked skill काम करती है: prompt string में /skill-name डालें और run शुरू होने से पहले यह expand हो जाता है।

#!/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 एक छोटी file है जिसमें एक जानबूझकर डाली गई fault है। Assertion यह है कि skill इसका नाम बताए। jq -e तब non-zero exit देता है जब उसका filter null उत्पन्न करता है, इसलिए जो skill seeded fault को पकड़ना बंद कर देती है, वह script को fail कर देती है। claude स्वयं non-zero exit देता है जब run fail होता है, और set -euo pipefail किसी भी विफलता को failed test में बदल देता है।

एक model runs के बीच अपने उत्तरों को reword करता है, इसलिए कभी भी पूरे वाक्य पर assert न करें। उस identifier पर assert करें जिसे skill को emit करना चाहिए, या उस schema के field पर जिसे आपने माँगा है, और fixture को छोटा रखें ताकि run सस्ता बना रहे।

CI में, --bare जोड़ें। इसके बिना, claude -p वही context load करता है जो एक interactive session करती, जिसमें उस machine के hooks, plugins और CLAUDE.md शामिल हैं जिस पर यह चलता है, इसलिए किसी teammate का personal configuration परिणाम बदल सकता है। Bare mode auto-discovery को छोड़ देता है, सिवाय उन skills के जो .claude/skills/ में उस directory के तहत हों जिसे --add-dir के साथ स्पष्ट रूप से प्रदान किया गया हो; यह उस project skill को छोड़ देता है जिसे आप यहाँ test कर रहे हैं, इसलिए उसे स्पष्ट रूप से load करें। Bare mode आपके subscription login को भी नहीं पढ़ता है, इसलिए environment में पहले ANTHROPIC_API_KEY set करें:

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

--plugin-dir के साथ load किया गया plugin अपना नाम .claude-plugin/plugin.json से लेता है, और उस manifest के बिना इसका नाम इसकी directory के आधार पर रखा जाता है। Skills repository में catalog के बगल में "name": "team-skills" के साथ एक plugin.json commit करें, अन्यथा ऊपर दिए गए command को इसके बजाय /agent-skills:api-review call करना होगा।

--output-format stream-json के साथ, system/init event report करता है कि कौन से plugins load हुए और उन plugins के लिए एक plugin_errors array ले जाता है जो load नहीं हुए। यह stream को खोलता है जब तक कि startup events पहले न आ जाएँ। एक non-empty plugin_errors पर CI job को fail करें। यह उस pin को पकड़ लेता है जो ऐसे revision पर लक्षित है जो अब मौजूद नहीं है, जो अन्यथा एक ऐसे agent के रूप में दिखाई देता है जो चुपचाप आपके house rules को अनदेखा कर रहा है।

साझा किया गया skill एक निष्पादन योग्य निर्देश है

दो विशेषताएँ इसे शाब्दिक रूप देती हैं, और जब फ़ाइल किसी अन्य टीम से आती है तो ये दोनों महत्वपूर्ण होती हैं।

सबसे पहले, एक SKILL.md मॉडल द्वारा कुछ भी पढ़ने से पहले shell commands चला सकता है। बॉडी में इस तरह की एक पंक्ति preprocessing है:

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

यह command उस मशीन पर चलती है जो skill को लोड कर रही है, और इसका आउटपुट उस टेक्स्ट में placeholder की जगह ले लेता है जिसे मॉडल प्राप्त करता है। तीन backticks के बाद ! के साथ खोला गया एक fenced block उसी तरह कई commands चलाता है। रन टाइम पर इसके लिए किसी को भी प्रॉम्प्ट नहीं किया जाता है। Claude Code प्रत्येक command की जाँच आपके permission rules के आधार पर करता है। ऑटो मोड के बाहर, यदि कोई command उन नियमों द्वारा अनुमत नहीं है, तो वह skill को abort कर देता है, जब तक कि skill नीचे दी गई दूसरी विशेषता के माध्यम से उसे पहले से approve न कर दे। Deny और ask नियम अभी भी उस पूर्व-अनुमोदन (pre-approval) को ओवरराइड करते हैं। साझा किए गए skill को पढ़ने का अर्थ है उसके command substitutions को पढ़ना।

दूसरा, frontmatter टूल को पहले से approve कर सकता है। allowed-tools उस टर्न के लिए बिना किसी permission prompt के सूचीबद्ध टूल प्रदान करता है जिसने skill को इनवोक किया है। Workspace trust इस अनुदान को नियंत्रित नहीं करता है: Claude Code एक प्रोजेक्ट skill के allowed-tools को उस फोल्डर में भी लागू करता है जिसे किसी ने ट्रस्ट नहीं किया है, यदि वह -p में चलाया गया हो। Claude Code का डॉक्यूमेंटेशन इसके परिणाम को स्पष्ट रूप से बताता है: एक skill खुद को व्यापक टूल एक्सेस दे सकता है, इसलिए किसी रिपॉजिटरी में Claude Code चलाने से पहले वहाँ चेक-इन किए गए skills के allowed-tools की समीक्षा करें। एक संगठन managed settings में allowManagedPermissionRulesOnly सेट करके प्रोजेक्ट और पर्सनल skills से इस फ़ील्ड को रोक सकता है, जिसके लिए Claude Code v2.1.282 या बाद का वर्शन आवश्यक है।

इसलिए skill bump को बिल्कुल dependency bump की तरह ही संभालें। जहाँ भी मैकेनिज्म अनुमति दे, exact commit द्वारा पिन करें, क्योंकि एक tag को मूव किया जा सकता है और एक branch परिभाषा के अनुसार मूव होती ही है। एक लॉक-डाउन मशीन पर, settings में "disableSkillShellExecution": true हर command substitution को चलाने के बजाय उसे literal text [shell command execution disabled by policy] से बदल देता है, और managed settings के माध्यम से लागू होने पर कोई उपयोगकर्ता इसे ओवरराइड नहीं कर सकता है। Bundled और managed skills इस सेटिंग से मुक्त हैं।

वही सावधानी इस बात पर भी लागू होती है कि एक skill क्या पढ़ता है। एक skill जो env चलाता है या कोई config फ़ाइल खोलता है, वह जो कुछ भी पाता है उसे मॉडल के कॉन्टेक्स्ट में खींच लेता है, जो कि keeping secrets out of the agents you run में कवर की गई विफलता है। एक skill जो कोई पेज फ़ेच करता है या क्वेरी चलाता है, वह बाहर की ओर इंगित वही एक्सपोज़र है, क्योंकि प्राप्त टेक्स्ट कॉन्टेक्स्ट में बिल्कुल वैसे ही दिखाई देता है जैसे आपके द्वारा लिखे गए निर्देश, एक ऐसी सीमा जिसके बारे में आपको point an agent at your own SearXNG instance for web search करने से पहले पढ़ना चाहिए।

वर्जन अपडेट होने पर क्या पढ़ें

• हर SKILL.md बॉडी का diff, क्योंकि वह टेक्स्ट ही वह निर्देश है जिसका पालन आपका एजेंट करेगा।
• हर कमांड सब्स्टीट्यूशन, क्योंकि स्किल लोड होने पर वे आपकी मशीन पर चलते हैं।
• allowed-tools में कोई भी बदलाव, क्योंकि वह लाइन बिना प्रॉम्प्ट के टूल्स की अनुमति देती है।
• टैग के पीछे का टेस्ट रन। यदि साझा रिपॉजिटरी CI में अपने स्वयं के स्मोक टेस्ट चलाती है, तो जिस टैग को आप पिन कर रहे हैं, उसके साथ एक सफल (green) रन जुड़ा होना चाहिए।

जो समीक्षक दस मिनट में पूरा diff नहीं पढ़ सकता, वह ऐसी स्किल देख रहा है जो बहुत बड़ी हो गई है। इसे विभाजित करें। यही तर्क उन रिपॉजिटरी दस्तावेजों पर भी लागू होता है जिन्हें आपके एजेंट पढ़ते हैं: स्थायी नियमों को AGENTS.md और HUMAN.md विभाजन में वर्णित फाइलों में रखें और आर्किटेक्चर संबंधी तर्क को एजेंटों के लिए लिखे गए DESIGN.md में रखें, और स्किल्स को सीमित प्रक्रियाओं तक ही रहने दें।

जब कोई मॉडल या टूल परिवर्तन किसी स्किल को खराब कर देता है

किसी स्किल को बिना एडिट किए भी उसके पीछे कई चीजें बदल जाती हैं। मॉडल अपग्रेड होने से लंबे निर्देशों का पालन करने की विश्वसनीयता बदल जाती है, इसलिए जो स्किल पहले नौवें चरण तक पहुँचने के लिए मॉडल पर निर्भर थी, वह अब वहाँ तक नहीं पहुँच पाती। एक कमांड लाइन टूल किसी फ्लैग का नाम बदल देता है, जिससे एजेंट पुराना फ्लैग चलाता है, एरर पढ़ता है और फिर खुद से सुधार (improvise) करता है। एक रेफरेन्स्ड URL 404 एरर देने लगता है। एजेंट हार्नेस के स्किल चुनने का तरीका बदल जाता है, जिससे वह description जो पहले मैच जीत जाता था, अब नहीं जीत पाता। जब कोई प्रक्रिया इस तरह समय से पहले समाप्त होने लगे, तो कोई भी वर्जन बंप इसे ठीक नहीं कर सकता; निर्देशों को ऐसी संरचना की आवश्यकता होती है जो अंतिम चरणों को पूरा करने के लिए मजबूर करे, और यही दृष्टिकोण the unlazy skill and its Depth Tree method के पीछे है।

यही कारण है कि इस व्यवस्था में स्मोक टेस्ट का बहुत महत्व है। प्रत्येक स्किल के टेस्ट को शेड्यूल के अनुसार और पुश करने पर चलाएं। गूगल इसी कारण से पूरी लाइब्रेरी पर साप्ताहिक मूल्यांकन जॉब्स चलाता है, और दस स्किल्स वाली टीम के लिए एक छोटे VPS पर साप्ताहिक क्रॉन जॉब पर्याप्त है। डेवलपर को पता चलने से पहले ही खराबी के बारे में जानने का यही एकमात्र तरीका है।

पोर्टेबिलिटी भी मदद करती है। Agent Skills स्पेक फ्रंटमैटर को छह कीज़ (keys) तक सीमित रखता है, इसलिए उस स्पेक पर लिखी गई स्किल उन टूल्स में भी लोड हो जाती है जिनके लिए आपने उसे नहीं लिखा था, जबकि आपके द्वारा जोड़ी गई हर हार्नेस-विशिष्ट की एक वेंडर पर दांव लगाने जैसा है। मॉडल स्वैप के बाद भी काम करने वाली स्किल्स लिखना अपने आप में एक अनुशासन है, जिसे making a skill work on any model में कवर किया गया है।

FAQ

मैं एक agent skill को कई repositories के बीच कैसे साझा करूँ?

Skill को एक समर्पित git repository में रखें, उसमें releases को tag करें, और प्रत्येक consuming project में फ़ाइल को कॉपी करने के बजाय एक tag का संदर्भ (reference) दें। दो तरीके काम करते हैं। एक git submodule सटीक commit को रिकॉर्ड करता है, और .claude/skills/<name> से एक symlink उसे submodule में एक सामान्य project skill के रूप में लोड कर देता है। एक plugin marketplace /plugin के माध्यम से यही काम करता है, जिसमें pin को consuming repository की .claude/settings.json में घोषित किया जाता है। दोनों ही version को git history में रखते हैं, ताकि आप यह बता सकें कि किन निर्देशों ने एक विशिष्ट agent run को उत्पन्न किया।

क्या मैं किसी agent skill को एक विशिष्ट version पर pin कर सकता हूँ?

SKILL.md के अंदर से ऐसा नहीं किया जा सकता, क्योंकि उस frontmatter में कोई version key नहीं होती। Pin को फ़ाइल के चारों ओर की परत (layer) से आना चाहिए। एक git submodule डिफ़ॉल्ट रूप से एक सटीक commit को pin करता है। Claude Code plugin marketplace में, एक plugin source branch या tag के लिए ref और सटीक commit के लिए sha स्वीकार करता है, और दोनों के मौजूद होने पर sha प्रभावी होता है। Marketplace source स्वयं केवल ref स्वीकार करता है। Commit pin को प्राथमिकता दें, क्योंकि आपके द्वारा review किए जाने के बाद tag को बदला जा सकता है।

एक skill smoke test को किन बातों की पुष्टि (assert) करनी चाहिए?

किसी स्थिर (stable) चीज़ पर पुष्टि करें। Skill को एक ऐसे fixture के विरुद्ध non-interactively चलाएं जिसमें एक ज्ञात दोष (fault) हो, फिर जांचें कि output में एक विशिष्ट identifier दिखाई देता है, उदाहरण के लिए वह rule id जिसे skill को रिपोर्ट करना चाहिए। --output-format json और --json-schema के साथ structured output का अनुरोध करने से जांच सटीक हो जाती है, और मान (value) न मिलने पर jq -e script को fail कर देता है। कभी भी पूरे वाक्य पर पुष्टि न करें, क्योंकि model हर run के बीच अपने उत्तरों को फिर से लिखता है।

क्या किसी दूसरी टीम की repository से shared skill इंस्टॉल करना सुरक्षित है?

इसे एक code dependency के रूप में मानें, क्योंकि यह निष्पादन योग्य निर्देश (executable instruction) है। एक SKILL.md, ! command substitution form के माध्यम से load होने के समय shell commands चला सकता है, और frontmatter का allowed-tools field बिना किसी prompt के tools को pre-approve कर सकता है। हर update पर diff पढ़ें, branch के बजाय एक सटीक commit पर pin करें, और उस source को प्राथमिकता दें जिसे आपकी अपनी टीम नियंत्रित करती है। Managed machines पर, settings में "disableSkillShellExecution": true user, project, plugin और additional-directory skills में command substitutions को चलने से रोकता है; bundled और managed skills इससे मुक्त हैं।

क्या एक shared skill, Claude Code के अलावा अन्य agents में काम करेगी?

यह इस पर निर्भर करता है कि आप कौन सा frontmatter उपयोग करते हैं। Agent Skills spec छह keys को परिभाषित करता है: name, description, license, compatibility, metadata और allowed-tools। उन तक सीमित skill उन tools में लोड हो जाती है जो spec को लागू करते हैं, और यह बिना किसी बदलाव के Claude Code में भी लोड हो जाती है। Harness-विशिष्ट keys और spec से परे body features को अन्य जगहों पर अनदेखा या अस्वीकार कर दिया जाता है, इसलिए उन्हें किसी भी ऐसी skill से दूर रखें जिसे आप व्यापक रूप से साझा करना चाहते हैं।