एजेंट स्किल्स को अलग रिपॉजिटरीज में कैसे साझा करें

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

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

इसके चार भाग हैं: एक साझा सत्य का स्रोत (shared source of truth), प्रति रिपॉजिटरी एक पिन किया गया वर्जन, प्रति स्किल एक स्मोक टेस्ट, और एक समीक्षा प्रक्रिया। नीचे दी गई जानकारी बताती है कि प्रत्येक भाग क्यों आवश्यक है, 2026 में रिलीज होने वाले टूल्स इसके बारे में क्या करते हैं, और बिना किसी बाहरी सर्विस के, सेल्फ-होस्टेड git रिमोट पर इसे कैसे बनाया जाए।

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

स्किल कहाँ रहती है, और साझा करना कठिन क्यों है

Claude Code तीन स्थानों से स्किल्स लोड करता है, और स्किल डॉक्यूमेंटेशन में प्रत्येक पाथ का नाम दिया गया है।

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

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

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

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

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

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

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

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

समस्या दो: किसी भी version को पिन न करना

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

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

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

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

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

What the tools shipping in 2026 solve

Several answers are landing right now, and they disagree about where the version should live.

Lockfiles. The skills command line tool from Vercel Labs (vercel-labs/skills, MIT licensed, v1.5.22 as of 5 August 2026) installs skills from a git repository into whichever directory your agent expects, and it knows the layout for more than seventy agents. npx skills add <repo> installs, npx skills update upgrades, and npx skills list shows what you have. The record of what is installed is kept once per user rather than once per repository, and an open request on that project (issue 283) asks for a skills install command that reinstalls every tracked skill from the lock file so a second machine ends up with the same set. Read that request as a status report. The lockfile idea is settled. The per-project half of it is still being built.

Specs and tests. SkillSpec takes the other angle. It treats a SKILL.md as a contract to check rather than prose to trust, with the stated goal of making skills "followable, testable, and provable". skillspec doctor <path> reports where an agent is likely to drop the thread. skillspec boundary map <path> reports what the skill can reach, and skillspec boundary assess <path> ranks those findings by risk. It is a Rust crate, dual licensed MIT or Apache 2.0, at version 0.2.2 as of 29 July 2026. Install the pinned version rather than the newest one:

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

--locked builds with the dependency versions the crate was published with, so the build does not drift under you. skillspec --version should print 0.2.2. A different number means an older binary earlier in your PATH is winning.

Vendor practice. Google described how it builds the skills in google/skills in a post on how it builds, tests and scales agent skills. Strip away the scale and the mechanism is ordinary continuous integration (CI). Every skill passes linters for frontmatter metadata, line count, directory layout and naming before it merges. A link checker fails the build on any URL that returns 404, which catches the plausible link an agent invented. Authors must supply an evaluation prompt suite and a scoring rubric alongside the skill. Scheduled evaluation jobs then run weekly against the whole library to catch regressions, and every skill has a named owner who is expected to fix it when quality drops.

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

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

1. सत्य का एक स्रोत। कौशल का केवल एक ही स्थान होता है, और प्रत्येक repository प्रतिलिपि रखने के बजाय उस स्थान को संदर्भित करती है।
2. प्रति repository एक pinned version। प्रत्येक project उस सटीक revision को रिकॉर्ड करता है जिसका वह उपयोग करता है, इसलिए अपग्रेड करना उस project में एक commit है जिसमें एक लेखक और एक तारीख होती है।
3. प्रति कौशल एक smoke test। एक runnable जांच जो यह साबित करती है कि कौशल अभी भी वही परिणाम देता है जिसका वह वादा करता है।
4. एक review path। साझा कौशल में किया गया बदलाव review से होकर गुजरता है, और उसे अपनाने से पहले प्रत्येक consumer एक diff देखता है।

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

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

एक रिपॉजिटरी में सभी स्किल्स (skills) मौजूद रहती हैं। इसमें अन्य कुछ भी नहीं रखा जाता है, इसलिए इसका इतिहास निर्देशों के एक चेंजलॉग (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 का उपयोग करें, क्योंकि इनमें एक संदेश और तारीख होती है। संदेश को इस तरह लिखें कि उपभोक्ता को पता चले कि उसे यह अपडेट क्यों चाहिए:

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

यदि आपका रिमोट Gitea, Forgejo, GitLab या आपके अपने VPS पर SSH के माध्यम से एक bare रिपॉजिटरी है, तो नीचे दी गई किसी भी बात में कोई बदलाव नहीं होगा। यहाँ सब कुछ git और एक symlink का संयोजन है।

git submodule के साथ पिनिंग (Pinning)

एक submodule आपके रिपॉजिटरी के भीतर किसी अन्य रिपॉजिटरी के एक सटीक commit को रिकॉर्ड करता है। वह रिकॉर्ड ही पिन (pin) है। प्रत्येक consuming project में:

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 उसका अनुसरण करता है और target से 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 के साथ ठीक करें। शुरुआत में + का मतलब है कि checked-out commit रिकॉर्ड किए गए commit से अलग है, इसलिए वह डेवलपर ऐसे निर्देश चला रहा है जो किसी और के पास नहीं हैं। नए clones को 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 लाइन रिव्यू पाथ है। यह वही बदलाव दिखाती है जो अन्य सभी consuming repos देखेंगे, और यह pull request में फिट बैठती है।

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

यदि आप हर डेवलपर को 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 पिन कैटलॉग प्रविष्टि में होता है।

प्रत्येक उपभोग करने वाली रिपॉजिटरी फिर अपने कमिट किए गए .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 चलाएं।

एक 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 एक छोटी फाइल है जिसमें एक जानबूझकर डाली गई 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 हर run के बीच अपने उत्तरों को बदल देता है, इसलिए कभी भी पूरे वाक्य पर assertion न करें। उस identifier पर assertion करें जिसे 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 को छोड़ देता है, जिसका अर्थ है कि यह उस skill को भी छोड़ देता है जिसका आप परीक्षण कर रहे हैं, इसलिए उसे explicitly load करें। Bare mode आपके subscription login को भी नहीं पढ़ता है, इसलिए environment में पहले 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 के साथ, run का पहला event यह रिपोर्ट करता है कि कौन से plugins load हुए और जो नहीं हुए उनके लिए एक plugin_errors array ले जाता है। एक non-empty plugin_errors पर CI job को fail करें। यह उस pin को पकड़ लेता है जो ऐसी revision पर लक्षित है जो अब मौजूद नहीं है, जो अन्यथा एक ऐसे agent के रूप में दिखाई देता है जो चुपचाप आपके house rules को अनदेखा कर रहा है।

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

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

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

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

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

दूसरा, फ्रंटमैटर टूल को पहले से स्वीकृत कर सकता है। allowed-tools उस टर्न के लिए बिना किसी अनुमति प्रॉम्प्ट के सूचीबद्ध टूल प्रदान करता है जिसने skill को इनवोक किया है। प्रोजेक्ट skill के लिए, वह अनुदान तब प्रभावी होता है जब कोई फ़ोल्डर के लिए वर्कस्पेस ट्रस्ट डायलॉग को स्वीकार करता है। Claude Code का दस्तावेज़ीकरण इसके परिणाम को स्पष्ट रूप से बताता है: रिपॉजिटरी पर भरोसा करने से पहले प्रोजेक्ट skill की समीक्षा करें, क्योंकि एक skill खुद को व्यापक टूल एक्सेस प्रदान कर सकता है।

इसलिए skill अपडेट को बिल्कुल dependency अपडेट की तरह संभालें। जहाँ भी तंत्र इसकी अनुमति देता है, सटीक कमिट (commit) द्वारा पिन करें, क्योंकि एक टैग को स्थानांतरित किया जा सकता है और एक ब्रांच परिभाषा के अनुसार बदलती रहती है। एक लॉक-डाउन मशीन पर, सेटिंग्स में "disableSkillShellExecution": true कमांड चलाने के बजाय हर कमांड प्रतिस्थापन को शाब्दिक टेक्स्ट [shell command execution disabled by policy] से बदल देता है, और प्रबंधित सेटिंग्स के माध्यम से लागू होने पर उपयोगकर्ता इसे ओवरराइड नहीं कर सकता है। बंडल और प्रबंधित skill इस सेटिंग से मुक्त हैं।

वही सावधानी इस बात पर लागू होती है कि एक skill क्या पढ़ता है। एक skill जो env चलाता है या कॉन्फ़िगरेशन फ़ाइल खोलता है, वह जो कुछ भी पाता है उसे मॉडल के संदर्भ में खींच लेता है, जो कि आपके द्वारा चलाए जाने वाले एजेंटों से secrets को दूर रखना में कवर की गई विफलता है।

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

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

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

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

किसी स्किल को संपादित किए बिना भी उसके अंतर्गत कई चीजें बदल जाती हैं। एक मॉडल अपग्रेड इस बात को बदल देता है कि लंबे निर्देशों का पालन कितनी विश्वसनीयता के साथ किया जाता है, इसलिए जो स्किल पहले मॉडल के नौवें चरण तक पहुँचने पर निर्भर थी, वह अब वहाँ तक पहुँचना बंद कर सकती है। एक कमांड लाइन टूल किसी फ्लैग का नाम बदल देता है, इसलिए एजेंट पुराने फ्लैग को चलाता है, त्रुटि को पढ़ता है और फिर सुधार (improvise) करता है। एक संदर्भित URL 404 त्रुटि देना शुरू कर देता है। एक एजेंट हार्नेस स्किल चुनने के अपने तरीके को बदल देता है, इसलिए जो description पहले मैच जीतता था, वह अब नहीं जीत पाता।

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

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

FAQ

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

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

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

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

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

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

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