Jinsi ya kuandika ujuzi wa wakala (agent skill)

Andika ujuzi wako wa wakala (agent skill) kutokana na hitilafu moja halisi

Njia bora ya kuandika ujuzi wako wa wakala ni kuuchuja kutoka kwenye hitilafu moja halisi. Tafuta kazi ambayo wakala wako wa usimbaji amekosea mara mbili, andika marekebisho uliyochapa mara zote mbili, na uhifadhi marekebisho hayo kama faili la SKILL.md ambalo wakala anaweza kulipakia mwenyewe. Kila kitu baada ya hapo ni utaratibu wa kiufundi: mpangilio wa faili, na mstari mmoja unaoamua kama ujuzi huo utawashwa au la.

Mpangilio huo ni muhimu. Ujuzi ulioandikwa kwa kufikirika huandika tatizo ambalo hujawahi kulipata, na bado unatumia nafasi ya muktadha (context) katika kila kikao. Ujuzi uliotokana na hitilafu uliyoshuhudia huja na jaribio lake: uliza swali lilelile tena, na uone kama wakala anapata jibu sahihi wakati huu. Ikiwa umbizo hilo ni geni kwako, soma ujuzi wa wakala ni nini na jinsi wakala anavyoupakia kwanza, kisha urudi na uandike mmoja.

Anza na kazi ambayo wakala amekosea mara mbili

Mara moja ni bahati. Mara mbili ni muundo, na muundo unastahili faili.

Hii hapa ni hitilafu inayojirudia kwenye seva halisi. Unamwomba wakala aongeze block ya reverse proxy kwenye nginx. Anahariri /etc/nginx/conf.d/app.conf, kisha anaendesha sudo systemctl restart nginx. Uhariri huo una kosa la uchapaji, kwa hivyo nginx inakataa kuanza, na tovuti inakuwa chini hadi utakaporekebisha:

nginx: [emerg] unknown directive "proxy_pas" in /etc/nginx/conf.d/app.conf:12
Job for nginx.service failed because the control process exited with error code.

Unarekebisha kosa hilo kwenye chat. Jaribu usanidi kwa sudo nginx -t kabla ya kugusa huduma, kisha uutekeleze kwa reload badala ya restart. Wiki moja baadaye, kwenye kazi tofauti, kosa lilelile linajirudia. Mara hiyo ya pili ndiyo ishara.

Andika mambo mawili wakati hitilafu bado iko mbele yako: ombi ulilochapa, na marekebisho uliyotoa, kwa maneno uliyotumia. Mistari hiyo miwili inakuwa ujuzi. Ombi linakuambia kile ambacho kichocheo (trigger) kinapaswa kulingana nacho. Marekebisho ndiyo maudhui yote.

Mwongozo wa uandishi wa Anthropic wenyewe unaweka hili mbele. Endesha wakala kwenye kazi za uwakilishi bila ujuzi, rekodi mahali anapofeli, kisha andika maagizo ya chini kabisa yanayorekebisha hitilafu hizo. Hitilafu hizo ndizo vipimo (specification), kwa hivyo ujuzi ambao huwezi kuufuatilia hadi kwenye hitilafu moja kwa kawaida ni ujuzi ambao hakuna mtu aliyekuwa nao.

Kwa mfano uliokamilika wa uchujaji huu, Ponytail inageuza hitilafu moja inayojirudia, wakala anayeandika upya zaidi ya uliyoomba, kuwa ujuzi unaweza kusoma mwanzo hadi mwisho kabla ya kuandika wako.

Anatomia ya skill

Skill ni saraka (directory) yenye faili moja la lazima ndani yake.

.claude/skills/nginx-config-changes/
├── SKILL.md
├── reference/
│   └── proxy-headers.md
└── scripts/
    └── check-and-reload.sh

SKILL.md huanza na block ya frontmatter, mipangilio michache iliyoandikwa kwa YAML (muundo uleule wa configuration unaotumiwa na faili za Docker Compose) kati ya alama za ---, ikifuatiwa na maelekezo katika markdown. Hili hapa ni skill nzima kwa ajili ya hitilafu iliyotajwa hapo juu.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
---

## Rules

Run `sudo nginx -t` after every edit under `/etc/nginx`. Do not touch the service until it prints `test is successful`.

Apply the change with `sudo systemctl reload nginx`. Never use `restart`. A reload keeps the running workers serving traffic until the new config parses, so a broken config leaves the site up. A restart stops nginx first, so a broken config takes the site down.

If `nginx -t` fails, fix the file and test again. Never reload a config that failed the test.

For the proxy header defaults this project expects, see [reference/proxy-headers.md](reference/proxy-headers.md).

Faili hilo lina mistari isiyozidi ishirini na ni skill kamili. Sehemu zake ni:

• name: hadi vibambo 64, herufi ndogo, tarakimu na alama za mkato (hyphens) pekee, na haiwezi kuwa na maneno claude au anthropic. Katika skill ya kibinafsi au ya mradi, hii ni lebo ya kuonyesha tu. Amri unayochapa inatokana na jina la saraka, kwa hivyo hii inaitikia /nginx-config-changes.
• description: kile ambacho skill inafanya na wakati wa kuitumia, hadi vibambo 1,024. Mstari huu hufanya kazi halisi, na sehemu inayofuata inahusu hili pekee.
• Mwili: maelekezo, yanayopakiwa tu wakati skill inapoanzishwa.
• reference/: faili za ziada ambazo wakala (agent) husoma anapohitajika. Yaunganishe kutoka SKILL.md na uweke viungo hivyo katika ngazi moja ya kina, kwa sababu faili linalorejelewa kutoka faili lingine lililorejelewa mara nyingi husomwa kwa sehemu tu.
• scripts/: faili ambazo wakala hutekeleza badala ya kusoma. Pato lao pekee ndilo linalogharimu nafasi ya muktadha (context), kwa hivyo hati (script) ya mistari 300 ni nafuu.

Skill hukua na kuwa na mpangilio kamili wakati tabia inayoirekebisha ni ngumu kiasi cha kuhitaji mpangilio huo, na skill isiyo ya uvivu hutumia nafasi hiyo kwa Depth Tree, seti ya faili za milango (gates files) na mkataba wa PLAN.md ili kuzuia wakala kutangaza kuwa amemaliza wakati matawi mazima ya kazi yakiwa hayajaguswa.

Mahali unapoweka saraka hiyo huamua nani anapata skill hiyo.

• .claude/skills/<name>/SKILL.md katika hazina (repository): mradi huu pekee, na husafiri kwenda kwa kila mtu anayekopi (clone) hazina hiyo.
• ~/.claude/skills/<name>/SKILL.md: kila mradi kwenye mashine yako, na si wa mtu mwingine yeyote.
• <plugin>/skills/<name>/SKILL.md: iliyosafirishwa ndani ya plugin, inayopatikana popote ambapo plugin hiyo imewezeshwa.

Unda moja kwa kutumia mkdir -p .claude/skills/nginx-config-changes na uandike faili hilo. Claude Code hufuatilia saraka hizi, kwa hivyo kuhariri skill iliyopo huanza kufanya kazi ndani ya kikao kinachoendelea. Kuunda saraka ya skills ya ngazi ya juu ambayo haikuwepo wakati kikao kilipoanza kunahitaji kuanzisha upya (restart), kwa sababu hakukuwa na kitu cha kufuatiliwa wakati kikao kilipoanza.

Sehemu ya maelezo ndiyo mstari wenye nguvu zaidi katika faili

Wakati wa kuanza, wakala hupakia name na description ya kila ujuzi unaopatikana kwenye muktadha wake. Haipakii sehemu za ndani (bodies). Ombi lako linapowasili, mstari huo mmoja ndio msingi mzima wa kuamua kama ujuzi huu unafaa, kwa hivyo sehemu ya ndani iliyo bora nyuma ya maelezo yasiyoeleweka haitasomwa kamwe.

Andika maelezo katika nafsi ya tatu. "Hujaribu na kupakia upya nginx kwa usalama" inafaa. "Ninaweza kukusaidia na nginx" haifai, kwa sababu maandishi hayo huingizwa kwenye prompt ya mfumo, ambapo nafsi ya kwanza inasomeka kama modeli inayojizungumzia yenyewe.

Jumuisha vitu viwili ndani yake: kile ambacho ujuzi hufanya, na hali ambayo inatumika. Weka kesi muhimu ya matumizi kwanza, kwa sababu Claude Code hukata orodha ya maingizo katika vibambo 1,536. Kuna sehemu ya hiari ya when_to_use kwa ajili ya misemo ya ziada ya kichocheo na maombi ya mfano, na huongezwa kwenye maelezo chini ya kikomo hicho hicho.

Kisha tumia maneno ambayo utaandika kihalisi. description: Helps with nginx hailingani na chochote, kwa sababu hakuna mtu anayeandika "helps with". Toleo lililo hapo juu linataja /etc/nginx, server block, reverse proxy na TLS (transport layer security) certificate path, ambayo ni takriban msamiati wa ombi lolote linalopaswa kuichochea.

Hapa kuna jaribio la maelezo. Mpe mtu ambaye hajawahi kuona sehemu ya ndani mstari huo mmoja, pamoja na ombi unalotaka kuandika, na umuulize kama ujuzi huo unatumika. Ikiwa hawezi kusema, basi hata modeli haiwezi.

Weka mwili wa ujumbe ukiwa mfupi, kwa sababu unakaa kwenye muktadha

Ujuzi unapoitwa, maudhui yake yaliyotolewa huingia kwenye mazungumzo kama ujumbe mmoja na kubaki hapo kwa muda wote wa kipindi hicho. Claude Code haisomi tena faili hiyo katika hatua zinazofuata. Kila mstari unaoandika ni gharama unayolipa kwa kipindi chote, si kwa jibu moja tu.

Anthropic inapendekeza kuweka SKILL.md chini ya mistari 500 na kuhamishia maelezo ya kina kwenye faili tofauti. Ufinyazaji unaonyesha kwa nini namba hiyo si ya kubuni. Mazungumzo yanapofupishwa ili kuongeza nafasi ya muktadha, Claude Code huunganisha tena mwito wa hivi karibuni wa kila ujuzi, huhifadhi token 5,000 za kwanza pekee za kila mmoja, na kujaza bajeti ya jumla ya token 25,000 kuanzia ujuzi ulioitwa hivi karibuni zaidi. Ujuzi mrefu hukatwa katikati. Ujuzi kadhaa mrefu husukumana nje kabisa.

Kwa hiyo, andika tu kile ambacho modeli haijui tayari. Inajua Nginx ni nini na reverse proxy hufanya nini. Haijui sheria yako ya nyumbani kuhusu reload dhidi ya restart, na sheria hiyo ndiyo sababu pekee ya faili hii kuwepo.

Ikiwa ujuzi unaiagiza wakala kuendesha script iliyounganishwa, taja njia hiyo kwa ${CLAUDE_SKILL_DIR} ili itatue popote ujuzi ulipowekwa, na uidhinishe mapema amri hiyo hiyo ili uendeshaji usisimame kwenye ombi la ruhusa.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/check-and-reload.sh *)
---

Ruhusa hiyo inashughulikia hatua iliyoita ujuzi huo na kufutika unapotuma ujumbe wako unaofuata, hivyo haibaki kuwa ruhusa ya kudumu kimyakimya.

Jinsi ya kuthibitisha kuwa skill inafanya kazi

Kuangalia skill ikipakia kunakuonyesha kuwa agent ameipata. Hakuambii kama jibu limebadilika. Hakiki vyote viwili, na ufanye hivyo katika session mpya, kwa sababu session uliyotumia kuandika skill hiyo tayari ina kila ulichosema wakati wa kuiandika. Muktadha huo uliobakia huficha mapungufu yaliyomo kwenye faili.

1. Anzisha session mpya ukiwa na claude ndani ya mradi.
2. Andika ombi lako kama unavyofanya katika siku ya kawaida ya kazi, kwa maneno yako mwenyewe, bila kutaja jina la skill.
3. Fuatilia kama inaitwa (invocation). Ikiwa skill haifanyi kazi, rekebisha maelezo yake (description). Mwili wa skill (body) si tatizo kwa sasa.
4. Iite kwa mkono ukitumia /nginx-config-changes kama njia ya kudhibiti. Tabia sahihi inapoitwa kwa mkono na tabia isiyo sahihi inapoitwa kupitia ombi inathibitisha kuwa kuna tatizo la trigger badala ya tatizo la maelekezo.
5. Tekeleza ombi lilelile huku skill ikiwa imezimwa na ulinganishe majibu hayo mawili. Katika menyu ya /skills, chagua skill hiyo, bonyeza Space ili kubadilisha hali yake kuwa off, kisha Enter ili kuhifadhi. Hii huandika ingizo la skillOverrides ndani ya .claude/settings.local.json, na kubonyeza Space tena huirudisha katika hali ya on utakapomaliza.
6. Andika maombi machache ambayo hayapaswi kuitisha skill hiyo, na uhakikishe kuwa inabaki kimya kwenye maombi hayo.

Ili kufanya mzunguko huo kuwa wa kiotomatiki, sakinisha plugin ya skill-creator kutoka kwenye marketplace rasmi.

/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official

Ikiwa matokeo ya usakinishaji yanasema Run /reload-plugins to activate., tekeleza amri hiyo. Kisha mwambie Claude atathmini skill yako kwa jina lake. Plugin hiyo huhifadhi kesi za majaribio (test cases) katika evals/evals.json ndani ya saraka ya skill na kuendesha kila kesi katika subagent yake, hivyo kila uendeshaji huanza na muktadha safi. Kisha huandika ulinganifu wa matokeo ya na skill dhidi ya bila skill, ambayo ndiyo namba ya kweli: uboreshaji wa kiwango cha kufaulu uliopimwa dhidi ya tokens na muda ambao skill inatumia.

Skill inaweza pia kubeba uthibitisho wake yenyewe badala ya kuacha kazi hiyo kwa uendeshaji tofauti wa tathmini, jambo ambalo ndilo skill ya Old Coder hufanya pale inapomfanya agent akurudishie ripoti ya ushahidi unayoweza kuiendesha wewe mwenyewe.

Hali ya hitilafu: skill haianzishwi kamwe

Unaandika ombi, wakala anafanya kitu kilekile cha zamani kisicho sahihi, na hakuna mstari wa skill unaoonekana. Fuata hatua hizi kwa mpangilio.

• Maelezo yanasema kile ambacho skill inafanya lakini hayasemi kamwe wakati wa kuitumia, kwa hivyo hakuna kitu katika ombi lako kinacholingana nayo.
• Maelezo hayajumuishi maneno unayoandika. Ikiwa unasema "nginx", maelezo lazima yaseme nginx.
• disable-model-invocation: true imewekwa kwenye frontmatter. Hiyo huondoa maelezo hayo kutoka kwenye muktadha wa model kabisa, na kuacha skill iweze kuitwa na wewe pekee kwa kutumia /name.
• paths glob kwenye frontmatter inadhibiti uanzishaji kwa faili zinazolingana, na faili unayofanyia kazi hailingani.
• Skill inakaa kwenye saraka ya .claude/skills/ iliyo ndani ya saraka yako ya kuanzia. Hizo hupakiwa tu baada ya wakala kusoma au kuhariri faili iliyo ndani ya saraka hiyo ndogo, kwa hivyo hadi wakati huo skill haipatikani kabisa.

Hali ya hitilafu: ujuzi huanzishwa mara kwa mara

Tatizo la kinyume ni maelezo mapana kiasi kwamba ujuzi huanzishwa kwa kazi zisizohusika. "Tumia unapofanya kazi kwenye seva" inalingana na karibu ombi lolote katika hazina ya seva. Mwili wa ujuzi hupakia kazi ambazo hauwezi kuzisaidia, na unabaki katika muktadha kwa muda wote wa kikao.

Finyaza maelezo ili yalingane na hali inayohusika kikweli, na taja faili au amri ambazo ujuzi huo unashughulikia. Ongeza paths glob pale ambapo ujuzi unahusu faili fulani pekee. Kwa chochote chenye athari za pembeni, kama vile deploy au commit, weka disable-model-invocation: true na uianzishe wewe mwenyewe kwa kutumia /name, ili wakala asiamue mwenyewe kuwa sasa ni wakati mwafaka wa kufanya deploy.

Njia ya kushindwa: ujuzi unapaswa kuwa katika faili lako la sheria

Faili la sheria kama vile CLAUDE.md au AGENTS.md hupakiwa mwanzoni mwa kila kikao na hutumika kwa kila kazi. Mwili wa ujuzi hupakiwa tu wakati ujuzi huo unapoanzishwa. Marudio ndiyo uamuzi mzima. Ukweli unaohusu kila kazi kwenye hazina, kama vile kisimamia vifurushi unachotumia, unapaswa kuwa kwenye faili la sheria. Utaratibu unaotumika kwa sehemu ndogo ya kazi, kama vile sheria ya nginx hapo juu, unapaswa kuwa kwenye ujuzi, ambapo haugharimu chochote katika siku ambazo hakuna mtu anayebadilisha nginx.

Kushindwa kwa kweli ni kuiweka katika maeneo yote mawili. Nakala mbili hutofautiana, na wakati wakala anapofanya jambo lisilo sahihi huwezi kujua ni nakala ipi aliyoifuata. Chagua makazi moja kwa kila maelekezo. Sheria ambayo tayari iko katika makazi moja kamili na bado inapuuzwa ni tatizo tofauti, na mbinu zilizo nyuma ya maelekezo yaliyopuuzwa zinafaa kuchunguzwa kabla ya kuihamishia kwenye ujuzi na kutumaini kuwa uhamisho huo utatatua tatizo. mpaka kati ya ujuzi, seva za MCP na faili za sheria huchunguza kesi ngumu zaidi, ikiwa ni pamoja na wakati jibu sahihi ni seva ya MCP (model context protocol) inayompa wakala zana mpya badala ya maelekezo mapya.

Ishare pindi inapothibitisha thamani yake

Ujuzi unaodumu kwa wiki nzima ya kazi halisi unastahili kuhifadhiwa. Ujuzi wa mradi katika .claude/skills/ hupitiwa kama msimbo (code) na huja pamoja na hazina (repository), hivyo mwenzako anayefanya clone ya mradi hupata marekebisho yako bila kuhitaji hatua za ziada za usanidi. Kuhamisha ujuzi kati ya hazina bila kutumia copy na paste ni changamoto inayojitegemea, iliyofafanuliwa katika jinsi ya kushiriki ujuzi wa wakala (agent skills) kati ya hazina mbalimbali.

Dokezo moja kuhusu uwezo wa kuhama (portability). Claude Code hukubali orodha ndefu ya sehemu za frontmatter, lakini kiwango cha Agent Skills huruhusu sita pekee: name, description, license, compatibility, metadata na allowed-tools. Ukipakia ujuzi kwenye claude.ai, au ukiufunga kwa ajili ya Skills API, ukiwa na kitu kingine chochote kwenye frontmatter, utashindwa moja kwa moja badala ya kupuuza sehemu hiyo:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

Baki ndani ya sehemu hizo sita na faili hilohilo litapakia katika Claude Code na katika kila kitu kingine kinachosoma kiwango hicho. Mahali ambapo faili linapakia bado huamua kile kinachoweza kufanya, kwa sababu Cowork huendeshwa katika sandbox ya Anthropic wakati Claude Code huendeshwa kwenye mashine yako mwenyewe au VPS, hivyo ujuzi wa nginx uliotajwa hapo juu unastahili kupelekwa kwenye checkout ya mwenzako lakini hauna maana katika sandbox isiyoweza kufikia seva. Kuandika maelekezo yenyewe ili yaweze kuhimili kuhamishiwa kwenye modeli tofauti ni kazi inayojitegemea, na kuandika ujuzi unaofanya kazi na modeli yoyote kunashughulikia hilo.

FAQ

Faili la SKILL.md linapaswa kuwa na urefu gani?

Liweke chini ya mistari 500, na tarajia ujuzi mwingi muhimu kuwa mfupi zaidi ya hapo. Maudhui yake huingia kwenye mazungumzo pindi ujuzi unapoitwa na kubaki hapo kwa kipindi chote cha kikao, hivyo kila mstari ni gharama ya mara kwa mara badala ya ya mara moja. Hamisha nyenzo ndefu za marejeleo kwenye faili tofauti ndani ya saraka ya ujuzi na uziunganishe kutoka SKILL.md, ngazi moja chini, ili wakala azisome tu anapozihitaji. Skripti zilizounganishwa hutekelezwa badala ya kusomwa, hivyo gharama yake ni matokeo yake pekee.

Kwa nini ujuzi wangu hauwaki kamwe?

Maelezo ndiyo sababu ya kawaida, kwa sababu ndiyo sehemu pekee ya ujuzi iliyo kwenye muktadha wakati modeli inapoamua. Hakikisha inaeleza wakati wa kutumia ujuzi huo, siyo tu kile unachofanya, na kwamba ina maneno unayochapa kweli kwenye maombi yako. Ikiwa maelezo yanaonekana sawa, kagua frontmatter kwa ajili ya disable-model-invocation: true, ambayo huficha ujuzi kutoka kwa modeli kabisa, na kwa ajili ya paths glob inayouwekea mipaka kwenye faili ambazo huzigusi. Ujuzi ulio kwenye saraka ya .claude/skills/ iliyopo chini ya saraka yako ya kuanzia ni sababu nyingine: hupakiwa tu baada ya wakala kusoma au kuhariri faili katika saraka hiyo ndogo.

Je, hili linapaswa kuwa ujuzi au mstari kwenye faili yangu ya sheria?

Uliza ni kazi ngapi zako zinahusika na hili. Faili ya sheria hupakiwa katika kila kikao, kwa hivyo inapaswa kushikilia ukweli ambao ni sahihi kwa kila kazi, kama vile meneja wa vifurushi au utaratibu wa kutaja matawi. Ujuzi hupakiwa tu unapowashwa, kwa hivyo ndiyo mahali sahihi kwa utaratibu unaohusu sehemu ndogo ya kazi. Usiandike kamwe maelekezo yaleyale katika sehemu zote mbili, kwa sababu nakala hizo mbili hupishana na unapoteza uwezo wa kujua ni ipi wakala alifuata.

Nitajuaje kama ujuzi umesaidia kweli?

Ulinganishe dhidi ya msingi. Kusanya maombi machache ya kweli, endesha kila moja katika kikao kipya kukiwa na ujuzi huo, kisha yaendeshe tena huku ujuzi ukiwa umezimwa kutoka kwenye menyu ya /skills, na usome majibu yote mawili kando kando. Kikao kipya ni muhimu kwa sababu mazungumzo uliyotumia kuandika ujuzi bado yana maelezo yako, jambo linalofanya faili isiyokamilika kuonekana imekamilika. Programu-jalizi ya skill-creator huendesha ulinganisho huu kwa ajili yako na kuripoti kiwango cha ufaulu kando ya gharama ya token.

Je, ninaweza kutumia SKILL.md ileile na wakala tofauti?

Ndiyo, mradi tu ubaki ndani ya nyanja ambazo kiwango cha Agent Skills kinabainisha: name, description, license, compatibility, metadata na allowed-tools. Claude Code hukubali nyanja nyingi zaidi, na pia inasaidia vipengele vya maudhui kama vile shell command injection ambavyo zana nyingine hazitekelezi. Kupakia ujuzi wenye nyanja iliyo nje ya kiwango hicho hushindwa kwa kutoa hitilafu ya wazi inayoorodhesha sifa zinazoruhusiwa, kwa hivyo amua mapema ikiwa ujuzi unakusudiwa kubaki ndani ya Claude Code au kusafiri.