AI skill-ləri düzgün necə qurmalı

Düzgün qurulmuş skill necə görünür?

İnternet açıq mənbəli skill-lə doludur - minlərlə. İstənilən birini on saniyəyə endirib repozitoriyaya atmaq olar; işləməyə isə başlamır. Bir dəfə qarşıma 200-dən artıq skill-i olan layihə çıxdı: hamısı endirilmiş, hamısı bir-birinin kopyası, qurulmuş giriş faylı isə - sıfır. AI üçün o skill-lər sadəcə mövcud deyildi. Aşağıda yazılanlar - məhz həmin sahibin ötürdüyü hissədir.

Əvvəlcə hay-küyü kənara qoyaq. Skill - markdown faylıdır: ad, təsvir, təlimatlar. Vəssalam. Güc faylın özündə deyil - AI onu tapa biləcəkmi və nə vaxt açacağını biləcəkmi, güc bundadır. Bunu dörd qayda təmin edir və heç biri müzakirəyə çıxarılmır.

Fayl SKILL.md adlanır - nöqtə. Nə skill.md, nə seo-writer.md, nə də README.md. Alətlər məhz bu adı axtarır, registrə həssas fayl sistemində isə kiçik hərfli variant onlar üçün, sadəcə, yoxdur.

Bir skill - bir qovluq, qovluğun adı da elə identifikatordur:

.github/skills/
  next-intl-add-language/SKILL.md
  next-intl-writer/SKILL.md
  seo-writer/SKILL.md
  web-design-reviewer/SKILL.md

Kebab-case: kiçik hərflər, defis, boşluqsuz, alt xəttsiz, versiya nömrəsiz. 200 skill-lik qəbiristanlıq elə bir seo-writer-v2-final-dan başlayır.

Frontmatter-dəki ad qovluğun adı ilə eyni olmalıdır. Hər SKILL.md frontmatter-lə açılır:

---
name: web-design-reviewer
description: 'This skill enables visual inspection of websites running
  locally or remotely to identify and fix design issues. Triggers on
  requests like "review website design", "check the UI", "fix the
  layout", "find design problems". Detects issues with responsive
  design, accessibility, visual consistency, and layout breakage,
  then performs fixes at the source code level.'
---

Qovluq web-design-reviewer, frontmatter isə Web Design Reviewer deyirsə, bir skill-in artıq iki kimliyi var: bir alət qovluğa baxır, o biri frontmatter-ə, reyestr isə üçüncü bir şeyi göstərir. Qovluq adı, frontmatter adı və reyestr qeydi - eyni sətirdir. Bütün repozitoriyanı beş saniyəyə yoxlamaq olar:

for f in .github/skills/*/SKILL.md; do
  folder=$(basename "$(dirname "$f")")
  name=$(grep -m1 '^name:' "$f" | sed 's/name: *//; s/["'"'"']//g')
  [ "$folder" = "$name" ] || echo "MISMATCH: $folder != $name"
done

Skill-ləri .github/skills/-də saxlayın. Spesifikasiya belə istəyir deyə yox - .github/ AI alətlərinin də, vendorların da, komanda yoldaşlarının da onsuz da ortaq bildiyi yeganə qovluqdur. Claude da, Copilot da, canlı reviewer də onu eyni yerdə axtarır.

Təsviri xülasə kimi yox, marşrutlaşdırıcı kimi yazın

Ən çox səhv buradadır. Skill-in mətnini model yalnız onu açmaq qərarına gələndən sonra oxuyur; qərarı isə təsvir verdirir. Deməli, təsvir məhsul annotasiyası deyil - marşrutlaşdırıcıdır. Eyni repozitoriyadan iki nümunə.

Zəif - çünki məhsuldan danışır:

seo-writer:
  "Write high-converting, SEO-optimized website copy,
   landing pages, and marketing content."

Güclü - çünki insanların yazdığı sözlərdən ibarətdir:

web-design-reviewer:
  "...Triggers on requests like 'review website design',
   'check the UI', 'fix the layout', 'find design problems'..."

Qazanan ikincidir, səbəb də uzunluq deyil. Orada real adamın çata yazdığı ifadələr hərfbəhərf dayanır. "check the UI" yazıram - uyğunluq birə-birdir. Təsvirləri istifadəçilərinizin işlətdiyi sözlərlə yazın, məhsul menecerinin seçəcəyi sözlərlə yox.

Yaxşı təsvir həm də sərhəd çəkir. next-intl-writer-in təsviri bu cümlə ilə bitir: "After writing translations, always wires them into the components using useTranslations or getTranslations, replacing every hardcoded string." Bircə cümlə - və skill artıq işi yarıda atıb mənə komponentləri toxunulmamış bir JSON qoyub getmir.

Təsvirləri dürüst saxlayan daha iki vərdiş. Birincisi: vendor adı yoxdur - içində "as Claude, you should" yazılan skill elə o an daşınmaz olur. İkincisi: nümunələr layihəyə uyğun olsun. Nümunələrində en.json, az.json, ru.json keçən skill en.json və fr.json-la gələn layihədə də işləyir - sadəcə model hər dəfə mövcud olmayan iki lokal haqqında oxuyur və bunların illüstrasiya olduğunu özü tapmalı olur. Heç bir səbəb olmadan, hər tapşırıqda ödənən sürtünmə.

AI hansı skill-i işlədəcəyini necə bilir?

AI repozitoriyanızı skan etmir - ona nəyi göstərsəniz, onu oxuyur.

SKILL.md-ni repozitoriyanın bir küncünə atmaq heç nəyi qeydiyyata almır. Hər alətin baxdığı bir-iki öz qovluğu var; qalanı onun üçün yoxdur, öz qovluğundan da sessiyanın əvvəlində yalnız adla təsviri götürür. Modelin yüklənmiş kontekstində fayl haqqında bir kəlmə yoxdursa - model onu açmayacaq, varlığından xəbər tutmayacaq, davranışını da dəyişməyəcək. Göstəricisi olmayan skill mətn faylıdır. Odur ki, giriş faylları kağız-kuğaz deyil. Naqillərdir.

Giriş nöqtəsi üçdür, hər alət özününkünü avtomatik oxuyur:

Qalan hər şey kontekstə yalnız ona görə düşür ki, bu üçlükdən biri modelə "bunu yüklə" deyib.

Giriş faylının içində qeydiyyat marşrutlaşdırma cədvəlidir. CLAUDE.md və AGENTS.md-də adi markdown cədvəli bəs edir:

## Skills

When the user's request matches an available skill, read its
`SKILL.md` and follow its instructions.

| Trigger | Skill |
|---|---|
| Generating translation keys and wiring i18n strings into components, replacing hardcoded strings | `next-intl-writer` - `.github/skills/next-intl-writer/SKILL.md` |
| Adding a new language / locale | `next-intl-add-language` - `.github/skills/next-intl-add-language/SKILL.md` |
| Writing SEO/marketing copy, landing-page text, or high-converting content | `seo-writer` - `.github/skills/seo-writer/SKILL.md` |
| Reviewing UI, checking the design, or fixing layout/responsive/visual issues | `web-design-reviewer` - `.github/skills/web-design-reviewer/SKILL.md` |

İki sütun, üç məlumat: nə vaxt əl atmalı, adı nədir, harada durur. Trigger sütununu tapşırıq dilində yazın, skill dilində yox - model onu fayl adı ilə deyil, istifadəçinin sorğusu ilə tutuşdurur.

Copilot üçün eyni reyestr copilot-instructions.md-nin içində blokdur:

<skills>
<skill>
<name>web-design-reviewer</name>
<description>This skill enables visual inspection of websites...</description>
<file>.github/skills/web-design-reviewer/SKILL.md</file>
</skill>
</skills>

Sintaksis fərqli, iş eynidir: ad, trigger, yol. Dünyada nə qədər reyestr formatı varsa, hamısı bu üç sahədir. Yol yoxdursa - model faylı aça bilmir. Trigger yoxdursa - vaxtının çatdığını bilmir. Ad yoxdursa - siz onu debug edə bilmirsiniz.

Və hər skill-i hər giriş faylında qeydiyyata alın, təkcə sevimlinizdə yox. Skill əlavə edib üç reyestrdən ikisini yenilədiniz - üçüncü alət artıq o birilərdən fərqli kataloqla yaşayır. Özü də bunu sizə deməyəcək.

İki skill nə vaxt biri artıqdır?

Bir sahədə iki skill - olar. Bir iş üçün iki skill - olmaz. Skill faylında prioritet bildirməyə heç nə yoxdur; sorğuya ikisi də uyğun gələndə model ikisini də oxuyur, ortalayır və sizə iki yarımçıq standartdan yığılmış kod bazası təhvil verir.

Buradakı test "oxşar skill saxlamayın"dan xeyli itidir. Yuxarıdakı i18n cütlüyünə baxın: next-intl-writer və next-intl-add-language eyni sahədə oturur, eyni qovluğa toxunur - amma toqquşmur, çünki işləri kəsişmir. next-intl-writer - "komponenti yığmışam, açarları yarat, hardcoded sətirləri əvəz et" deməkdir. next-intl-add-language - "bütün tətbiqi yeni lokalda istəyirəm". Niyyət başqa, trigger başqa, nəticə başqa.

Sual iki skill-in oxşar səslənməsində deyil. Sual budur: tək bir istifadəçi sorğusu ikisinə də uyğun gələ bilərmi? Gələ bilirsə - biri silinir, ya da trigger-lər o vaxta qədər yenidən yazılır ki, uyğun gələn tək qalsın.

Kolleksiyanın ölçüsü də bu məntiqlə ölçülür. 200 skill heç kimə lazım deyil: yerini haqq edən dörd skill aralarında üç trigger bölüşən iki yüzdən güclüdür. Hansı sorğunun hansı skill-i işə saldığını ucadan deyə bilmirsinizsə - o skill-in repozitoriyada yeri yoxdur.

Claude və Copilot bir skill dəstini paylaşa bilərmi?

Bəli - özü də heç nəyin ikinci nüsxəsini saxlamadan. Sxem sadədir: məzmun .github/-da yaşayır, giriş fayllarında ancaq göstəricilər durur.

.github/
  skills/*/SKILL.md            <- the actual skills
  instructions/*.md            <- deep domain standards (a11y, Next.js)
  prompts/*.prompt.md          <- reusable task recipes
  agents/*.agent.md            <- specialised personas
  copilot-instructions.md      <- Copilot's entry point
CLAUDE.md                      <- Claude's entry point
AGENTS.md                      <- vendor-neutral rulebook
.claude/commands/*.md          <- thin Claude wrappers, no content

.github/skills/, .github/instructions/ və .github/prompts/-da vendor haqqında bir kəlmə də yoxdur. Bu fayllar nə "Claude" deyir, nə "Copilot" - işi təsvir edirlər. Paylaşıla bilmələri də elə bundandır. Qalanını üç fənd həll edir.

Nazik wrapper. Slash komandaları Copilot .github/prompts/*.prompt.md-dən, Claude Code .claude/commands/*.md-dən götürür. Ağla ilk gələn - faylı iki qovluğa da kopyalamaq. Etməyin. Mənim .claude/commands/implement-feature.md faylım bütövlükdə budur:

---
description: Implement or update a feature, strictly matching
  existing architecture, conventions, and patterns
argument-hint: <feature description, or paste/reference a .md,
  code, or design>
---

Follow the feature-implementation guidelines below as the rules
for this task.

**My request:** $ARGUMENTS

@.github/prompts/implement-feature.prompt.md

On sətir; sonuncusu icra anında əsl promptu dartıb gətirən @ fayl istinadıdır. 374 sözlük feature-implementation standartı düz bir nüsxədə yaşayır: Copilot onu /implement-feature kimi görür, Claude da /implement-feature kimi, redaktə bir dəfə olunur. Wrapper vendor sintaksisini daşıyır, hədəf - məzmunu.

Qoy hər vendor ortaq faylları öz üsulu ilə yükləsin. Təlimat fayllarının frontmatter-ində applyTo glob-ları durur:

---
description: 'Next.js + Tailwind development standards'
applyTo: '**/*.tsx, **/*.ts, **/*.jsx, **/*.js, **/*.css'
---

Uyğun fayl redaktəyə açılan kimi Copilot həmin faylı glob-la özü qoşur. Claude applyTo oxumur - ona görə CLAUDE.md eyni fayllara birbaşa göstərir:

## Related Instruction Files

For deeper, tool-agnostic guidance, also follow:

- `.github/instructions/nextjs.instructions.md`
- `.github/instructions/nextjs-tailwind.instructions.md`
- `.github/instructions/a11y.instructions.md`
- `AGENTS.md` - full project rulebook shared across AI agents.

Eyni üç fayl, iki tam fərqli yükləmə mexanizmi, sıfır dublikat. WCAG qaydası dəyişdi - bir redaktə, iki alət.

Yuxarı qaydalar toplusunu da yığışdırın. Açığını deyim: mənim CLAUDE.md, AGENTS.md və copilot-instructions.md fayllarım eyni baza qaydalarını hələ də təkrarlayır (komponentlər 300 sətirdən qısa, yalnız next/image, hər store-da isLoading, etiketli Loader2, ssr: false-lu next/dynamic - heç vaxt), bir qaydanın üç nüsxəsi isə gec-tez bir-birindən uzaqlaşacaq. Son nöqtə - bir qaydalar toplusu, iki göstərici:

<!-- CLAUDE.md -->
# Project rules
@AGENTS.md

<!-- .github/copilot-instructions.md -->
# Project rules
See AGENTS.md for the full project rulebook. Follow it exactly.

Sıfırdan başlayırsınızsa - yeganə həqiqət mənbəyi AGENTS.md olsun, o biri ikisi ilk gündən nazik qalsın.

Həmişə yüklənən qatı kiçik saxlayın

Kontekst büdcədir. Skill-lər isə bu büdcəni yalnız lazım olanda xərcləmək üsuludur. Canlı konfiqurasiyada bölgü, söz sayı ilə, belədir:

Konfiqurasiyanın təxminən 70%-i ona ehtiyac yaranana qədər kontekstə heç düşmür. Təkcə əlçatanlıq standartı 3 987 sözlük WCAG 2.2 meyarlarıdır: forma yığanda əvəzsiz, webhook payload-ı düzəldəndə - təmiz səs-küy. Ona görə də .github/instructions/a11y.instructions.md-də yaşayır və CLAUDE.md-yə yapışdırılmır, glob-la çəkilir.

200 skill-lik repozitoriyaya qarşı əsas arqument də elə budur. Hamısı qeydiyyatda olsaydı belə, hər sessiya bir-birinə zidd təlimatlar divarı ilə açılacaqdı və model hansının vacib olduğunu təxmin etməli qalacaqdı. Modelin qarşısında hər sessiya duran şey kiçik olmalıdır - yoxsa oxunmur. Claude Code + Obsidian düz jurnal (flat log) olmadan yazısındakı 407 sətirlik iş loqunun dərsi də elə budur.

Buradan konfiqurasiyanız üçün iki nəticə. Giriş fayllarına yalnız hər tapşırığa aid qaydalar; sahəyə aid nə varsa - skill-in, təlimat faylının, glob-un arxasına. Və skill həqiqət olmaqdan çıxan an silin: köhnəlmiş skill heç olmayandan pisdir - model ona tam əminliklə əməl edir, skill-də adı keçən hər yol isə "bu yol var" vədidir.

Yalnız bir müddət qüvvədə olan qaydalarla nə etməli?

Layihənin elə fazaları olur ki, adi qaydalar orada keçmir: miqrasiya, redizayn, möhkəmləndirmə sprinti. Adi yol - qaydaları yerindəcə dəyişib sonra geri qaytarmağı unutmamağa ümid etmək. Daha yaxşı yol - CLAUDE.md-nin ən başına, faylın başqa heç yerində olmayan iki şeyi daşıyan müvəqqəti blok qoymaq: açıq üstünlük bəyanatı və bitmə şərti.

## ACTIVE: UI Redesign Implementation Contract (temporary)

This section governs the `redesign/ui` branch. Where it conflicts
with any rule below, this section wins. Delete this section once
the redesign ships.

**Scope: visual layer only.** A valid edit changes what the user
sees, never what the code fetches, stores, decides, or where it
navigates.

### Frozen (never touch)
...

Bütün işi iki cümlə görür. "Where it conflicts with any rule below, this section wins" prioritet problemini bağlayır - skill-lər bunu özləri ifadə edə bilmir. "Delete this section once the redesign ships" isə o deməkdir ki, blok öz silinmə təlimatını üstündə gəzdirir və sakitcə daimiyə çevrilə bilmir. Qaydaları sıralamaq azdır. Üstünlüyü də bəyan edin, müddəti də.

Konfiqurasiyanızı on dəqiqəyə yoxlayın

Sınıq AI konfiqi səssiz sınır. Exception atmır: model, sadəcə, sakitcə bir az yanlış nəsə edir, günah isə modelin üstünə yazılır. Ona görə konfiqurasiyaya cədvəl üzrə yoxlama lazımdır - həm də mexaniki yoxlama. Dörd yoxlama çürüntünün çoxunu tutur; bu yazı çıxana qədər dördü də mənim öz repozitoriyamda nəsə tapmışdı.

Yoxlama 1: diskdəki hər skill hər yerdə qeydiyyatdadırmı?

# every skill folder on disk
ls -1 .github/skills/

# every skill mentioned in your entry files
grep -o 'skills/[a-z-]*' CLAUDE.md AGENTS.md \
  .github/copilot-instructions.md | sort -u

İki siyahı hər giriş faylı üzrə üst-üstə düşməlidir. Nə tutur: iki reyestrdə olub üçüncüdən yoxa çıxan skill - yəni qalanlardan fərqli kataloqla işləyən bir alət.

Yoxlama 2: skill-lərin adını çəkdiyi yollar sağdırmı? Skill-lər bircə üsulla köhnəlir: fayl adı çəkirlər, fayllar isə köçür.

# real paths
grep -ohE 'src/[a-zA-Z0-9/._-]+' .github/skills/*/SKILL.md \
  .github/instructions/*.md CLAUDE.md AGENTS.md \
  | sort -u | while read -r p; do
      [ -e "$p" ] || echo "MISSING: $p"
    done

# alias paths - do not skip this half, it is where the rot hides
grep -ohE '@/[a-zA-Z0-9/._-]+' .github/skills/*/SKILL.md \
  .github/instructions/*.md .github/agents/*.md \
  CLAUDE.md AGENTS.md .github/copilot-instructions.md \
  | sed 's/[.,`)]*$//' | sort -u | while read -r p; do
      real="src/${p#@/}"
      [ -e "$real" ] || [ -e "$real.ts" ] || [ -e "$real.tsx" ] \
        || echo "MISSING: $p"
    done

İki yarının ikisini də işlədin. Birinci grep yalnız real src/ yollarını görür; qaydalarınız @/ alias-ı ilə yazılıbsa, çürüntünün hamısı ikinci yarıdadır. Yalançı müsbətlərə də hazır olun: kod nümunələrindəki illüstrativ yollar da siyahıya düşəcək. Siyahı oxunur, sayılmır. Nə tutur: fayl neçə aydır src/components/animated/language-toggle.tsx-də olduğu halda modeli src/components/language-toggle.tsx-ə göndərən skill, bir də heç vaxt yazılmamış modul üçün "always use the utilities from @/lib/utils/scroll" deyən qayda.

İkinci halda tələ var. Eyni qaydanın yolsuz, bulanıq versiyası - "use a shared scroll utility" - qulağa daha təhlükəsiz gəlir. Əslində daha pisdir. Yanlış yol model onu açmağa cəhd edən an gurultu ilə sınır. Bulanıq göstərici isə modelə nəsə uydurtdurub yoluna davam etdirir - kod review-a qədər də heç kim görmür.

Yoxlama 3: skill hələ bu layihəni təsvir edirmi? Hər skill-dəki nümunələri cari kod bazası ilə üzləşdirin: lokal faylları, qovluq adları, komponent adları. Uzaqlaşanda heç nə sınmır - elə buna görə də uzaqlaşırlar.

Yoxlama 4: eyni fakt iki dəfə yazılıb? İki faylda yaşayan sətir gec-tez o iki faylda fərqli olacaq. Klassik günahkar - skill təsvirləri: bir SKILL.md frontmatter-ində, bir də Copilot üçün <skills> blokunda. Reyestrlərə təsvir marşrutlaşdırma üçün lazımdır, ona görə dubldan tam qaçmaq olmur - qoy o, unutduğunuz təkrarların yox, bilərəkdən sinxron saxladıqlarınızın siyahısında dursun.

Audit bir siyahıda:

• Hər SKILL.md məhz SKILL.md adlanır
• Qovluq adı, frontmatter adı və reyestr qeydi eyni sətirlərdir
• Diskdəki hər skill yalnız sevimlinizdə yox, hər giriş faylında qeydiyyatdadır
• Hər reyestr qeydi mövcud yola göstərir
• Skill-in içində çəkilən hər yol hələ də mövcuddur
• Heç bir iki skill eyni istifadəçi sorğusuna uyğun gəlmir
• Təsvirlər istifadəçilərin həqiqətən yazdığı ifadələrdən ibarətdir
• Heç bir skill vendor adı çəkmir
• Daimi qat kiçikdir, ağır fayllar tələbə görə yüklənir

AI-ınız nə tənbəldir, nə axmaq. Ona nə vermisinizsə, düz onu oxuyur - artıq heç nə. Elə indi repozitoriyanı açın, skill qovluqlarını sadalayın, giriş fayllarını grep edin. Bu iki siyahının düz gəlmədiyi hər nöqtə - AI-ınızın səssizcə yan keçdiyi yerdir.