Claude Code ने मेरी skill को 5 बार अनदेखा किया। 1 लाइन ने ठीक कर दिया

Claude Code की कोई skill नाम से बुलाने पर बिल्कुल सही चल सकती है और फिर भी अपने आप कभी लोड नहीं होती। हमारी skill जब भी हमने उसका नाम टाइप किया, चली। लेकिन वही काम सादे शब्दों में माँगने पर हर बार skip हो गई। हमने उसे skip होते देखा, वजह पढ़ी, और वही एक लाइन दोबारा लिखी जिसने इसे ठीक किया।

Skill निर्देशों का एक सहेजा हुआ सेट है, जिसे Claude Code तब खुद उठा लेता है जब आपकी request उससे मेल खाती है। मेल का फ़ैसला एक ही लाइन करती है, जिसे Claude चुनने से पहले पढ़ता है, आपके निर्देश नहीं। नीचे के छह step आपको उस prompt से, जिसे आप बार-बार टाइप करते हैं, ऐसी skill तक ले जाते हैं जो अपने आप लोड होती है। साथ में बीस requests का एक test है, जो आपकी टीम को पता चलने से पहले ही skip हो रही skill पकड़ लेता है।

Test (वही request, fresh sessions)	Skill लोड हुई
नाम से बुलाया (/release-notes)	2 में से 2
सादे शब्द, मूल description	5 में से 0
सादे शब्द, दोबारा लिखा description	5 में से 5

Skill एक फ़ोल्डर है जिसमें एक ही फ़ाइल होती है, SKILL.md। फ़ाइल एक छोटे header से शुरू होती है (नाम और एक वाक्य का description), उसके बाद निर्देश आते हैं। यह एक function की तरह काम करती है: बुलाने वाला signature और docstring पढ़ता है, और body तभी चलती है जब उसे बुलाया जाए। इसे अपने home फ़ोल्डर में रखिए तो हर project में मिलेगी, या repository के अंदर रखिए तो वहाँ काम करने वाले सबको मिलेगी।

फ़ाइल से नहीं, काम से शुरू कीजिए। वह prompt चुनिए जिसे आप बार-बार टाइप करते हैं, और लिख लीजिए कि आपको ठीक-ठीक कौन-सा output चाहिए। हमारा काम था हफ़्ते के release notes: सोमवार से अब तक के commits, area के हिसाब से बाँटे हुए, chores हटे हुए, हर बदलाव की एक लाइन और उसका pull request नंबर। open-source Hono repository पर उस लंबे prompt ने उस हफ़्ते के आठ bug fixes के साफ़ notes बनाए, और वही output वह लक्ष्य बना जिसे skill को छूना था।

हर prompt skill के लायक नहीं होता। एक बार का सवाल नहीं होता, और जो skill आप दोबारा इस्तेमाल नहीं करते वह Claude को पढ़नी पड़ने वाली एक और बेकार लाइन है। उन prompts की छोटी सूची रखिए जो आप हर हफ़्ते टाइप करते हैं; सबसे ऊपर वाला आपकी पहली skill बनता है।

अपने project में .claude/skills/release-notes/SKILL.md बनाइए: छिपे हुए .claude फ़ोल्डर के अंदर skills फ़ोल्डर, उसमें skill के नाम का फ़ोल्डर, और उसके अंदर skill फ़ाइल। फ़ोल्डर मायने रखता है। अलग पड़ी release-notes.md बिल्कुल लोड नहीं होती, और docs सबसे पहले यही जाँचने को कहते हैं।

Header दो डैश-पंक्तियों के बीच कुछ लेबल वाली लाइनें होती हैं, और वह फ़ाइल की पहली लाइन से शुरू होना ज़रूरी है, वरना Claude Code उसे अनदेखा कर देता है। हमारे header में नाम release-notes था, और वह description था जो ज़्यादातर लोग लिखते:

---
name: release-notes
description: Generates changelog documents from repository history.
---

Header के नीचे निर्देश क्रमांकित step में जाते हैं, वही जो आप किसी नए साथी को देते। हमारे पाँच हैं: सोमवार से अब तक के commits ढूँढो, chore और docs commits हटाओ, conventional-commit scope के हिसाब से बाँटो, हर बदलाव की एक सादी लाइन लिखो, और ऊपर छोटे सार के साथ शीर्षक वाला एक block दो। Anthropic इस हिस्से को छोटा रखने की सलाह देता है। Restart की ज़रूरत नहीं: नई या बदली हुई skill को Claude Code उसी session में उठा लेता है जिसमें आप हैं।

उसे नाम से test कीजिए: slash टाइप कीजिए, menu में skill चुनिए, enter दबाइए। Fresh sessions में हमारी skill ने commit log पढ़ा, fixes को area के हिसाब से बाँटा और notes ठीक वैसे लिखे जैसे चाहिए थे, हर बार। पेच यह है कि आपको, और आपकी पूरी टीम को, उसका नाम याद रखना पड़ता है।

कोई साथी skill का नाम टाइप नहीं करेगा। वह नया session खोलेगा और वैसे ही माँगेगा जैसे आपसे माँगता। तो वही test कीजिए: एक fresh session खोलिए (नई बातचीत, जिसमें कुछ लोड नहीं है) और काम अपने शब्दों में माँगिए। Fresh होना ज़रूरी है, क्योंकि इस्तेमाल हो चुकी skill बातचीत में बनी रहती है और उस session का test कुछ साबित नहीं करता।

हमने टाइप किया "what did we ship this week?"। Claude ने commit log खुद चलाया और अपने तरीके से सार लिख दिया, skill का कोई निशान नहीं। जवाब बुरे नहीं थे, पर हर run में बदलते रहे: एक ने सोमवार से गिना, दूसरे ने पिछले release tag से और एक docs बदलाव भी ले आया जिसे skill हटा देती। पाँच fresh sessions में skill पाँचों बार skip हुई।

पाँच runs एक demo हैं, आँकड़ा नहीं। लेकिन जो skill नाम से चले और सादे शब्दों में हर बार skip हो, वह अपना काम नहीं कर रही, और चूँकि वह दूसरे step का नाम वाला test पास कर चुकी थी, आप कभी देखने की सोचते ही नहीं।

एक भी शब्द बदलने से पहले तीन जाँचें चलाइए:

1. /skills उन सभी skills की सूची देता है जो session देख सकता है। उसमें अपनी खोजिए। हमारी सूची में थी और on थी, लेकिन setup में 277 skills थीं, और कई plugin skills "release" पर हमारी से पहले मेल खा रही थीं।
2. claude --debug एक विस्तृत log लिखता है कि Claude Code क्या लोड करता है। skills वाली लाइनें देखिए। हमारे में project skill लोड दिखी, और साथ में एक चेतावनी भी कि skill की सूची budget से बड़ी है, इसलिए कुछ descriptions काटे जाते हैं।
3. claude plugin validate .claude/skills जाँचता है कि header सही बना है। यह जाँच मायने रखती है: टूटा हुआ header skill को नाम से चलने देता है, पर Claude उसे अपने आप मिला नहीं पाता। हमारा पास हुआ।

जाँच	क्या बताती है	हमारा नतीजा
/skills	Skill दिख रही है और on है?	सूची में, on (277 skills)
--debug	क्या लोड हुई? क्या सूची कटी है?	लोड हुई; सूची budget से बड़ी होने की चेतावनी
plugin validate	क्या header parse होता है?	पास

फ़ाइल लोड है और header सही है, तो वजह description है। किसी skill को लोड करने का फ़ैसला करने तक Claude आपके निर्देश नहीं पढ़ता। वह हर skill की एक लाइन पढ़ता है, नाम और description, और उन्हें आपके शब्दों से मिलाता है। हमारे में लिखा था "generates changelog documents from repository history"; request में था "what did we ship this week"। दोनों वाक्यों में एक भी साझा शब्द नहीं। Claude ने हमारे निर्देश कभी पढ़े ही नहीं; उसने एक लाइन पढ़ी, और उस लाइन में हमारे शब्द नहीं थे।

Budget की चेतावनी का मतलब है कि Claude Code descriptions को फ़िट करने के लिए काटता है, सबसे कम इस्तेमाल हुई skills से शुरू करके, और बिल्कुल नई skill सबसे कम इस्तेमाल हुई होती है। जाँचिए कि आपकी बच गई या नहीं: हमारी बच गई, क्योंकि उसके अपने शब्दों वाली requests ने उसे लोड किया।

Description उस पल के लिए लिखिए जब कोई माँगता है, फ़ाइल के लिए नहीं। लिखिए कि skill क्या करती है, कब इस्तेमाल होती है, और लोग असल में कौन-से शब्द टाइप करते हैं। हमारा यह बना:

description: Writes this week's release notes from git log, grouped by scope (router, css, jsx). Use when the user asks what we shipped, what changed this week, for release notes, a changelog, or a summary of recent commits.

Anthropic की authoring guide एक नियम और जोड़ती है: इसे third person में लिखिए ("Writes"), कभी "I can help" या "You can use this" नहीं।

फिर उसी request से fresh session में साबित कीजिए। "What did we ship this week?" ने अब Claude के कुछ छूने से पहले skill लोड की, और notes हमारे format में आए, पाँच में से पाँच fresh sessions में।

एक baseline भी चलाइए: अपनी local settings फ़ाइल में skill override से skill को off कर दीजिए (यह उसे हटाए बिना छिपा देता है)। Off होने पर Claude अपने सार पर लौट गया; on होने पर skill लोड हुई। फ़र्क skill ने डाला, किस्मत ने नहीं।

सीमा: जो description बहुत ज़्यादा चीज़ों से मेल खाए, उससे skill वहाँ भी चल पड़ती है जहाँ नहीं चलनी चाहिए। वे शब्द जोड़िए जो आप सच में इस्तेमाल करते हैं, वे सारे नहीं जो आपको सूझें।

एक request ने हमारा fix साबित किया, पर जिस skill पर पूरी टीम निर्भर है उसे कई तरह से माँगा जाता है। Anthropic का skill-creator यह test बताता है: बीस requests, आधी जो skill को लोड करें और आधी near misses जो न करें। Near miss वह request है जो सुनने में मिलती-जुलती है पर दूसरा काम है, जैसे "write a commit message for my staged changes"। हर request को उसके अपने fresh session में चलाइए और नोट कीजिए कि skill लोड हुई या नहीं। skill-creator की अपनी script ने हमारे Claude Code version पर skill देखी ही नहीं, इसलिए वही बीस requests हमने अपनी एक छोटी script से चलाईं।

Description	जिन should-load requests ने उसे लोड किया	जिन near misses ने उसे लोड किया
मूल	10 में से 4	10 में से 0
दोबारा लिखा	10 में से 10	10 में से 0

Rewrite से पहले skill सिर्फ़ उन्हीं requests पर लोड हुई जिनमें पहले से "release notes", "changelog" या "release" था: चौथे step का शब्द-मिलान, साफ़ दिखता हुआ। Rewrite के बाद वह हर उस request पर लोड हुई जिस पर होनी चाहिए थी, और हर near miss से बाहर रही।

जिस skill को कभी चूकना नहीं है, उसे ज़बरदस्ती चलाइए। उसका नाम टाइप कीजिए, या एक hook जोड़िए (एक छोटी script जिसे Claude Code तय पल पर चलाता है, यहाँ आपके हर message भेजने पर) जिसका output Claude को उस काम के लिए skill इस्तेमाल करने को कहे। Hook होने पर मूल description भी सादी request पर लोड हो गया। सीमा: हर test run असली usage खर्च करता है और hook हर message में एक लाइन जोड़ता है, इसलिए उसे उन गिनी-चुनी skills के लिए रखिए जिन्हें सच में चलना ही है। Description बदलने पर अपनी सूची दोबारा चलाइए।

हमारी release-notes skill नाम से हर बार चली, सादे शब्दों में हर fresh session में skip हुई, और एक दोबारा लिखी लाइन ने उसे हर बार लोड करा दिया। वजह: Claude फ़ैसला करने से पहले हर skill की एक लाइन पढ़ता है, और वह आपके शब्दों से मिलाता है, आपके इरादों से नहीं।

Skill उस काम के लिए फ़ायदेमंद है जिसे आप तय output के साथ दोहराते हैं: हफ़्ते के notes, pull request का विवरण, release checklist। एक बार के सवाल के लिए नहीं, और जो नियम हमेशा लागू होना चाहिए उसके लिए यह सही औज़ार नहीं; वह hook का काम है। बेकार पड़ी skills का ढेर भी महँगा पड़ता है, क्योंकि बहुत ज़्यादा होने पर Claude Code descriptions काटने लगता है, सबसे कम इस्तेमाल हुई से शुरू करके। अच्छा description संभावना बढ़ाता है पर skill को उस काम पर नहीं चलाएगा जिसके लिए वह बनी ही नहीं, और मुट्ठी भर runs एक demo हैं, इसलिए test requests की आपकी सूची ही असली जाँच है।

एक नियम: description उन शब्दों में लिखिए जो आप उस काम को माँगते समय सच में टाइप करते हैं।