Jinsi ya kushiriki ujuzi wa wakala kati ya repos

Jinsi ya kushiriki ujuzi wa wakala (agent skills) kati ya hazina (repos)

Ili kushiriki ujuzi wa wakala kati ya hazina mbalimbali, acha kunakili faili na anza kuitegemea kama dependency. Dumisha hazina moja ya ujuzi, iweke alama (tag), na uruhusu kila mradi uweke toleo maalum (pin) la alama hiyo. Kisha ongeza jaribio la msingi (smoke test) kwa kila ujuzi, na kagua kila ongezeko la toleo (bump) kama unavyokagua ongezeko la dependency nyingine.

Hiyo inajumuisha sehemu nne: chanzo kimoja cha ukweli, toleo lililowekwa (pinned version) kwa kila hazina, jaribio la msingi kwa kila ujuzi, na njia ya ukaguzi. Kila kitu hapa chini kinaelezea kwa nini kila sehemu ipo, nini zana zinazotolewa mwaka 2026 hufanya kuhusu hilo, na jinsi ya kujenga mfumo mzima kwenye git remote inayojiendesha (self-hosted) bila kuhusisha huduma za nje.

Ujuzi wa wakala ni folda inayoshikilia faili ya SKILL.md, pamoja na hati (scripts) na faili zozote za marejeleo inazohitaji. Ikiwa kitengo hicho ni kipya, soma nini ujuzi wa wakala na jinsi SKILL.md inavyofanya kazi kwanza. Ukurasa huu unahusu mnyororo wa usambazaji (supply chain) unaozunguka kitengo hicho.

Mahali ujuzi unapoishi, na kwa nini kushiriki ni vigumu

Claude Code hupakia ujuzi kutoka maeneo matatu, na nyaraka za ujuzi hutaja kila njia.

• ~/.claude/skills/<skill-name>/SKILL.md ni ya kibinafsi. Hupakia katika miradi yako yote na si ya mtu mwingine yeyote.
• .claude/skills/<skill-name>/SKILL.md ni ya kiwango cha mradi. Hupakia kwa yeyote anayetoa (check out) hazina (repository) hiyo.
• <plugin>/skills/<skill-name>/SKILL.md husafirishwa ndani ya plugin. Hupakia popote ambapo plugin hiyo imewezeshwa.

Njia ya katikati ndiyo yenye manufaa kwa timu, kwa sababu imejitolea (committed) na kila mtu anayefanya clone ya repo hiyo huipata. Hapo ndipo matatizo yanapoanzia. Ujuzi ulioko kwenye .claude/skills/ ni wa hazina moja. Una hazina nane. Kwa hivyo ujuzi huo hunakiliwa mara nane.

Frontmatter haitoi msaada wowote. Uainishaji wa Agent Skills unaruhusu funguo sita, na njia za usambazaji zinazotekeleza hilo huchapisha orodha hiyo unapotumia nyingine:

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

Angalia kile ambacho hakipo: hakuna ufunguo wa version. Hakuna kitu ndani ya faili kinachorekodi nakala ipi ni mpya zaidi. Hilo ni jambo la busara, kwa sababu ujuzi ni hati badala ya kuwa kifurushi. Hii inamaanisha kuwa uwekaji wa toleo (versioning) lazima utoke kwenye safu inayozunguka faili, na safu hiyo ni jukumu lako.

Tatizo la kwanza: nakala nane zinazotofautiana kimyakimya

Copy-paste hufanya kazi siku ya kwanza. Inafeli siku ya sitini. Mtu fulani anasahihisha maelekezo yasiyo sahihi katika repo ya payments na haigusi zile nyingine saba. Mtu mwingine anaongeza sheria kuhusu pagination katika orders. Sasa jina moja la skill linatoa majibu mawili tofauti kulingana na saraka (directory) ambayo wakala (agent) alianzia, na hakuna msanidi anayejua.

Kufeli huku ni kimyakimya kwa sababu hakuna hali ya hitilafu (error state). Skill ni maandishi. Maelekezo yaliyopitwa na wakati yanazalisha jibu la uhakika lakini lisilo sahihi, ambalo ndilo la gharama kubwa. Hakuna kitu katika wakala kinacholinganisha nakala yako na ya mtu mwingine, kwa hivyo ishara pekee ni mtu kugundua kuwa repo mbili hazikubaliani.

Tatizo la pili: hakuna toleo lililofungwa (pinned)

Hata wakati timu inapoweka ujuzi katika sehemu moja, njia ya kawaida ya kushiriki ni hatua ya kunakili: hati ya usanidi (setup script), mstari wa curl katika hati ya kujiunga (onboarding doc), au shell alias inayolandanisha folda. Njia hizo zote husakinisha chochote kilichopo kwenye ncha ya branch kwa wakati huo.

Hii inamaanisha watengenezaji wawili kwenye commit moja ya programu ileile wanaweza kuwa wanaendesha maelekezo tofauti, kwa sababu walifanya ulandanishi (sync) katika siku tofauti. Pia inamaanisha huwezi kujibu swali la msingi baada ya wakala (agent) kuendesha kazi vibaya: ni toleo gani la ujuzi lililozalisha hili? Bila marekebisho yaliyorekodiwa (recorded revision), uendeshaji huo hauwezi kurudiwa, kwa hivyo ripoti ya hitilafu haiwezi kufanyiwa kazi.

Tatizo la tatu: hakuna anayejua kama ujuzi bado unafanya kazi

Ujuzi hauna compiler. Ni maelekezo yanayolenga model, kwa hivyo unaweza kuacha kufanya kazi wakati faili likiwa halijabadilika hata kidogo. Uboreshaji wa model hubadilisha jinsi maelekezo marefu yanavyofuatwa. Zana ya command line inayotumiwa na ujuzi inaweza kubadili jina la flag. URL katika faili la marejeleo inaweza kuanza kurejesha 404 na agent akaanza kufanya kazi kulingana na ukurasa huo wa hitilafu.

Hakuna kinachoshindwa kwa kelele katika hali hizo zote. Agent bado anajibu. Jibu linakuwa tu ni baya zaidi kuliko lilivyokuwa mwezi uliopita, jambo ambalo ni vigumu kuligundua kwa kila pull request moja baada ya nyingine.

Matatizo yanayotatuliwa na zana zinazotolewa mwaka 2026

Majibu kadhaa yanajitokeza sasa, na hayakubaliani kuhusu mahali ambapo toleo linapaswa kuhifadhiwa.

Lockfiles. Zana ya mstari wa amri ya skills kutoka Vercel Labs (vercel-labs/skills, yenye leseni ya MIT, toleo la 1.5.22 kufikia tarehe 5 Agosti 2026) husakinisha skills kutoka kwenye git repository hadi kwenye saraka yoyote inayotarajiwa na wakala wako, na inajua mpangilio wa mawakala zaidi ya sabini. npx skills add <repo> husakinisha, npx skills update hupandisha toleo, na npx skills list huonyesha ulichonacho. Rekodi ya kile kilichosakinishwa huhifadhiwa mara moja kwa kila mtumiaji badala ya mara moja kwa kila repository, na ombi lililo wazi kwenye mradi huo (issue 283) linaomba amri ya skills install inayoweka upya kila skill iliyofuatiliwa kutoka kwenye lock file ili mashine ya pili iwe na seti sawa. Soma ombi hilo kama ripoti ya hali. Wazo la lockfile limekubalika. Nusu yake ya kila mradi bado inajengwa.

Specs na majaribio. SkillSpec inachukua mwelekeo mwingine. Inachukulia SKILL.md kama mkataba wa kukaguliwa badala ya maandishi ya kuaminiwa, ikiwa na lengo lililowekwa la kufanya skills ziweze "kufuatilika, kupimika, na kuthibitika". skillspec doctor <path> huripoti mahali ambapo wakala ana uwezekano wa kupoteza uzi wa mazungumzo. skillspec boundary map <path> huripoti kile ambacho skill inaweza kufikia, na skillspec boundary assess <path> hupanga matokeo hayo kulingana na hatari. Hii ni Rust crate, yenye leseni mbili ya MIT au Apache 2.0, katika toleo la 0.2.2 kufikia tarehe 29 Julai 2026. Sakinisha toleo lililofungwa (pinned) badala ya jipya zaidi:

cargo install skillspec --version 0.2.2 --locked
skillspec --version

--locked hujenga kwa kutumia matoleo ya dependency ambayo crate ilichapishwa nayo, ili ujenzi usibadilike bila wewe kujua. skillspec --version inapaswa kuchapisha 0.2.2. Nambari tofauti inamaanisha binary ya zamani iliyo mapema kwenye PATH yako inashinda.

Mazoea ya uuzaji (Vendor practice). Google ilielezea jinsi inavyojenga skills katika google/skills kwenye chapisho kuhusu jinsi inavyojenga, kupima na kuongeza uwezo wa skills za wakala. Ondoa uwezo wa kuongeza (scale) na utaratibu huo ni continuous integration (CI) ya kawaida. Kila skill hupita linters kwa ajili ya metadata ya frontmatter, idadi ya mistari, mpangilio wa saraka na majina kabla ya kuunganishwa (merge). Kikagua viungo (link checker) husimamisha ujenzi kwenye URL yoyote inayorejesha 404, jambo linalokamata kiungo kinachoonekana kuwa sahihi ambacho wakala alibuni. Waandishi lazima watoe seti ya prompt za tathmini na mwongozo wa alama pamoja na skill. Kazi za tathmini zilizopangwa hufanyika kila wiki dhidi ya maktaba nzima ili kukamata regression, na kila skill ina mmiliki aliyetajwa ambaye anatarajiwa kuirekebisha wakati ubora unaposhuka.

Muundo uliopo chini ya majibu yote matatu

Huna haja ya kuchagua mojawapo ya hayo. Chini yake kuna umbo moja, na git ya kawaida inakupa yote hayo.

1. Chanzo kimoja cha ukweli. Ujuzi (skill) una makazi moja tu, na kila hazina (repository) inarejelea makazi hayo badala ya kuhifadhi nakala.
2. Toleo lililofungwa (pinned version) kwa kila hazina. Kila mradi hurekodi marekebisho kamili (revision) inayotumia, kwa hivyo kuboresha ni commit katika mradi huo yenye mwandishi na tarehe.
3. Jaribio la utendaji (smoke test) kwa kila ujuzi. Ukaguzi mmoja unaoweza kuendeshwa ambao unathibitisha kuwa ujuzi huo bado unatoa matokeo unayoahidi.
4. Njia ya mapitio (review path). Mabadiliko kwenye ujuzi ulioshirikiwa hupitia mapitio, na kila mtumiaji huona tofauti (diff) kabla ya kuikubali.

Huo ndio muundo wa utegemezi (dependency). Ujuzi ulikua artifact iliyoshirikiwa kwa kasi zaidi kuliko zana zilizoundwa kuuzunguka, kwa hivyo zana unazoziamini tayari ndizo kitu salama zaidi cha kutumia.

Muundo wa timu ndogo kwenye git remote inayojiendesha (self-hosted)

Hazina (repository) moja huhifadhi ujuzi. Hakuna kitu kingine kinachowekwa humo, hivyo historia yake husomeka kama changelog ya maelekezo.

agent-skills/
  skills/
    api-review/
      SKILL.md
    release-notes/
      SKILL.md
  tests/
    api-review.sh
    release-notes.sh
  CHANGELOG.md

Releases ni tags. Tumia annotated tags, kwa sababu hubeba ujumbe na tarehe, na andika ujumbe huo kama sababu inayomfanya mtumiaji kutaka toleo jipya:

git tag -a v1.4.0 -m "api-review: require pagination on list endpoints"
git push origin v1.4.0

Ikiwa remote yako ni Gitea, Forgejo, GitLab au hazina tupu (bare repository) kupitia SSH kwenye VPS yako, hakuna kinachobadilika katika yafuatayo. Kila kitu hapa ni git pamoja na symlink.

Kufunga toleo (pinning) kwa kutumia git submodule

Submodule hurekodi commit moja kamili ya hazina (repository) nyingine ndani ya hazina yako. Rekodi hiyo ndiyo inayofanya kazi ya kufunga toleo (pin). Katika kila mradi unaotumia submodule hiyo:

git submodule add https://git.example.com/team/agent-skills.git vendor/agent-skills
git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills checkout v1.4.0
mkdir -p .claude/skills
ln -s ../../vendor/agent-skills/skills/api-review .claude/skills/api-review
git add .gitmodules vendor/agent-skills .claude/skills/api-review
git commit -m "Pin shared agent skills to v1.4.0"

Symlink ndiyo sehemu inayofanikisha hili. Ingizo la skill katika ngazi ya mradi linaweza kuwa symlink inayoelekea kwenye saraka (directory) nyingine kwenye diski, na Claude Code huifuata na kusoma SKILL.md kutoka kwenye lengo hilo. Hivyo, skill hupakiwa kama skill ya kawaida ya mradi, wakati data zake zikiwa zimehifadhiwa kwenye submodule katika commit uliyochagua.

Thibitisha pin hiyo:

git submodule status

Mstari ulio sahihi huanza na nafasi (space), ikifuatiwa na commit, kisha njia (path), na mwishowe tag iliyo karibu zaidi:

 4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602 vendor/agent-skills (v1.4.0)

Alama ya - mwanzoni mwa mstari inamaanisha kuwa submodule haikuwahi kuanzishwa (initialised), kwa hivyo .claude/skills/api-review haielekezi popote na skill haitapakiwa bila kutoa ujumbe wowote wa hitilafu. Rekebisha hili kwa kutumia git submodule update --init. Alama ya + mwanzoni inamaanisha kuwa commit iliyopo kwenye mfumo inatofautiana na ile iliyorekodiwa, hivyo msanidi huyo anatumia maelekezo ambayo hakuna mtu mwingine anayo. Clone mpya zinahitaji git clone --recurse-submodules, na mstari huo unapaswa kuwepo kwenye README, kwa sababu clone ya kawaida huacha vendor/agent-skills ikiwa tupu na haitoi hitilafu yoyote.

Kupandisha toleo (upgrading) ni hatua ya makusudi, na ndiyo lengo kuu:

git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills diff v1.4.0 v1.5.0 -- skills/
git -C vendor/agent-skills checkout v1.5.0
git add vendor/agent-skills
git commit -m "Bump shared agent skills to v1.5.0"

Mstari wa diff ndio njia ya ukaguzi. Unaonyesha mabadiliko yaleyale ambayo kila hazina nyingine inayotumia submodule hiyo itayaona, na unafaa kuingizwa kwenye pull request.

Kufunga toleo kwa kutumia soko la programu jalizi (plugin marketplace)

Ikiwa hutaki kumtaka kila msanidi programu ajifunze matumizi ya submodules, mfumo wa plugin wa Claude Code unakufanyia usambazaji huo, na unafanya kazi dhidi ya seva ya mbali unayojiendeshea (self-hosted). Weka katalogi katika .claude-plugin/marketplace.json kwenye hazina ya skills:

{
  "name": "acme-agents",
  "owner": { "name": "Platform team", "email": "platform@example.com" },
  "plugins": [
    {
      "name": "team-skills",
      "description": "Shared review and release skills",
      "version": "1.4.0",
      "source": {
        "source": "url",
        "url": "https://git.example.com/team/agent-skills.git",
        "ref": "v1.4.0",
        "sha": "4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602"
      }
    }
  ]
}

Kuna vyanzo viwili tofauti vinavyohusika hapa, na kuvichanganya ni kosa la kawaida. Chanzo cha soko (marketplace source), yaani mahali ambapo katalogi yenyewe inachukuliwa, kinakubali ref kwa ajili ya branch au tag na hakikubali sha. Chanzo cha plugin ndani ya katalogi kinakubali vyote viwili, na wakati vyote vikiwa vimewekwa, sha ndiyo inayotumika kama kigezo cha kufunga toleo (pin). Kwa hivyo, kufunga toleo kwa kutumia commit kamili kunafanyika kwenye ingizo la katalogi.

Kila hazina inayotumia (consuming repository) inatangaza soko hilo katika faili lake la .claude/settings.json lililohifadhiwa:

{
  "extraKnownMarketplaces": {
    "acme-agents": {
      "source": {
        "source": "url",
        "url": "https://git.example.com/team/agent-skills.git",
        "ref": "v1.4.0"
      }
    }
  },
  "enabledPlugins": {
    "team-skills@acme-agents": true
  }
}

Mwanachama wa timu anayeiamini folda ya mradi huombwa kusakinisha soko hilo, na plugin huwashwa kwa ajili yake bila kuhitaji ukurasa wa wiki wa kumwelekeza kufanya hivyo. Skills hizo kisha hujibu kwa /team-skills:api-review, kwa sababu skills za plugin zimewekwa kwenye namespace kulingana na jina la plugin na haziwezi kugongana na skill ya mradi yenye jina sawa. Baada ya kusukuma (push) tag mpya, watumiaji hufanya refresh kwa kutumia /plugin marketplace update acme-agents, kisha huendesha /reload-plugins ikiwa muhtasari wa usakinishaji utaomba hivyo.

Kuandika smoke test kwa ajili ya skill moja

Smoke test ni script ya agent inayofanya kazi dhidi ya fixture yenye hitilafu inayojulikana, pamoja na assertion moja. Claude Code hufanya kazi bila mwingiliano wa mtumiaji kwa kutumia -p, na skill inayotumiwa na mtumiaji hufanya kazi hapo: weka /skill-name kwenye prompt string na itapanuliwa kabla ya run kuanza.

#!/usr/bin/env bash
set -euo pipefail

claude -p "/api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
  --allowedTools "Read" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["rule_ids"]}' \
  | jq -e '.structured_output.rule_ids | index("pagination-required")' > /dev/null

fixtures/orders-api.md ni faili fupi lenye hitilafu moja ya makusudi. Assertion ni kwamba skill inaitaja hitilafu hiyo. jq -e hutoka (exit) kwa status isiyo ya sifuri wakati filter yake inazalisha null, kwa hivyo skill inayoacha kunasa hitilafu iliyopandikizwa itafanya script ifeli. claude yenyewe hutoka kwa status isiyo ya sifuri wakati run inafeli, na set -euo pipefail hubadilisha hitilafu yoyote kuwa test iliyofeli.

Model hubadilisha maneno ya majibu yake kati ya run moja na nyingine, kwa hivyo usiwahi kufanya assertion kwenye sentensi nzima. Fanya assertion kwenye kitambulishi (identifier) ambacho skill inatakiwa kutoa, au kwenye field ya schema uliyoomba, na weka fixture iwe ndogo ili run iwe ya gharama nafuu.

Katika CI, ongeza --bare. Bila hiyo, claude -p hupakia muktadha uleule ambao session ya mwingiliano ingepakia, ikijumuisha hooks, plugins na CLAUDE.md kutoka kwenye mashine inayoendesha, kwa hivyo configuration ya kibinafsi ya mfanyakazi mwenzako inaweza kubadilisha matokeo. Bare mode huruka ugunduzi wa kiotomatiki (auto-discovery), jambo ambalo linamaanisha inaruka pia skill unayoi-test, kwa hivyo ipakie hiyo moja kwa uwazi. Bare mode haisomi pia login yako ya usajili, kwa hivyo weka ANTHROPIC_API_KEY kwenye environment kwanza:

claude --bare -p "/team-skills:api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
  --plugin-dir vendor/agent-skills \
  --allowedTools "Read" \
  --output-format json

Kwa kutumia --output-format stream-json, tukio la kwanza la run huripoti ni plugins zipi zilizopakiwa na hubeba array ya plugin_errors kwa zile ambazo hazikupakiwa. Fanya CI job ifeli ikiwa plugin_errors si tupu. Hilo hunasa pin inayolenga revision ambayo haipo tena, ambayo vinginevyo ingeonekana kama agent anayepuuza kimya kimya sheria zako za nyumbani.

Ujuzi ulioshirikiwa ni maelekezo yanayoweza kutekelezwa

Vipengele viwili hufanya jambo hili kuwa la kweli, na vyote ni muhimu wakati faili inatoka kwa timu nyingine.

Kwanza, SKILL.md inaweza kuendesha amri za shell kabla ya modeli kusoma chochote. Mstari kama huu ndani ya mwili wa maandishi ni usindikaji wa awali (preprocessing):

- Current branch: !`git rev-parse --abbrev-ref HEAD`

Amri hiyo huendeshwa kwenye mashine inayopakia ujuzi huo, na matokeo yake huchukua nafasi ya kishika-nafasi (placeholder) katika maandishi yanayopokelewa na modeli. Kizuizi kilichofungwa kwa alama tatu za backtick kikifuatiwa na ! huendesha amri kadhaa kwa njia hiyo hiyo. Hakuna anayethibitisha lolote kati ya haya wakati wa utekelezaji. Kusoma ujuzi ulioshirikiwa kunamaanisha kusoma mbadala wa amri zake.

Pili, frontmatter inaweza kuidhinisha zana mapema. allowed-tools hutoa zana zilizoorodheshwa bila ombi la ruhusa kwa hatua iliyoita ujuzi huo. Kwa ujuzi wa mradi, idhini hiyo huanza kufanya kazi mara tu mtu anapokubali mazungumzo ya uaminifu wa workspace kwa folda husika. Nyaraka za Claude Code zinaeleza matokeo yake wazi: kagua ujuzi wa mradi kabla ya kuamini hazina (repository), kwa sababu ujuzi unaweza kujipa idhini pana ya kutumia zana.

Kwa hivyo, shughulikia ongezeko la ujuzi kama unavyoshughulikia ongezeko la dependency. Funga (pin) kwa kutumia commit kamili popote utaratibu unaporuhusu, kwa sababu tag inaweza kuhamishwa na branch hubadilika kulingana na ufafanuzi wake. Kwenye mashine iliyofungwa (locked-down), "disableSkillShellExecution": true katika mipangilio hubadilisha kila mbadala wa amri na maandishi halisi ya [shell command execution disabled by policy] badala ya kuiendesha, na ikitumika kupitia mipangilio inayodhibitiwa, mtumiaji hawezi kuibatilisha. Ujuzi uliounganishwa (bundled) na unaodhibitiwa hauhusiki na mpangilio huo.

Uangalifu uleule unatumika kwa kile ambacho ujuzi husoma. Ujuzi unaoendesha env au kufungua faili ya usanidi huvuta chochote kinachopatikana kwenye muktadha wa modeli, ambayo ni hitilafu inayoshughulikiwa katika kuepuka kuweka siri ndani ya mawakala unaoendesha. Ujuzi unaochota ukurasa au kuendesha query ni mfiduo uleule unaoelekezwa nje, kwa kuwa maandishi yaliyorejeshwa huingia kwenye muktadha yakionekana kama maelekezo uliyoyaandika, mpaka ambao ni vyema kuusoma kabla ya kuelekeza wakala kwenye mfano wako wa SearXNG kwa ajili ya utafutaji wa wavuti.

Nini cha kusoma wakati wa kubadilisha toleo (version bump)

• Diff ya kila mwili wa SKILL.md, kwa sababu maandishi hayo ndiyo maelekezo ambayo wakala wako atayafuata.
• Kila uingizwaji wa amri (command substitution), kwa sababu hizo huendeshwa kwenye mashine yako wakati ujuzi (skill) unapopakiwa.
• Mabadiliko yoyote kwenye allowed-tools, kwa sababu mstari huo hutoa zana bila kukuuliza ruhusa.
• Jaribio la uendeshaji (test run) lililo nyuma ya tag. Ikiwa hazina (repository) iliyoshirikiwa inaendesha majaribio yake ya smoke katika CI, tag unayoiunganisha inapaswa kuwa na matokeo ya kijani (green run).

Mkaguzi asiyeweza kusoma diff nzima ndani ya dakika kumi anatazama ujuzi ambao umekuwa mkubwa sana. Ugawe. Hoja hiyo hiyo inatumika kwa nyaraka za hazina ambazo mawakala wako wanasoma: weka sheria za kudumu kwenye faili zilizoelezewa katika mgawanyo wa AGENTS.md na HUMAN.md na hoja za usanifu katika DESIGN.md iliyoandikwa kwa ajili ya mawakala, na uache ujuzi uwe taratibu finyu.

Wakati mabadiliko ya modeli au zana yanapoharibu ujuzi

Mambo kadhaa hubadilika nyuma ya pazia la ujuzi bila mtu yeyote kuuhariri. Uboreshaji wa modeli hubadilisha jinsi maelekezo marefu yanavyofuatwa kwa usahihi, hivyo ujuzi uliotegemea modeli kufika hatua ya tisa unaweza kuacha kufika hapo. Zana ya mstari wa amri (command line tool) hubadilisha jina la flag, kwa hivyo wakala huendesha flag ya zamani, husoma hitilafu, na kubuni mbadala. URL inayorejelewa huanza kurejesha 404. Harness ya wakala hubadilisha jinsi inavyochagua ujuzi, kwa hivyo description iliyokuwa ikishinda mechi haifanyi hivyo tena.

Hii ndiyo sababu smoke test ina uzito mkubwa katika mpangilio huu. Endesha jaribio la kila ujuzi kwa ratiba na pia wakati wa push. Google huendesha kazi zake za tathmini kila wiki dhidi ya maktaba nzima kwa sababu hii, na cron job ya kila wiki kwenye VPS ndogo inatosha kwa timu yenye ujuzi kumi. Hiyo ndiyo njia pekee ya kusikia kuhusu uharibifu kabla ya msanidi programu hajajua.

Uwezo wa kubebeka (portability) pia husaidia. Vipimo vya Agent Skills huweka frontmatter kwenye funguo sita, kwa hivyo ujuzi ulioandikwa kulingana na vipimo hivyo hupakia katika zana nyingine nje ya ile uliyoiandikia, wakati kila ufunguo mahususi wa harness unaoongeza ni dau kwa muuzaji mmoja. Kuandika ujuzi unaostahimili mabadiliko ya modeli ni taaluma ya kipekee, inayoshughulikiwa katika kufanya ujuzi ufanye kazi kwenye modeli yoyote.

FAQ

Ninawezaje kushiriki ujuzi mmoja wa agent kwenye hazina (repositories) kadhaa?

Weka ujuzi huo kwenye git repository maalum, weka tag kwenye releases zake, na ufanye kila mradi unaotumia ujuzi huo urejelee tag husika badala ya kunakili faili. Kuna njia mbili zinazofanya kazi. Git submodule hurekodi commit kamili, na symlink kutoka .claude/skills/<name> kwenda kwenye submodule hiyo huifanya ipakiwe kama ujuzi wa kawaida wa mradi. Soko la plugin (plugin marketplace) hufanya kazi hiyo hiyo kupitia /plugin, huku pin ikitangazwa kwenye .claude/settings.json ya mradi unaotumia ujuzi huo. Njia zote mbili huweka toleo kwenye historia ya git, hivyo unaweza kujua ni maelekezo yapi yaliyozalisha utekelezaji fulani wa agent.

Je, ninaweza kufunga (pin) ujuzi wa agent kwenye toleo maalum?

Huwezi kufanya hivyo ukiwa ndani ya SKILL.md, kwa sababu frontmatter hiyo haina ufunguo wa version. Pin lazima itoke kwenye safu inayozunguka faili hiyo. Git submodule hufunga commit kamili kwa usanifu wake. Katika soko la plugin la Claude Code, chanzo cha plugin hukubali ref kwa ajili ya branch au tag na sha kwa ajili ya commit kamili, na sha ndiyo inayotumika pale zote mbili zinapokuwepo. Chanzo cha soko lenyewe hukubali ref pekee. Pendekeza kutumia pin ya commit, kwa sababu tag inaweza kubadilishwa baada ya wewe kuikagua.

Jaribio la awali (smoke test) la ujuzi linapaswa kuhakiki nini?

Hakiki kitu kisichobadilika. Endesha ujuzi huo bila mwingiliano (non-interactively) dhidi ya fixture iliyo na hitilafu inayojulikana, kisha angalia kama kitambulisho maalum kinaonekana kwenye matokeo, kwa mfano rule id ambayo ujuzi huo unapaswa kuiripoti. Kuomba matokeo yaliyopangwa (structured output) kwa kutumia --output-format json na --json-schema hufanya uhakiki kuwa sahihi, na jq -e husimamisha script pale thamani inapokosekana. Usiwahi kuhakiki sentensi nzima, kwa sababu model hubadilisha maneno ya majibu yake kati ya utekelezaji mmoja na mwingine.

Je, ni salama kusakinisha ujuzi ulioshirikiwa kutoka kwenye repository ya timu nyingine?

Ichukulie kama dependency ya msimbo (code dependency), kwa sababu ni maelekezo yanayoweza kutekelezwa. SKILL.md inaweza kuendesha amri za shell wakati wa kupakia (load time) kupitia mfumo wa substitution wa amri ya !, na uwanja wa allowed-tools kwenye frontmatter unaweza kuidhinisha zana mapema bila kuuliza. Soma tofauti (diff) kwenye kila sasisho, funga (pin) kwenye commit kamili badala ya branch, na upendelee chanzo ambacho timu yako inakidhibiti. Kwenye mashine zinazosimamiwa, "disableSkillShellExecution": true katika mipangilio husimamisha kabisa utekelezaji wa substitution za amri.

Je, ujuzi ulioshirikiwa utafanya kazi kwenye agents nyingine mbali na Claude Code?

Hiyo inategemea frontmatter unayotumia. Spec ya Agent Skills inafafanua funguo sita: name, description, license, compatibility, metadata na allowed-tools. Ujuzi uliopunguzwa kwenye funguo hizo hupakiwa kwenye zana zinazotekeleza spec hiyo, na pia hupakiwa kwenye Claude Code bila mabadiliko. Funguo maalum za harness na vipengele vya mwili (body features) vilivyo nje ya spec hiyo hupuuzwa au kukataliwa kwingineko, hivyo yaepuke kwenye ujuzi wowote unaokusudia kuushiriki kwa mapana.