क्लॉड कोड स्किल्स चुप रहते हैं? ये है असली फिक्स

क्लॉड कोड स्किल्स चुप रहते हैं? ये है असली फिक्स

मैं एक डेव टीम मैनेज करता हूँ जो पिछले करीब एक साल से क्लॉड कोड के अंदर ही रहती है। "हमने एक स्प्रिंट के लिए ट्राय किया" वाली बात नहीं, बल्कि "हमारी CI उसी पर चलती है और हमारे PR टेम्पलेट असल में क्लॉड प्रॉम्प्ट हैं" वाली ज़िंदगी है। इस सफर में कहीं मैं महत्वाकांक्षी हो गया। मैंने अपनी टीम के लिए कस्टम स्किल्स बनाईं: `code-review`, `debug-protocol`, और `team-conventions`. वे `.claude/skills/` में रहते हैं, सुंदर दिखते हैं, और उनमें वो सारा YAML frontmatter है जिसका आप सपना देख सकते हैं — लेकिन पहले कुछ हफ्तों तक वे ज़्यादातर पड़े रहे। चुप। अनदेखे। जैसे आग लगने पर ही बजने वाला अलार्म, जब आग लग ही चुकी हो।

सबसे निराशाजनक बात? स्किल फाइलें सही थीं। पाथ सही थे। Markdown साफ और बढ़िया दस्तावेज था। स्किल बस चला ही नहीं। और महीनों बाद, मुझे सच पता चला: यह कभी स्किल की गलती नहीं थी। यह मेरी गलती थी।

"स्किल नहीं चला" वाला जाल

जिन्होंने अभी तक क्लॉड कोड स्किल कॉन्फ़िगरेशन के गड्ढे में नहीं देखा, उनके लिए छोटा संस्करण: स्किल `.claude/skills//SKILL.md` के अंदर फोल्डर होते हैं। हर एक में थोड़ा सा YAML frontmatter होता है — एक नाम और एक description — और फिर असली निर्देश जो मॉडल को स्किल एक्टिवेट होने पर फॉलो करने होते हैं।

```markdown
---
name: code-reivew
description: Use when the user asks for a code review.
---
```

यह काफी सीधा लगता है। लेकिन क्लॉड कोड यह तय करता है कि स्किल चले या नहीं, वह हर स्किल का description पढ़कर, उसे अपने system prompt में मिलाकर, और आपके अनुरोध से मैच करके। दूसरे शब्दों में, स्किल एक्टिवेशन असल में इरादा मिलाने का खेल है। और अगर आपका description सीधे keyword-ट्रिगर की तरह लिखा है, तो खेल शुरू से ही rigged है।

हमने तीन हफ्ते क्लॉड को दोष दिया, API को दोष दिया, चाँद की कला को दोष दिया। फिर हमने असली स्किल डॉक्यूमेंटेशन पढ़ा [docs.anthropic.com/en/docs/claude-code/skills](https://docs.anthropic.com/en/docs/claude-code/skills) और कुछ असहज सच समझा: मॉडल आलसी नहीं है, वह शाब्दिक है। वह सिर्फ उसी स्किल को चला सकता है जिसे वह description से प्रासंगिक मानता है। और हमारे descriptions बहुत बेकार थे।

असली समस्या: Description का मेल न खाना

यह बात हमें समझने में बहुत वक्त लगा: **स्किल किसी खाली जगह में नहीं रहती।** वह दूसरी स्किल्स, बिल्ट-इन व्यवहारों, और क्लॉड के कॉन्टेक्स्ट में मौजूद बाकी चीज़ों के सूप में रहती है। जब कोई डेवलपर कुछ टाइप करता है, तो क्लॉड एक तेज़ मानसिक हिसाब लगाता है: "क्या यह किसी स्किल description से मेल खाता है? अगर कई मैच हैं, तो सबसे करीब कौन सा है? क्या मुझे सीधे जवाब देना चाहिए?"

अगर आपका स्किल description बहुत संकीर्ण, बहुत अस्पष्ट, या बहुत keyword-केंद्रित है, तो क्लॉड उसे मिस कर देगा। और अगर आपका description किसी दूसरी स्किल या बिल्ट-इन कमांड से टकराता है, तो क्लॉड गलत चुन लेगा। आपकी SKILL.md में लिखा कोड कभी समस्या नहीं होता। मेटाडेटा होता है।

ये हैं तीन सबसे बड़े तरीके जिनसे असली टीमें फंसती हैं।

स्थिति 1: कोड रिव्यू स्किल जो सोती रही

मैंने अपनी `code-review` स्किल दुनिया के सबसे obvious description के साथ लिखी: *"Use when the user asks for a code review."* आसान, है ना? गलत।

हमारे डेवलपर कभी "code review" नहीं बोलते थे। वे बोलते थे:

- "Can you sanity-check my PR?"
- "Look at this diff, something's off."
- "Review this before I ship it."
- "Is this over-engineered?"

अंदाज़ा लगाइए किस वजह से स्किल चली? कोई नहीं। क्लॉड ने सीधे जवाब दिया, स्किल को बुलाया ही नहीं, क्योंकि मैसेज में "code review" शब्द आया ही नहीं। फिक्स शर्मनाक रूप से आसान था। हमने description को शाब्दिक नहीं, अर्थपूर्ण बनाया:

```yaml
description: >-
Use for reviewing code changes, pull requests, diffs, or merge requests.
Trigger on phrases like "review this PR", "check my diff", "sanity-check
this code", "is this good to merge", or "look at these changes".
Not for general debugging or explaining code.
```

हमने "Not for" वाला हिस्सा भी जोड़ा। इस एक बदलाव से स्किल करीब 80% ज़्यादा बार चली। Claude Code स्किल्स मूल रूप से prompt engineering हैं — और प्रॉम्प्ट description है।

स्थिति 2: डिबगिंग प्रोटोकॉल जो गायब था

हमारी `debug-protocol` स्किल टीम की हीरो बनने वाली थी। बग्स को रिप्रोड्यूस करने, लॉग्स चेक करने, स्टेट देखने और फिक्स सुझाने की एक संरचित, स्टेप-बाय-स्टेप प्रक्रिया। वह सुंदर थी। वह कभी चली भी नहीं।

क्यों? क्योंकि description "debug" शब्द से शुरू होता था। और "debug" क्लॉड कोड में हर जगह है। एक बिल्ट-इन debug फ्लैग है, सिस्टम-लेवल डिबगिंग व्यवहार है, और उसी डायरेक्टरी में शायद तीन और स्किल्स हैं जो ऐसी ही भाषा इस्तेमाल करती हैं। जब हमारे डेवलपर कहते थे "help me debug this failing test," क्लॉड के पास चार संभावित मैच होते थे, और वह चुनता था उसे जिसका *पूरे प्रॉम्प्ट* में सबसे मज़बूत relevance होता — आमतौर पर बिल्ट-इन व्यवहार, हमारी कस्टम स्किल नहीं।

हमने दो सबक सीखे:

1. **स्किल्स को अनोखे, विशिष्ट नाम दें।** `debug-protocol` बहुत generic है। `sentry-repro-protocol` या `memory-leak-hunt` जैसा नाम बेहतर होता। Generic नाम generic इरादे के आगे कुचल जाते हैं।
2. **मैन्युअल ओवरराइड इस्तेमाल करें।** Claude Code में आप हमेशा `/debug-protocol` टाइप करके स्किल को ज़बरदस्ती चला सकते हैं। हमने इसे अपनी टीम की आदतों में जोड़ दिया, और अचानक स्किल मरी नहीं थी — उसे सीधा न्योता चाहिए था।

लेकिन गहरा insight यह है: मॉडल ने गलत स्किल चुनी क्योंकि *हमने* टक्कर डिज़ाइन की थी। अगर आपके पास दो स्किल्स हैं जो एक जैसी लगती हैं, तो क्लॉड अनुमान लगाएगा। Descriptions को एक-दूसरे को disqualify करने दें। क्लॉड को साफ़ बताएं: "जब समस्या सर्वर लॉग्स से जुड़ी हो, तो इसे general debugging व्यवहार की जगह इस्तेमाल करो।"

स्थिति 3: टीम कन्वेंशन स्किल जो सब भूल गई

सबसे अजीब नाकामी हमारी `team-conventions` स्किल से आई। उसमें कमिट मैसेज, ब्रांच नामकरण, और PR description के नियम थे। यह सत्र की शुरुआत में बढ़िया चलती थी और फिर करीब मैसेज नंबर 20 पर रुक जाती थी। हमने माना कि मॉडल "भूल रहा है।" वह मेमोरी बग नहीं था — वह कॉन्टेक्स्ट था।

Claude Code सारे स्किल descriptions को system prompt में डालता है। लंबे descriptions कॉन्टेक्स्ट खा जाते हैं। और जब बातचीत बढ़ती है, तो सिस्टम जगह बनाने के लिए system prompt को compress या truncate करने लगता है। हमारा `team-conventions` description टेक्स्ट की दीवार थी — कॉर्पोरेट jargon के तीन पैराग्राफ। कॉन्टेक्स्ट विंडो तंग होते ही उसे सबसे पहले फेंका गया।

फिक्स यह था कि description को दो या तीन वाक्यों में सीमित कर दें और असली नियमों को स्किल फोल्डर के अंदर एक referenced फाइल में रख दें। अब description सिर्फ एक signpost है: *"Use for commit message, branch naming, and PR conventions. Full rules in convention.md."* मॉडल इतना याद रख सकता है, और जब स्किल चलती है, तो पूरी फाइल पढ़ लेता है। हमने गैर-स्किल नियमों को भी अपनी `CLAUDE.md` प्रोजेक्ट मेमोरी फाइल में डाल दिया, जो टीम-व्यापी निर्देशों के लिए ज़्यादा भरोसेमंद तरीके से लोड होती है।

प्रैक्टिकल फिक्स जो आप आज से शुरू कर सकते हैं

हफ्तों की पीड़ा के बाद, यह वह चेकलिस्ट है जो काश किसी ने मुझे पहले दिन दी होती।

Description को Search Query की तरह सोचें

अगर कोई आपके skill description को search करे, तो क्या वह उस चीज़ से मेल खाएगा जो आप चाहते हैं? Description को एक semantic search string की तरह लिखें। पर्यायवाची शब्द, आपकी टीम के असली वाक्यांश, और स्पष्ट बहिष्करण शामिल करें। यह मत सोचिए कि मॉडल "जानता है कि आपका क्या मतलब था।" वह सिर्फ वही जानता है जो आपने लिखा।

स्किल फाइल्स को हल्का रखें

500 लाइनों वाली स्किल फाइल एक liability है। वह कॉन्टेक्स्ट खाती है, truncate होती है, और भरोसेमंद नहीं रहती। SKILL.md को सिर्फ इस बात पर केंद्रित रखें कि स्किल कब चलनी चाहिए। भारी विवरण को helper फाइलों में डालें — `prompt.md`, `criteria.md`, `checklist.md` — जिन्हें क्लॉड स्किल एक्टिवेट होने के बाद ही पढ़े।

Negative Examples जोड़ें

यह उल्टा लगता है, लेकिन काम करता है। Description में साफ़ लिखें कि स्किल किस लिए *नहीं* है। लिखें: *"Not for general architecture discussions. Not for syntax questions."* इससे false positives कम होते हैं और मॉडल को एक जैसी स्किल्स में फर्क करने में मदद मिलती है। Negative examples सबसे तेज़ औज़ार हैं।

मैन्युअल ओवरराइड के लिए `/` इस्तेमाल करें

आपका मेटाडेटा कितना भी अच्छा हो, एक वक्त ऐसा आएगा जब auto-detection फेल होगी। अपनी टीम को सिखाएं कि जब ज़रूरत हो तो `/skill-name` टाइप करें। यह failure नहीं है — यह fallback है। सबसे चतुर टीमें automatic skill firing को सुविधा मानती हैं, निर्भरता नहीं।

इसे किसी भी दूसरे कोड की तरह Debug करें

Claude Code में `--debug` फ्लैग है। इसे इस्तेमाल करें। सत्र की शुरुआत में assemble होने वाले system prompt का निरीक्षण करें और पुष्टि करें कि आपके skill descriptions वहाँ हैं। यह obvious लगता है, लेकिन हमने पाया कि हमारे एक YAML frontmatter ब्लॉक में पिछला comma चुपचाप पूरी फाइल को invalid कर रहा था। स्किल कभी लोड ही नहीं हुई। intent-matching की वजह से नहीं — parse error की वजह से। Debug आउटपुट ने दस सेकंड में पकड़ लिया।

अलग-अलग Phrasings के साथ Test करें

सिर्फ अपने documentation का exact phrase टेस्ट मत कीजिए। एक नया सत्र खोलिए और उस गंदे, इंसानी, अस्पष्ट तरीके से टाइप कीजिए जैसे आपकी टीम असल में बोलती है। "Is this PR gonna explode?" आपकी रिव्यू स्किल चलानी चाहिए अगर description सही हैं। अगर नहीं, तो description अभी काफी अच्छा नहीं है।

FAQ

मेरी स्किल नए सत्र में काम करती है, लेकिन बाद में चलना बंद कर देती है?

वह लगभग हमेशा context truncation होता है। लंबे skill descriptions बातचीत बढ़ने पर system prompt से हट जाते हैं। Description पतला करें, या reference file के साथ संरचना बदलें। यह मेमोरी की समस्या नहीं है — यह जगह की समस्या है।

Skill Description में keywords या natural language बेहतर है?

दोनों, सही अनुपात में। एक वाक्य के semantic description से शुरू करें कि इरादा क्या है ("use for reviewing code changes"), फिर सामान्य trigger phrases की सूची जोड़ें। अकेले keywords पर भरोसा न करें, लेकिन इतना abstract भी न रहें कि कुछ मैच न हो।

क्या कस्टम स्किल बिल्ट-इन Claude Code व्यवहार को ओवरराइड कर सकती है?

सीधे तौर पर नहीं। बिल्ट-इन व्यवहार ऐसे level पर जुड़े होते हैं जहाँ आपकी स्किल override नहीं कर सकती। लेकिन आप अपनी स्किल description को टीम की असली स्थिति के लिए अधिक विशिष्ट और प्रासंगिक बनाकर मैच जीत सकते हैं। अटक जाएँ तो `/skill-name` से force करें, या request को ऐसे फिर से लिखें कि बिल्ट-इन रास्ता फिट न बैठे।

मुझे कैसे पता चलेगा कि मेरी स्किल फाइल लोड हो रही है?

`claude --debug` चलाएँ और आउटपुट देखें। System prompt assembly में आपकी स्किल्स सूचीबद्ध दिखनी चाहिए। अगर स्किल लिस्ट में नहीं है, तो YAML frontmatter, फोल्डर स्ट्रक्चर, और फ़ाइलनाम जाँचें। बिना valid `SKILL.md` वाला स्किल फोल्डर सिर्फ सजावट है।

निचली पंक्ति

यहाँ असहज सच है: जब स्किल नहीं चलती, तो स्किल फाइल लगभग कभी समस्या नहीं होती। समस्या यह है कि आपने इंसानी इरादे — "मेरे काम की समीक्षा करो, हमारे नियमों का पालन करो, इस बग को हमारे तय तरीके से ठीक करो" — को उस मेटाडेटा में कितनी अच्छी तरह अनुवाद किया जिसे क्लॉड पढ़ता है। यह बेहतर कोड लिखने के बारे में नहीं है। यह बेहतर *signpost* लिखने के बारे में है।

अगर आप चुप स्किल्स से निराश हैं, तो अपनी markdown को शुरू से मत लिखिए। अपने descriptions को दोबारा लिखिए। असली उदाहरण जोड़िए। Exclusions जोड़िए। फाइल को हल्का रखिए। और जब सब कुछ फेल हो, तो सीधे `/skill-name` टाइप करके आगे बढ़िए।

स्किल टूटी नहीं है। और मानिए या न मानिए, क्लॉड भी नहीं। हम बस भूल गए कि मॉडल को पार्टी में बुलाने के लिए कमरे के उस पार एक अस्पष्ट इशारा काफी नहीं होता।