Agent Skills: .claude/skills और .agents/skills कैसे सेट करें

अगर एक ही रिपॉज़िटरी पर Claude Code, Codex, Cursor और Gemini CLI से काम होता है, तो साझा स्किल फ़ाइलें .agents/skills/<skill-name>/ में रखें। हर स्किल के लिए .claude/skills/ के अंदर एक सापेक्ष सिंबॉलिक लिंक बनाएँ, ताकि Claude Code भी उसी डायरेक्टरी को पढ़ सके। पूरी टीम में यह संरचना अपनाने से पहले हर क्लाइंट में जाँचें कि स्किल मिल रही है और उसे चलाया जा सकता है।

इस व्यवस्था में काम के निर्देशों की एक ही कॉपी संपादित करनी पड़ती है, जबकि अलग-अलग क्लाइंट अपने खोज-नियमों के अनुसार उसे पढ़ सकते हैं। अगर आपकी टीम केवल Claude Code इस्तेमाल करती है, तो मौजूदा .claude/skills/ संरचना रख सकती है। डायरेक्टरी बदलना तभी उपयोगी है जब वही स्किल किसी दूसरे क्लाइंट में भी चाहिए।

क्या AAIF ने डायरेक्टरी का नाम मानक बना दिया है?

मानक AAIF के अंतर्गत है, लेकिन स्किल कहाँ खोजनी है, यह हर क्लाइंट खुद तय करता है। Anthropic ने 22 अक्टूबर 2026 को इसे दान करने की घोषणा की, और फ़ाउंडेशन ने Agent Skills को अपनी परियोजनाओं में शामिल किया।

क्लाइंट में स्किल सपोर्ट जोड़ने की गाइड साफ़ कहती है कि स्किल की डायरेक्टरी कहाँ रखी जाए, यह विनिर्देश की शर्त नहीं है। अलग-अलग टूल में इस्तेमाल आसान बनाने के लिए वह क्लाइंट की अपनी डायरेक्टरी के साथ .agents/skills/ पर भी विचार करने की सलाह देती है। इस सलाह का अर्थ यह नहीं है कि हर मौजूदा क्लाइंट इस पाथ को स्कैन करता है।

एक क्लाइंट से दूसरे में ले जाने योग्य इकाई एक डायरेक्टरी है, जिसमें SKILL.md, शुरुआत में YAML मेटाडेटा और Markdown में निर्देश होते हैं। फ़ॉर्मैट के विनिर्देश के अनुसार name और description ज़रूरी हैं; अतिरिक्त संसाधन भी साथ रखे जा सकते हैं। स्किल बुलाने का तरीका, स्क्रिप्ट चलाने का रनटाइम और अनुमतियाँ अभी भी क्लाइंट पर निर्भर हैं। खास तौर पर allowed-tools अभी प्रयोगात्मक है और उसका समर्थन अलग-अलग है, इसलिए उसे सभी क्लाइंट में एक जैसी अनुमति-नीति नहीं माना जा सकता।

चारों टूल किन पाथ पर स्किल खोजते हैं?

नीचे आधिकारिक दस्तावेज़ों में दिए गए लोकल खोज-पाथ इस्तेमाल करें। इस गाइड के पाथ और नियंत्रण 2026-10-26 की आधिकारिक जानकारी पर आधारित हैं; यहाँ दी गई संरचना बनाने के लिए हर पाथ के आगे <skill-name>/SKILL.md जोड़ें।

टूल	रिपॉज़िटरी के खोज-पाथ	उपयोगकर्ता के खोज-पाथ	साझा रिपॉज़िटरी के लिए विकल्प
Claude Code	.claude/skills/	~/.claude/skills/	हर स्किल के लिए .claude/skills/ से साझा डायरेक्टरी तक लिंक बनाएँ।
Codex CLI और IDE एक्सटेंशन	.agents/skills/	~/.agents/skills/	साझा डायरेक्टरी सीधे पढ़ें।
Cursor Agent	.agents/skills/, .cursor/skills/; संगतता के लिए .claude/skills/ और .codex/skills/ भी	यही चार डायरेक्टरी नाम ~/ के अंदर	.agents/skills/ इस्तेमाल करें; Cursor के लिए अतिरिक्त लिंक नहीं चाहिए।
Gemini CLI	.agents/skills/ और .gemini/skills/	~/.agents/skills/ और ~/.gemini/skills/	.agents/skills/ सीधे पढ़ें। एक ही दायरे में इसे .gemini/skills/ से अधिक प्राथमिकता मिलती है।

Claude Code की वर्तमान गाइड में .agents/skills/ से सीधे स्किल खोजने का उल्लेख नहीं है, और फ़ीचर अनुरोध #31005 अभी खुला है। वहीं, ऊपर दिए गए Codex और Gemini के दस्तावेज़ .claude/skills/ को खोज-पाथ में शामिल नहीं करते। दस्तावेज़ों में बताए गए पाथ इस्तेमाल करें; दोनों डायरेक्टरी को सभी क्लाइंट में एक-दूसरे का विकल्प न मानें।

ये लोकल खोज-पाथ हैं। आपके लैपटॉप की होम डायरेक्टरी में रखी स्किल किसी रिमोट वर्कर या नए कंटेनर में अपने-आप उपलब्ध नहीं होती। उस वातावरण तक भी फ़ाइलें पहुँचानी होंगी।

एक साझा स्किल और Claude Code के लिए लिंक बनाएँ

पूरी स्किल .agents/skills/ में रखें और उसके पूरे फ़ोल्डर का लिंक बनाएँ, ताकि बाद में जोड़ी गई स्क्रिप्ट या संदर्भ फ़ाइलें भी साथ उपलब्ध हों। हर स्किल का अलग लिंक रखने से मौजूदा Claude-विशिष्ट स्किल के लिए भी जगह बनी रहती है।

शुरू करने से पहले Git और ऐसा इंस्टॉल किया हुआ क्लाइंट चाहिए जिसमें आप लॉग इन कर चुके हों और जो रिपॉज़िटरी में पहले से काम कर सके। फ़ाइल सिस्टम की इस सेटिंग के लिए नए API क्रेडेंशियल की ज़रूरत नहीं है; क्लाइंट तक पहुँच और टूल की सामान्य अनुमति-शर्तें लागू रहेंगी।

अलग-अलग क्लाइंट में इस्तेमाल होने वाली स्किल लिखें

अपने एडिटर में .agents/skills/review-staged/SKILL.md बनाएँ। ज़रूरत हो तो उसकी पैरेंट डायरेक्टरी भी बनाएँ। अगर इस नाम की स्किल पहले से मौजूद है, तो दूसरा नाम चुनें और डायरेक्टरी, शुरुआती मेटाडेटा तथा कमांड में उसे हर जगह एक जैसा बदलें।

फ़ाइल में यह पूरा पाठ पेस्ट करें:

---
name: review-staged
description: "Review staged Git changes for correctness before a commit. Use when the user asks to review the Git index or staged changes."
---

Begin the answer with `Skill loaded: review-staged`.

1. Locate the repository root with `git rev-parse --show-toplevel`.
   Run all following commands from that directory.
2. Run `git diff --cached --name-only`. If it prints no paths,
   report `No staged changes.` and stop.
3. Run `git diff --cached --check` and `git diff --cached --`.
   Treat a nonzero `--check` exit as evidence to report, not a reason
   to skip reading the diff.
4. Read relevant files as needed. Report concrete correctness issues
   with file and line references. Separate confirmed issues from questions.
5. Finish with suggested verification commands. Do not claim they ran.

Do not edit files, stage changes, or create a commit.

यह प्रक्रिया Git इंडेक्स की समीक्षा करती है, यानी अगले कमिट के लिए तैयार किए गए बदलावों की। Git के diff संदर्भ में इस तुलना के लिए --cached और व्हाइटस्पेस की त्रुटियों व कॉन्फ़्लिक्ट मार्कर की जाँच के लिए --check दिया गया है। उदाहरण एजेंट से सामान्य कमांड चलाने को कहता है; यह किसी खास क्लाइंट की प्रॉम्प्ट में कमांड का परिणाम जोड़ने वाली सुविधा पर निर्भर नहीं है।

macOS या Linux में Bash से लिंक जोड़ें

इस स्किल के लिए सापेक्ष सिंबॉलिक लिंक, यानी दूसरे फ़ोल्डर की ओर इशारा करने वाला लिंक, बनाएँ। Claude Code के दस्तावेज़ स्पष्ट रूप से सिंबॉलिक लिंक वाली स्किल डायरेक्टरी का समर्थन बताते हैं।

संबंधित Git रिपॉज़िटरी के किसी भी अंदरूनी स्थान से यह ब्लॉक Bash में चलाएँ:

(
  set -eu
  cd "$(git rev-parse --show-toplevel)"
  test -f .agents/skills/review-staged/SKILL.md
  mkdir -p .claude/skills

  skill_link=.claude/skills/review-staged
  if [ -e "$skill_link" ] || [ -L "$skill_link" ]; then
    printf '%s\n' "Already exists: $skill_link" >&2
    exit 1
  fi

  ln -s ../../.agents/skills/review-staged "$skill_link"
  test -L "$skill_link"
  test -f "$skill_link/SKILL.md"
  readlink "$skill_link"
)

अपेक्षित आउटपुट ../../.agents/skills/review-staged है और एग्ज़िट स्टेटस 0 होना चाहिए। दोनों .. हिस्से लिंक की पैरेंट डायरेक्टरी, .claude/skills/, के सापेक्ष हैं और रिपॉज़िटरी के रूट तक वापस ले जाते हैं।

अगर लिंक बनाने वाला पाथ पहले से मौजूद है, तो कोई बदलाव करने से पहले उसे देखें। सही लिंक मौजूद हो तो उसे रखें; वहाँ वास्तविक स्किल डायरेक्टरी हो तो उसकी सामग्री को मुख्य कॉपी से मिलाकर सोच-समझकर एक करें। कमांड किसी मौजूदा डायरेक्टरी या ऐसे लिंक को नहीं बदलती जिसका लक्ष्य मौजूद नहीं है।

Windows में यही लिंक बनाएँ

नीचे दिया गया सापेक्ष डायरेक्टरी लिंक बनाने के लिए PowerShell 7.1 या बाद का संस्करण इस्तेमाल करें। Microsoft के New-Item दस्तावेज़ में यह संस्करण-शर्त दी गई है। Windows में सिंबॉलिक लिंक बनाने के लिए आमतौर पर एडमिन अधिकार या समर्थित Windows संस्करण में चालू Developer Mode चाहिए।

मुख्य SKILL.md फ़ाइल सेव करने के बाद रिपॉज़िटरी के रूट से यह चलाएँ:

New-Item -ItemType Directory -Force -Path '.claude/skills' -ErrorAction Stop | Out-Null
Push-Location '.claude/skills' -ErrorAction Stop
try {
    New-Item -ItemType SymbolicLink -Path 'review-staged' `
        -Target '../../.agents/skills/review-staged' -ErrorAction Stop | Out-Null
    Get-Item 'review-staged' | Select-Object LinkType, Target
    Test-Path 'review-staged/SKILL.md' -PathType Leaf
}
finally {
    Pop-Location
}

LinkType का मान SymbolicLink और फ़ाइल की जाँच का परिणाम True होना चाहिए। अगर अधिकारों की कमी के कारण लिंक न बने, तो अपने संगठन की स्वीकृत प्रक्रिया से Developer Mode या एडमिन अधिकारों वाला सेटअप इस्तेमाल करें।

यह न मानें कि Windows का सामान्य Git Bash, Linux जैसा ही काम करेगा: Git for Windows के दस्तावेज़ बताते हैं कि डिफ़ॉल्ट रूप से ln -s कॉपी बनाता है। PowerShell वाला तरीका अपनाएँ और बने हुए लिंक की जाँच करें।

क्लोन करने के बाद एक अलग समस्या आ सकती है। core.symlinks=false होने पर Git सिंबॉलिक लिंक को एक सामान्य फ़ाइल के रूप में चेकआउट करता है, जिसमें लिंक के लक्ष्य का पाठ होता है। PowerShell में यह जाँचें:

git config --show-origin --get core.symlinks
Get-Item '.claude/skills/review-staged' |
    Select-Object LinkType, Target, PSIsContainer
Test-Path '.claude/skills/review-staged/SKILL.md' -PathType Leaf

अगर लिंक की जगह टेक्स्ट फ़ाइल है, तो उसी फ़ाइल को वास्तविक लिंक से बदलने से पहले उसका पाठ देखें। आगे के क्लोन के लिए सिंबॉलिक लिंक चेकआउट करने का समर्थित तरीका सक्षम करें। केवल Git की सेटिंग बदलने से पहले से चेकआउट की गई टेक्स्ट फ़ाइल डायरेक्टरी लिंक में नहीं बदलती।

स्किल की उपलब्धता, सक्रियण और परिणाम जाँचें

पहले क्लाइंट की स्किल सूची देखें, फिर स्किल को सीधे बुलाएँ। डिस्क पर फ़ाइल मौजूद होने से यह साबित नहीं होता कि क्लाइंट ने उसे ढूँढ लिया है, और सूची में नाम दिखने से यह साबित नहीं होता कि उसके निर्देश लोड हुए हैं।

हर क्लाइंट में रिपॉज़िटरी का रूट खोलें या क्लाइंट वहीं से शुरू करें। नीचे दिए गए नियंत्रण क्लाइंट के अंदर इस्तेमाल करें, Bash या PowerShell के प्रॉम्प्ट पर नहीं:

क्लाइंट	स्किल मिलने की पुष्टि	उदाहरण चलाने का तरीका
Claude Code	/skills चलाएँ; ज़रूरत हो तो कमांड संदर्भ में दिया गया /reload-skills इस्तेमाल करें।	/review-staged भेजें।
Codex CLI या IDE एक्सटेंशन	/skills या $ वाला स्किल चयन मेनू खोलें।	$review-staged Review my staged changes. भेजें।
Cursor Agent	Customize → Skills खोलें, फिर / के चयन मेनू में स्किल ढूँढें।	review-staged चुनें और कमिट के लिए तैयार बदलावों की समीक्षा माँगें।
Gemini CLI	/skills list चलाएँ; फ़ाइलें जोड़ने के बाद /skills reload इस्तेमाल करें।	यह अनुरोध भेजें: Use the review-staged skill to review my staged changes.

Gemini की दस्तावेज़ों में बताई गई सक्रियण प्रक्रिया में activate_skill और सहमति माँगने वाला इंटरैक्टिव प्रॉम्प्ट इस्तेमाल होता है। पूछे जाने पर इच्छित स्किल डायरेक्टरी की मंज़ूरी दें। सूची देखने और दोबारा लोड करने की कमांड उसकी प्रबंधन गाइड में हैं।

अपेक्षित उत्तर Skill loaded: review-staged से शुरू होता है। उसके बाद मिली समस्याएँ और सुझाई गई जाँचें आती हैं, या इंडेक्स खाली होने पर No staged changes. मिलता है। इस पहचान-पंक्ति के साथ सक्रियण या फ़ाइल पढ़े जाने का रिकॉर्ड और Git कमांड भी देखें। इससे निर्देश लोड होने की पुष्टि होती है; समीक्षा में बताई गई हर समस्या सही है, इसकी पुष्टि अलग से करनी होगी।

इस संरचना में Cursor दोनों पाथ पढ़ता है। 14 अक्टूबर 2026 के IDE 3.25 रिलीज़ नोट्स बताते हैं कि एक ही नाम वाली स्किल मेनू में अलग-अलग पंक्तियों में दिख सकती हैं। अपने इंस्टॉल किए हुए संस्करण में डुप्लिकेट प्रविष्टियाँ देखें; यह न मानें कि सभी क्लाइंट एक ही स्किल के कई लिंक को समान तरीके से संभालते हैं।

मोनोरिपो और CI के लिए स्पष्ट संरचना रखें

साझा स्किल रिपॉज़िटरी के रूट पर रखें और पहली सफल सेटिंग के लिए सभी क्लाइंट वहीं से शुरू करें। किसी खास पैकेज से जुड़ी प्रक्रिया हो तो स्किल के विवरण और निर्देशों में पैकेज का नाम दें; सभी क्लाइंट में नेस्टेड डायरेक्टरी की खोज एक जैसी होने पर निर्भर न रहें। ऊपर का उदाहरण जानबूझकर पूरे Git इंडेक्स की समीक्षा करता है।

ऐसी संरचना रखें जिसमें हर स्थान की भूमिका स्पष्ट हो:

स्थान	भूमिका
.agents/skills/review-staged/SKILL.md	साझा निर्देशों की मुख्य कॉपी, जिसे संपादित किया जाएगा।
.agents/skills/review-staged/references/	स्किल के साथ दिए जाने वाले वैकल्पिक संदर्भ दस्तावेज़।
.claude/skills/review-staged	साझा स्किल की पूरी डायरेक्टरी का सापेक्ष लिंक।
packages/mobile/	अनुरोधित काम में बताए गए ऐप का कोड।

किस दायरे में स्किल उपलब्ध होती है, इसके नियम अलग हैं। Claude Code और Codex अपनी स्किल डायरेक्टरी खोजने के लिए शुरुआती डायरेक्टरी से ऊपर रिपॉज़िटरी के रूट तक जाते हैं। Cursor नेस्टेड प्रोजेक्ट स्किल का भी समर्थन बताता है, जिनका दायरा उनकी डायरेक्टरी के अंदर की फ़ाइलों तक होता है। Gemini की प्रबंधन गाइड वर्कस्पेस स्किल को वर्तमान डायरेक्टरी के सापेक्ष बताती है। चारों को रूट से शुरू करने पर इन अंतरों पर निर्भर नहीं रहना पड़ता।

हर साझा स्किल की डायरेक्टरी सीधे स्किल रूट के अंदर रखें। Gemini की शुरुआती गाइड खोज को इसी गहराई तक सीमित बताती है। Cursor का रिकर्सिव खोज करना बीच में श्रेणी की एक अतिरिक्त डायरेक्टरी को सभी क्लाइंट के लिए संगत नहीं बना देता।

अगर वर्कस्पेस में केवल एक पैकेज खुला है, तो उसी वर्कस्पेस में खोज की जाँच दोहराएँ और ज़रूरत पड़ने पर साझा स्किल वहाँ इंस्टॉल करें या उसका लिंक बनाएँ। रूट वाले लिंक का ../../ लक्ष्य किसी अधिक गहरे स्थान पर बिना दोबारा पाथ निकाले इस्तेमाल न करें।

अगर आपकी टीम के चेकआउट वातावरण सिंबॉलिक लिंक संभाल सकते हैं, तो मुख्य डायरेक्टरी और सापेक्ष लिंक को कमिट करें। लिंक का लक्ष्य रिपॉज़िटरी के अंदर ही रखें, ताकि नया क्लोन किसी डेवलपर की होम डायरेक्टरी तक पहुँच के बिना उसे पढ़ सके।

Linux CI में चेकआउट के बाद Bash की यह जाँच ज़रूरी फ़ाइलों और लिंक की मौजूदगी परखती है:

test -f .agents/skills/review-staged/SKILL.md &&
test -L .claude/skills/review-staged &&
test -f .claude/skills/review-staged/SKILL.md

एग्ज़िट स्टेटस 0 का मतलब है कि फ़ाइल सिस्टम की ये जाँचें सफल हुईं। जिस वातावरण में क्लाइंट वास्तव में चलेगा, वहाँ स्किल मिलने और उसे बुलाने की ऊपर दी गई जाँचें भी करनी होंगी।

स्किल फिर भी लोड न हो तो विफल चरण जाँचें

बार-बार प्रॉम्प्ट बदलने के बजाय उस चरण को ठीक करें जहाँ समस्या हुई है। नीचे अलग-अलग स्थितियों के लिए जाँचें हैं; हर पाठक को सभी सेटिंग क्रम से बदलने की ज़रूरत नहीं है।

• स्किल सूची में नहीं है: वर्कस्पेस का रूट, डायरेक्टरी की स्पेलिंग और फ़ाइल का ठीक SKILL.md नाम जाँचें। फ़ाइल उसी पाथ से पढ़ें जिसे क्लाइंट स्कैन करता है। मुख्य पाथ काम करता हो लेकिन Claude वाला पाथ नहीं, तो लिंक या चेकआउट ठीक करें।
• फ़ाइल मिली, लेकिन मेटाडेटा अस्वीकार हुआ: YAML के सीमांकन चिह्न, अधिकतम 1024 कैरेक्टर वाला गैर-खाली description और डायरेक्टरी से मेल खाता name जाँचें। नाम की लंबाई 1–64 कैरेक्टर हो और उसमें केवल लोअरकेस अक्षर, अंक या हाइफ़न हों। नाम की शुरुआत या अंत में हाइफ़न न रखें और लगातार हाइफ़न से बचें।
• नई फ़ाइल अभी नहीं दिख रही: ऊपर दी गई कमांड से Claude या Gemini की स्किल दोबारा लोड करें। Codex के दस्तावेज़ स्वचालित खोज बताते हैं; वह काम न करे तो रीस्टार्ट करें। अगर स्टार्टअप वाली खोज दोहरानी हो तो Cursor फिर से खोलें।
• Gemini में वर्कस्पेस स्किल नहीं दिख रही: /permissions trust से फ़ोल्डर पर भरोसे की स्थिति जाँचें। वर्तमान कॉन्फ़िगरेशन संदर्भ में skills.enabled का डिफ़ॉल्ट true है, लेकिन एडमिन की नीति स्किल पर रोक लगा सकती है। बंद सेटिंग या फ़ोल्डर पर भरोसे से जुड़ा निर्णय संबंधित नियंत्रणों से ठीक करें।
• दूसरी स्किल चल रही है: एक ही नाम की व्यक्तिगत और प्रोजेक्ट कॉपी देखें। Claude में व्यक्तिगत स्किल को प्रोजेक्ट स्किल से अधिक प्राथमिकता मिलती है; Codex दोनों दिखा सकता है; Gemini वर्कस्पेस स्किल को उपयोगकर्ता की स्किल से अधिक प्राथमिकता देता है। अलग काम करने वाली प्रक्रियाओं के लिए अलग नाम रखें।
• स्किल सूची में है, लेकिन अपने-आप नहीं चुनी जाती: पहले उसे सीधे बुलाएँ। वह काम करे तो विवरण में साफ़ लिखें कि स्किल किस काम के लिए है। स्पष्ट विवरण चयन में मदद करता है; सही तरह से मिल रही फ़ाइल को दूसरी जगह ले जाना मदद नहीं करता।
• निर्देश लोड हुए, लेकिन कमांड विफल हैं: Git की उपलब्धता, वर्तमान कार्य डायरेक्टरी और बताई गई अनुमति-त्रुटि जाँचें। डायरेक्टरी की संगत संरचना से रनटाइम इंस्टॉल नहीं होता और कमांड चलाने की अनुमति नहीं मिलती।