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 mbinu za kiufundi: mpangilio wa faili, na mstari mmoja unaoamua kama ujuzi huo utawashwa au la.

Utaratibu huo ni muhimu. Ujuzi ulioandikwa kwa kufikirika huandika tatizo ambalo hujawahi kuwa nalo, 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 muundo wenyewe ni mpya kwako, soma ujuzi wa wakala ni nini na jinsi wakala anavyoupakia kwanza, kisha rudi 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 chapa, 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 uliloandika, na marekebisho uliyotoa, kwa maneno uliyotumia. Mistari hiyo miwili inakuwa ujuzi. Ombi linakuambia kile ambacho kichocheo kinapaswa kulingana nacho. Marekebisho ndiyo maudhui yote.

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

Anatomia ya skill

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

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

SKILL.md hufunguka kwa block ya frontmatter, mipangilio michache iliyoandikwa katika YAML (muundo uleule wa usanidi unaotumiwa na faili za Docker Compose) kati ya alama za ---, ikifuatiwa na maelekezo katika markdown. Hii 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 unayoandika inatokana na jina la saraka, kwa hivyo hii inaitikia /nginx-config-changes.
• description: kile ambacho skill hufanya na wakati wa kuitumia, hadi vibambo 1,024. Mstari huu hufanya kazi halisi, na sehemu inayofuata inahusu hili pekee.
• Mwili: maelekezo, ambayo hupakiwa tu wakati skill inapoanzishwa.
• reference/: faili za ziada ambazo wakala (agent) husoma anapohitajika. Ziunganishe 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 muktadha, kwa hivyo hati (script) ya mistari 300 ni nafuu.

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, kwa sababu hakukuwa na kitu cha kufuatiliwa wakati kikao kilipoanza.

Sehemu ya description ndiyo mstari wenye nguvu zaidi katika faili

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

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

Jumuisha vitu viwili ndani yake: kile ambacho skill hufanya, na hali ambayo inatumika. Weka kesi muhimu ya matumizi kwanza, kwa sababu Claude Code hukata orodha ya entries kwa 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, ambalo ni msamiati wa takriban ombi lolote linalopaswa kuichochea.

Huu hapa ni mtihani wa maelezo. Mpe mtu ambaye hajawahi kuona sehemu ya ndani mstari huo mmoja, pamoja na ombi unalotaka kuandika, na umuulize kama skill hiyo inafaa. Ikiwa hawezi kusema, basi hata modeli haiwezi.

Weka mwili uwe mfupi, kwa sababu unakaa kwenye muktadha

Ujuzi unapoitwa, maudhui yake yaliyotafsiriwa huingia kwenye mazungumzo kama ujumbe mmoja na kubaki hapo kwa muda wote wa kipindi hicho. Claude Code haisomi upya faili kwenye 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 kwenye faili tofauti. Ufinyazaji unaonyesha kwa nini namba hiyo si ya kubahatisha. Mazungumzo yanapofupishwa ili kuacha nafasi kwenye muktadha, Claude Code huunganisha tena mwito wa hivi karibuni wa kila ujuzi, huweka token 5,000 za kwanza pekee za kila mmoja, na kujaza bajeti ya jumla ya token 25,000 kuanzia ujuzi ulioitwa hivi karibuni. Ujuzi mrefu hukatwa katikati. Ujuzi kadhaa mirefu 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 juu ya restart, na sheria hiyo ndiyo sababu pekee ya faili hii kuwepo.

Ikiwa ujuzi unaiambia 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 kidokezo cha 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 inashughulikia hatua iliyoita ujuzi huo na kufutika unapotuma ujumbe wako unaofuata, kwa hivyo haigeuki kimyakimya kuwa ruhusa ya kudumu.

Jinsi ya kuthibitisha kuwa skill inafanya kazi

Kuangalia skill ikipakia kunakuonyesha kuwa wakala (agent) ameipata. Hii haikuhakikishii kuwa 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 hiyo.
3. Fuatilia kama inaitwa (invocation). Ikiwa skill haifanyi kazi, rekebisha maelezo (description). Mwili wa skill (body) bado si tatizo.
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 kwenye hali ya on utakapomaliza.
6. Andika maombi machache ambayo hayapaswi kuanzisha skill hiyo, na uhakikishe kuwa inabaki kimya kwenye maombi hayo.

Ili kufanya mzunguko huo kuwa wa kiotomatiki, sakinisha plugin ya skill-creator kutoka kwenye soko 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. Plugin hiyo huhifadhi kesi za majaribio (test cases) ndani ya evals/evals.json ndani ya saraka ya skill na huendesha kila kesi katika wakala mdogo (subagent) wake, hivyo kila uendeshaji huanza na muktadha safi. Kisha huandika ulinganisho wa matokeo ya kutumia skill dhidi ya kutotumia skill, ambayo ndiyo namba ya kweli: uboreshaji wa kiwango cha kufaulu uliopimwa dhidi ya token na muda unaotumiwa na skill hiyo.

Hali ya hitilafu: ujuzi hauanzishwi kamwe

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

• Maelezo yanasema kile ujuzi hufanya lakini hayataji kamwe wakati wa kuutumia, kwa hivyo hakuna chochote katika ombi lako kinacholingana nao.
• Maelezo hayajumuishi maneno unayoandika. Ikiwa unasema "nginx", maelezo lazima yaseme nginx.
• disable-model-invocation: true imewekwa kwenye frontmatter. Hii huondoa maelezo kutoka kwa muktadha wa modeli kabisa, na kuacha ujuzi uweze kuitwa na wewe pekee kwa kutumia /name.
• paths glob kwenye frontmatter hupunguza uanzishaji kwa faili zinazolingana, na faili unayofanyia kazi hailingani.
• Ujuzi unakaa kwenye saraka ya .claude/skills/ iliyo ndani ya saraka yako ya kuanzia. Hizi hupakiwa tu baada ya wakala kusoma au kuhariri faili ndani ya saraka hiyo ndogo, kwa hivyo hadi wakati huo ujuzi haupatikani kabisa.

Hali ya hitilafu: ujuzi huchochewa mara kwa mara

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

Finyaza maelezo hayo ili yalingane na sharti linalohusika kikweli, na taja faili au amri ambazo ujuzi huo unashughulikia. Ongeza paths glob pale ujuzi unapohusu 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 peke yake kuwa sasa ni wakati mwafaka wa kufanya deploy.

Hali ya hitilafu: ujuzi unapaswa kuwa katika faili lako la kanuni

Faili la kanuni kama vile CLAUDE.md au AGENTS.md hupakiwa mwanzoni mwa kila kipindi 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 kanuni. Utaratibu unaotumika kwa sehemu ndogo ya kazi, kama vile kanuni ya nginx hapo juu, unapaswa kuwa kwenye ujuzi, ambapo haugharimu chochote katika siku ambazo hakuna anayebadilisha nginx.

Hitilafu ya 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. mpaka kati ya ujuzi, seva za MCP na faili za kanuni huchunguza kesi ngumu zaidi, ikiwemo wakati jibu sahihi ni seva ya MCP (model context protocol) inayompa wakala zana mpya badala ya maelekezo mapya.

Shiriki ujuzi baada ya kuuthibitisha

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 anayekopi hazina hiyo hupata marekebisho yako bila kuhitaji hatua za ziada za usanidi. Kuhamisha ujuzi kati ya hazina bila kutumia njia ya kukata na kubandika ni changamoto inayojitegemea, ambayo imeelezewa katika jinsi ya kushiriki ujuzi wa wakala kati ya hazina.

Ujumbe mmoja kuhusu uwezo wa kuhamishika. 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 kufanya kazi 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 litafanya kazi katika Claude Code na katika kila kitu kingine kinachosoma kiwango hicho. Kuandika maelekezo yenyewe ili yaweze kufanya kazi hata yakihamishiwa kwenye modeli nyingine ni kazi tofauti, na kuandika ujuzi unaofanya kazi na modeli yoyote kunaelezea 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 huo unapoitwa na kubaki hapo kwa muda wote wa 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 haufanyi kazi?

Maelezo ndiyo sababu ya kawaida, kwa sababu ndiyo sehemu pekee ya ujuzi iliyo kwenye muktadha wakati modeli inapoamua. Hakikisha yanaeleza wakati wa kutumia ujuzi huo, siyo tu kile unachofanya, na kwamba yana maneno unayotumia kihalisi kwenye maombi yako. Ikiwa maelezo yanaonekana kuwa sahihi, kagua frontmatter kwa ajili ya disable-model-invocation: true, ambayo huficha ujuzi huo kwa modeli kabisa, na kwa ajili ya paths glob inayouwekea mipaka kwenye faili ambazo huzigusi. Ujuzi ulio kwenye saraka ya .claude/skills/ iliyo ndani 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?

Jiulize ni kazi zako ngapi linahusu. Faili ya sheria hupakiwa katika kila kikao, kwa hivyo inapaswa kuwa na ukweli ambao ni sahihi kwa kila kazi, kama vile meneja wa vifurushi au utaratibu wa kutaja matawi. Ujuzi hupakiwa tu unapoanzishwa, kwa hivyo ndiyo mahali sahihi kwa utaratibu unaohusu sehemu ndogo ya kazi. Usiandike kamwe maelekezo yaleyale katika maeneo yote mawili, kwa sababu nakala hizo mbili hutofautiana na unapoteza uwezo wa kujua ni ipi wakala aliifuata.

Nitajuaje kama ujuzi umesaidia kweli?

Ulinganishe dhidi ya msingi wa kawaida. Kusanya maombi machache ya kweli, endesha kila moja katika kikao kipya huku ujuzi ukiwa unapatikana, 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 huo bado yana maelezo yako, jambo linalofanya faili isiyo kamili kuonekana kuwa kamili. Programu-jalizi ya skill-creator huendesha ulinganisho huu kwa ajili yako na kuripoti kiwango cha mafanikio 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 kutashindwa kwa kutoa hitilafu ya wazi inayoorodhesha sifa zinazoruhusiwa, kwa hivyo amua mapema ikiwa ujuzi unakusudiwa kubaki ndani ya Claude Code au kusafiri.