Claude Code Skills: अपना पहला SKILL.md लिखें और परीक्षण करें।

Claude Code skills के official डॉक्स के अनुसार, एक skill एक फोल्डर है जिसमें SKILL.md फाइल होती है जिसमें YAML frontmatter और markdown निर्देश होते हैं। Claude शुरुआत में नाम और description लोड करता है, फिर पूरा बॉडी तभी खींचता है जब skill की जरूरत होती है। यह progressive-disclosure डिजाइन context को lean रखता है। आप यहाँ क्या पाते हैं: internal links की auditing के लिए एक original skill, शुरुआत से लिखा गया, trigger test cases के साथ, एक result rubric, और इसे repeatable बनाने के लिए packaging स्टेप्स।

एक Working SKILL.md Example

आइए finished artefact से शुरू करें ताकि आप देख सकें कि हम कहाँ जा रहे हैं। नीचे एक skill है जो पूरी साइट पर internal links की auditing करती है। इसे कॉपी करें, इंस्टॉल करें, और फिर बाकी पोस्ट को पढ़ें ताकि हर निर्णय को समझ सकें।

description: >

Audits internal links in a project's HTML or Markdown output.

Use when the user asks to check broken links, find dead anchors,

audit site links, or review internal navigation before a deploy.

``

## Internal Link Audit

``

Run a link audit against the built output or source files.

``

### Steps

``

1. Collect all internal links (href or markdown link targets starting

with / or a relative path).

2. Resolve each link against the project root.

3. Check whether the resolved target file or anchor exists on disk.

4. Report broken links grouped by source file. For each broken link,

show: source file, link text, href, and the reason it fails

(missing file, missing anchor, or redirect loop if detectable).

5. List passing links only in a summary count, not individually.

6. If zero broken links are found, say so explicitly.

``

### Output format

``

- Broken links: grouped table per source file.

- Summary line: "X of Y internal links are broken."

- If scripts/ contains check-links.sh, run it first and append

Claude's analysis below the script output.

यह एक real, functional skill है। इसे ~/.claude/skills/internal-link-audit/SKILL.md में सेव करें और यह तुरंत हर प्रोजेक्ट में available होगी।

एक बात ध्यान दें: official docs की पुष्टि करते हैं कि custom commands को skills में merge कर दिया गया है। दोनों को /name से invoke किया जा सकता है। तो /internal-link-audit सीधे कमांड के रूप में काम करता है, और Claude इसे natural-language request से भी automatically match करेगा। ये दो अलग-अलग mechanisms नहीं हैं।

एक Narrow Task चुनें और Description लिखें

description फील्ड documentation नहीं है। यह trigger है। इसके हर शब्द का मतलब है कि Claude को skill को सही समय पर match करने में मदद मिले या शोर जो matching को बदतर बनाता है।

Hidekazu Konishi की guide इसे स्पष्ट कहती है: एक vague description ही सबसे आम कारण है कि एक skill कभी fire नहीं होता। इसे third person में लिखें। primary use case को lead करें। फिर actual phrases list करें जो users type करते हैं, क्योंकि matching उन phrases के विरुद्ध होती है, आपके आंतरिक विचार के विरुद्ध नहीं।

बुरा description: web projects में links और संबंधित चीजों में मदद करता है।

बेहतर: किसी project के HTML या Markdown output में internal links की auditing करता है।

Use when the user asks to check broken links, find dead anchors,

audit site links, or review internal navigation before a deploy.

ध्यान दें कि दूसरा संस्करण primary action ("internal links की auditing करता है") को front-load करता है, फाइल types को नाम देता है, और फिर Use when clause में चार concrete trigger phrases देता है। हर phrase कुछ ऐसा है जो एक developer actually type करेगा।

Narrow बेहतर है

एक "general link checker" बनाने की इच्छा का प्रतिरोध करें। एक skill जो एक काम अच्छी तरह करती है reliably trigger होती है। एक skill जो links check करने, redirects validate करने, और page speed पर report करने का वादा करती है unreliably trigger होती है और inconsistently output देती है। सबसे छोटा useful slice pick करें। आप हमेशा बाकी के लिए एक दूसरी skill लिख सकते हैं।

internal-link audit के लिए, narrowing decisions ये थे:

• Internal links ही, external नहीं (अलग tooling, अलग failure modes)
• फाइल existence और anchor existence को check करता है, HTTP status को नहीं
• स्रोत फ़ाइल के अनुसार समूहीकृत टूटे हुए लिंक, सपाट सूची नहीं

हर संकीर्णकरण निर्णय ट्रिगर वाक्यांशों को अधिक विशिष्ट बनाता है और आउटपुट फ़ॉर्मेट को सत्यापित करना आसान बनाता है।

आमंत्रण और सहायक फ़ाइलें नियंत्रित करें

कौशल स्वचालित रूप से लोड होते हैं जब Claude विवरण से मेल खाता है, और वे स्पष्ट /skill-name आदेशों का भी जवाब देते हैं। आधिकारिक दस्तावेज़ों के अनुसार, Claude स्टार्टअप पर चार स्थानों को स्कैन करता है: व्यक्तिगत (~/.claude/skills/), प्रोजेक्ट (.claude/skills/), प्लगइन, और एंटरप्राइज़। एंटरप्राइज़ व्यक्तिगत को ओवरराइड करता है, व्यक्तिगत प्रोजेक्ट को ओवरराइड करता है। जब आप किसी टीम को कौशल भेज रहे हों जहाँ स्थानीय व्यक्तिगतकरण टकरा सकता है, तो पदानुक्रम जानना महत्वपूर्ण है।

आमंत्रण के लिए, आपके पास दो मार्ग हैं:

1. स्वचालित: Claude आपके अनुरोध को पढ़ता है, लोड किए गए विवरणों के विरुद्ध मेल खाता है, कौशल को चलाता है। कोई स्लैश आदेश की आवश्यकता नहीं है।
2. स्पष्ट: आप /internal-link-audit टाइप करते हैं। Claude पूर्ण SKILL.md बॉडी लोड करता है और इसे चलाता है। परीक्षण के लिए और उन क्षणों के लिए उपयोगी जहाँ स्वचालित मेल ट्रिगर नहीं करता है।

दोनों मार्ग समान निर्देश निष्पादित करते हैं। अंतर "मैनुअल बनाम स्वचालित" नहीं है, यह इस बारे में है कि Claude कौन सा संकेत यह निर्णय लेने के लिए उपयोग करता है कि कौशल लागू होता है।

सहायक फ़ाइलें

कौशल फ़ोल्डर SKILL.md से अधिक कुछ रख सकता है:

• scripts/: निष्पादन योग्य कोड (Bash, Python) जिसे कौशल बॉडी संदर्भित करता है। internal-link-audit कौशल scripts/check-links.sh को संदर्भित करता है यदि यह मौजूद है, तो आप निर्देशों को बदले बिना बाद में वास्तविक लिंक-जाँच स्क्रिप्ट स्वैप कर सकते हैं।
• references/: विस्तृत दस्तावेज़ जो Claude माँग पर लोड करता है, हर आमंत्रण पर नहीं। सीमांत मामलों के नियमों के लिए अच्छा जो आप मुख्य निर्देशों को अस्त-व्यस्त नहीं करना चाहते।
• assets/: टेम्पलेट और आउटपुट प्रारूप।

पहले कौशल के लिए, SKILL.md अकेला ठीक है। जब आपके पास कोई आदेश हो जो आप वास्तव में चलाना चाहते हैं तो scripts/ जोड़ें। जब आपके निर्देश लंबे महसूस करने लगें क्योंकि आप एक दर्जन सीमांत मामलों को इनलाइन में संभाल रहे हों तो references/ जोड़ें।

यदि आप पहले से ही प्रोजेक्ट-व्यापी निर्देशों के लिए CLAUDE.md प्रबंधित कर रहे हैं, कौशल उसके साथ होते हैं, वे प्रतिस्थापन नहीं हैं। एजेंसियों के लिए Claude.md पोस्ट कवर करता है कि वह फ़ाइल अलग से कैसे संरचित करें; कौशल संकीर्ण, पुनः उपयोग योग्य कार्यों को संभालते हैं जो वैश्विक निर्देश फ़ाइल में नहीं होते।

सकारात्मक और नकारात्मक ट्रिगर परीक्षण चलाएँ

लिखना आसान हिस्सा है। परीक्षण वह जगह है जहाँ अधिकांश लोग बहुत जल्दी रुक जाते हैं। डेटा विज्ञान की ओर गाइड के अनुसार उत्पादन-तैयार Claude Code कौशल पर, "परीक्षण" का अर्थ है कौशल पर वास्तविक प्रॉम्प्ट फेंकना और यह जाँचना कि क्या यह सही व्यवहार करता है, सॉफ़्टवेयर अर्थ में यूनिट परीक्षण नहीं।

आपको दो प्रकार के परीक्षण मामलों की आवश्यकता है: सकारात्मक (ट्रिगर करना चाहिए) और नकारात्मक (ट्रिगर नहीं करना चाहिए)।

internal-link-audit के लिए सकारात्मक ट्रिगर मामले

ये प्रॉम्प्ट सभी को स्वचालित रूप से कौशल को आमंत्रित करना चाहिए:

• "तैनाती से पहले टूटे हुए आंतरिक लिंक की जाँच करें।"
• "मेरे मार्कडाउन आउटपुट में मृत एंकर खोजें।"
• "बिल्ड फोल्डर में साइट के लिंक्स की ऑडिट करें।"
• "क्या साइट पर कोई टूटे हुए लिंक्स हैं?"
• "प्रोजेक्ट में आंतरिक नेविगेशन की समीक्षा करें।"

नकारात्मक ट्रिगर केस

ये प्रॉम्प्ट्स इस स्किल को ट्रिगर नहीं करने चाहिए। अगर करते हैं, तो आपको ओवर-ट्रिगरिंग की समस्या है।

• "जांचें कि मेरे README में बाहरी लिंक्स अभी भी काम करते हैं या नहीं।" (बाहरी लिंक्स, अलग स्किल क्षेत्र)
• "मेरी sitemap.xml की पुष्टि करें।" (बिल्कुल अलग कार्य)
• "पेज पर टूटी हुई इमेजों को खोजें।" (इमेजें, लिंक्स नहीं)
• "अपने API एंडपॉइंट्स की HTTP स्थिति जांचें।" (HTTP, फाइल-सिस्टम नहीं)

परिणाम का मानदंड

/internal-link-audit से अच्छे आउटपुट को ये सभी शर्तें पूरी करनी चाहिए:

पहले सकारात्मक cases चलाएँ। अगर skill सभी पाँच पर काम करती है, तो negative cases पर जाएँ। अगर किसी negative case पर काम करती है, तो आपके पास description की समस्या है।

Over-triggering, Missed Triggers और Weak Output को ठीक करें

तीन failure modes, तीन fixes। ये अलग-अलग समस्याएँ हैं और हर एक का अलग समाधान है।

Over-triggering का मतलब है कि skill तब काम करती है जब उसे नहीं करना चाहिए। आमतौर पर एक description के कारण जो बहुत broad है। Fix यह है कि Use when clause में exclusion language जोड़ें:

Do NOT use for external link checks, HTTP status checks,

sitemap validation, or image audits.

Explicit exclusions जोड़ने से match surface को narrow किया जा सकता है बिना positive triggers को हटाए।

Missed triggers का मतलब है कि skill मौजूद है लेकिन कभी automatically काम नहीं करती। Description असली user language से match नहीं कर रहा है। Fix यह है कि ज्यादा trigger phrases जोड़ें जो दिखाएँ कि लोग असल में कैसे पूछते हैं, न कि आप formally कैसे describe करते हैं। "क्या dead links हैं?" "internal navigation audit" से अलग है, दोनों को एक ही skill को fire करना चाहिए।

Towards Data Science guide एक optimisation loop describe करता है: test cases को split करें, trigger rate measure करें, improved descriptions generate करें, best score को pick करें। आप इसे manually कुछ prompts के साथ कर सकते हैं, या Anthropic के skill-creator skill को use करके semi-automate कर सकते हैं।

Weak output का मतलब है कि skill काम करती है लेकिन output inconsistent या incomplete है। यह एक description समस्या नहीं है, body समस्या है। देखें कि आपने जो rubric define किया है उसमें कौन सी criteria fail हो रही हैं। अधिक specific formatting instructions जोड़ें। अगर output में failure-reason column missing है, तो instructions में explicitly कहें। अगर ये सभी passing links को list कर रहा है (जो आप नहीं चाहते), तो जोड़ें "Do not list passing links individually."

अगर आप Claude Code automations का एक stack manage कर रहे हैं और उस बड़ी तस्वीर को जानना चाहते हैं कि skills क्या fit करती हैं, तो Claude Code superpowers post surrounding workflow को cover करता है।

बढ़ती हुई teams या agencies के लिए जो multiple client projects handle कर रहे हैं, dedicated Claude Code agency setup page एक बार देखने लायक है, यह explain करता है कि skills को multi-project environment में कैसे organize किया जाए।

Skill को Package करें और इसे Maintain करें

एक बार जब skill सभी positive tests को pass कर जाती है और negative cases को नहीं, तो इसे properly package करें।

Final folder structure

~/.claude/skills/internal-link-audit/

├── SKILL.md

├── scripts/

│ └── check-links.sh (optional, referenced in instructions)

└── references/

└── anchor-edge-cases.md (optional, for edge-case rules)

Projects और लोगों के बीच sharing

Personal skills ~/.claude/skills/ में आपकी machine पर हर project में available हैं। Team distribution के लिए, skill को एक shared repository में move करें और team members को उन्हें अपने personal skills folder में symlink या copy करने दें, या इसे .claude/skills/ में एक shared project repo में commit करें project-scoped access के लिए।

Skill format एक open standard है। freeCodeCamp के build guide के अनुसार, एक जैसी SKILL.md structure Claude Code, GitHub Copilot, Cursor, और Gemini CLI में काम करती है, install paths अलग हैं लेकिन file format नहीं। Claude Code के लिए, path ~/.claude/skills/ है। Copilot के लिए, ये ~/.copilot/skills/ है। Same file, different home।

Maintenance

Skills drift करती हैं। Project structure बदल जाता है, output format को update करने की जरूरत होती है, या trigger phrases team से बात करने का तरीका match करना बंद कर देते हैं। SKILL.md को अपने repo में किसी और doc की तरह treat करें: इसे version करें, underlying workflow बदलने पर इसे review करें, और description में कोई भी edit करने के बाद trigger tests फिर से चलाएँ।

एक numbered maintenance checklist:

1. Description change के बाद सभी positive और negative trigger tests फिर से चलाएँ।
2. अगर output format requirements बदलते हैं तो result rubric को update करें।
3. अगर आप scripts/ में एक script जोड़ते हैं, तो SKILL.md body में explicitly reference करें ताकि Claude को पता चले कि इसे use करना है।
4. एक व्यक्तिगत कौशल को टीम कौशल में बढ़ावा देते समय, ट्रिगर वाक्यांशों की समीक्षा करें — टीम के सदस्य आपसे अलग भाषा का उपयोग कर सकते हैं।
5. ऐसे कौशल हटाएँ जो अब उपयोग में नहीं हैं। पुरानी चीजें जो अप्रत्याशित रूप से सक्रिय होती हैं, वे बिल्कुल कौशल न होने से भी बदतर हैं।

FAQ

SKILL.md फ़ाइल को बिल्कुल कहाँ रहने की आवश्यकता है?

व्यक्तिगत कौशल के लिए जो सभी परियोजनाओं में उपलब्ध हैं, पथ है ~/.claude/skills/your-skill-name/SKILL.md। निर्देशिका का नाम स्लैश कमांड बन जाता है। परियोजना-सीमित कौशल के लिए (केवल एक रिपॉज़िटरी में उपलब्ध), परियोजना रूट के अंदर .claude/skills/your-skill-name/SKILL.md का उपयोग करें। एंटरप्राइज़ कौशल एक अलग पथ का अनुसरण करते हैं जिसे आपके संगठन के Claude Code प्रशासक द्वारा प्रबंधित किया जाता है।

क्या कौशल हर बार Claude शुरू होने पर अपनी पूरी सामग्री लोड करता है?

नहीं। आधिकारिक दस्तावेज़ों के अनुसार, Claude स्टार्टअप पर कौशल निर्देशिका को स्कैन करता है लेकिन केवल नाम और विवरण को संदर्भ में लोड करता है। पूरा SKILL.md निकाय तभी लोड होता है जब कौशल किसी अनुरोध से मेल खाता है। यह प्रगतिशील-प्रकटीकरण डिज़ाइन है: विवरण संदर्भ में रहते हैं, पूरी निर्देशें माँग पर लोड होती हैं।

क्या एक ही अनुरोध के लिए एक से अधिक कौशल सक्रिय हो सकते हैं?

कौशल व्यक्तिगत रूप से मेल खाए जाते हैं। यदि दो कौशल के विवरण एक ही अनुरोध से मेल खाते हैं, तो प्राथमिकता पदानुक्रम लागू होता है: एंटरप्राइज़ व्यक्तिगत को ओवरराइड करता है, परियोजना को ओवरराइड करता है। एक ही स्तर के भीतर, आप विवरणों को अधिक सावधानी से अलग करना चाहेंगे ताकि केवल इच्छित कौशल सक्रिय हो। डुप्लिकेट ट्रिगर आमतौर पर एक संकेत हैं कि दो कौशल के पास ओवरलैपिंग दायरा है और उन्हें विलीन या संकीर्ण किया जाना चाहिए।

यदि विवरण "उपयोग करें जब" कहता है लेकिन उपयोगकर्ता सीधे स्लैश कमांड टाइप करता है तो क्या होता है?

कौशल फिर भी चलता है। /skill-name के माध्यम से स्पष्ट आह्वान स्वचालित मिलान को पूरी तरह बाइपास करता है और पूरा निकाय सीधे लोड करता है। विवरण फ़ील्ड का "उपयोग करें जब" खंड केवल स्वचालित मिलान पर लागू होता है। तो सीधा स्लैश कमांड हमेशा काम करता है, भले ही उपयोगकर्ता की व्याख्या स्वचालित पहचान को ट्रिगर नहीं करती।

मुझे कौशल का उपयोग करने के मुकाबले CLAUDE.md में निर्देश जोड़ने का समय कब पता चलता है?

CLAUDE.md हमेशा-सक्रिय संदर्भ के लिए है: परियोजना संरचना, कोडिंग परंपराएँ, वह चीजें जो Claude को हर सत्र में जानना चाहिए। कौशल माँग-पर कार्यों के लिए हैं: वह चीजें जो आप कभी-कभी करते हैं, हमेशा नहीं, और सुसंगत आउटपुट चाहते हैं। यदि आप अपने आप को CLAUDE.md में बहु-चरणीय वर्कफ़्लो जोड़ते हुए पाते हैं, तो यह संभवतः कौशल में होना चाहिए।

विवरण फ़ील्ड उस काम को करता है जो अधिकांश लोग सोचते हैं कि निकाय करता है। अपनी टीम की वास्तविक शब्दावली से ट्रिगर वाक्यांश लिखें, कार्य को संकीर्ण रखें, और बाकी सब कुछ सफल हो जाता है।