Jinsi ya kushiriki agent skills bila drift kati ya repos
Nakili skill kwenye repos 8 na nakala zitatofautiana. Tumia repo moja iliyoshirikiwa, tag ya version, na kila project ibane na ikague utegemezi wake.
Jinsi ya kushiriki ujuzi wa wakala (agent skills) kati ya hazina (repos) mbalimbali
Ili kushiriki ujuzi wa wakala kati ya hazina mbalimbali, acha kunakili faili na anza kuitegemea. Tunza hazina moja ya ujuzi, iweke alama (tag), na uruhusu kila mradi ufunge (pin) alama hiyo. Kisha ongeza jaribio la uthibitisho (smoke test) kwa kila ujuzi, na kagua kila ongezeko la toleo (bump) kama unavyokagua ongezeko la utegemezi (dependency bump).
Hii ina sehemu nne: chanzo kimoja cha ukweli, toleo lililofungwa kwa kila hazina, jaribio la uthibitisho 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 mwenyeji wa nje wa git au sajili ya vifurushi (package registry). Majaribio ya uthibitisho ndiyo ubaguzi pekee. Huendeshwa na Claude Code, ambayo hutuma kila ombi kwenye API ya modeli, kwa hivyo hatua hiyo bado huondoka kwenye seva yako.
Ujuzi wa wakala ni folda iliyo na faili ya SKILL.md, pamoja na hati (scripts) na faili zozote za marejeleo inazohitaji. Ikiwa kitengo hicho ni kipya, soma nini ujuzi wa wakala ulivyo 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 yafuatayo, miongoni mwa mengine, na nyaraka za ujuzi hutaja kila njia.
.claude/skills/<skill-name>/SKILL.mdndani ya saraka ya mipangilio inayodhibitiwa ni eneo la biashara. Hupakia kwa kila mtumiaji kwenye mashine ambapo shirika huichapisha.~/.claude/skills/<skill-name>/SKILL.mdni ya kibinafsi. Hupakia katika miradi yako yote na si ya mtu mwingine yeyote..claude/skills/<skill-name>/SKILL.mdni ya kiwango cha mradi. Hupakia kwa yeyote anayetoa (check out) hazina (repository) hiyo.<plugin>/skills/<skill-name>/SKILL.mdhusafirishwa ndani ya plugin. Hupakia popote ambapo plugin hiyo imewezeshwa.
Claude Code pia hupakia ujuzi kutoka saraka za miradi zilizowekwa ndani ya nyingine, saraka zilizotolewa na --add-dir, na ujuzi uliowezeshwa kwa akaunti yako ya claude.ai.
Ujuzi wa kiwango cha mradi ndio unaofaa kwa timu, kwa sababu hufanyiwa commit na kila mtu anayekopi (clone) hazina hiyo huupata. Hapa ndipo matatizo yanapoanzia. Ujuzi katika .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 uainishaji huo huchapisha orodha wakati unapotumia nyingine:
Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, nameAngalia kile ambacho hakipo: hakuna ufunguo wa version. Toleo linaweza kurekodiwa chini ya metadata, lakini uainishaji haufafanui pini ya utegemezi (dependency pin) au utaratibu wa kusasisha. Hilo ni jambo la busara, kwa sababu ujuzi ni hati badala ya kifurushi. Hii inamaanisha kuwa utoaji wa matoleo lazima utoke kwenye safu inayozunguka faili, na safu hiyo ni jukumu lako.
Tatizo la kwanza: nakala nane zinazoanza kutofautiana kimya kimya
Kununakili na kubandika hufanya kazi siku ya kwanza. Hushindwa siku ya sitini. Mtu anarekebisha maelekezo yasiyo sahihi katika repo ya payments, lakini hazigusi zile saba nyingine. Mtu mwingine anaongeza kanuni kuhusu pagination katika orders. Sasa jina lilelile la skill hutoa ukaguzi tofauti kulingana na directory ambayo agent ilianzishwamo, na hakuna developer anayejua.
Kushindwa huku hutokea bila kuonekana kwa sababu hakuna hali ya error. Skill ni maandishi. Maelekezo yaliyopitwa na wakati husababisha jibu lenye kujiamini lakini lisilo sahihi, na hilo ndilo tatizo lenye gharama kubwa. Hakuna kitu katika agent kinacholinganisha nakala yako na nakala za wengine, kwa hiyo ishara pekee ni mtu kugundua kwamba repo mbili hazikubaliani.
Tatizo la pili: hakuna kinachobainisha toleo
Hata timu inapoweka ujuzi wote mahali pamoja, njia ya kawaida ya kushiriki ni hatua ya kunakili: script ya usanidi, mstari wa curl kwenye hati ya kuanza kazi, au shell alias inayosawazisha folda. Njia hizi zote husakinisha kile kilicho kwenye kilele cha branch kwa sasa.
Hii inamaanisha kuwa developers wawili wanaotumia commit moja ya application moja wanaweza kuwa wanaendesha maelekezo tofauti, kwa sababu waliendesha usawazishaji katika siku tofauti. Pia inamaanisha huwezi kujibu swali muhimu baada ya agent kuendesha vibaya: ni toleo gani la skill lililosababisha hali hii? Bila revision iliyorekodiwa, uendeshaji huo hauwezi kurudiwa kwa usahihi, kwa hiyo ripoti ya hitilafu haiwezi kusaidia uchunguzi.
Tatizo la tatu: hakuna anayejua kama skill bado inafanya kazi
Skill haina compiler. Ni maelekezo yanayolenga model, kwa hiyo inaweza kuacha kufanya kazi huku faili likibaki sawa byte kwa byte. Upgrade ya model hubadilisha kiwango ambacho inafuata kwa ukaribu maelekezo marefu. Command-line tool inayotumiwa na skill hubadilisha jina la flag. URL iliyo kwenye reference file huanza kurudisha 404, na agent hutumia error page kama chanzo.
Hakuna hali yoyote kati ya hizi inayosababisha failure ionekane wazi. Agent bado inajibu. Jibu huwa baya zaidi kuliko lilivyokuwa mwezi uliopita, na hilo ni jambo gumu kugundua hatua kwa hatua katika 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, v1.7.2 kufikia tarehe 9 Oktoba 2026) husakinisha ujuzi (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. Inatunza faili mbili za lock. Faili ya kimataifa kwenye ~/.agents/.skill-lock.json hurekodi kile mtumiaji mmoja alichosakinisha. Tangu v1.4.1 (20 Februari 2026), kusakinisha kwenye wigo wa mradi pia huandika skills-lock.json kwenye mzizi wa mradi, na msimbo wa chanzo wa zana hiyo unasema faili hiyo inakusudiwa kuingizwa kwenye mfumo wa udhibiti wa toleo (version control). npx skills experimental_install hurejesha ujuzi wa mradi kutoka humo. Suala namba 283, lililoomba amri ya skills install kurejesha faili ya lock ya kimataifa kwenye mashine nyingine, lilifungwa kama lisilopangwa tarehe 5 Novemba 2026; msimamizi anaitambua kama ombi lilelile la suala namba 549. Soma yote mawili kama ripoti ya hali. Faili ya lock ya kila mradi ipo. Katika toleo lililotolewa la v1.8.1, amri ya kurejesha bado imeandikwa kama ya majaribio kwenye usaidizi, lakini npx skills install bila chanzo pia hurejesha faili ya lock ya mradi.
Specs na majaribio. SkillSpec inachukua mtazamo mwingine. Inachukulia SKILL.md kama mkataba wa kukaguliwa badala ya maandishi ya kuaminiwa, ikiwa na lengo lililotajwa la kufanya ujuzi "kufuatikana, kujaribika, na kuthibitika". skillspec doctor <path> huripoti mahali ambapo wakala ana uwezekano wa kuacha mnyororo wa mawasiliano. skillspec boundary map <path> huonyesha kile ujuzi unachokibeba, na skillspec boundary assess <path> huripoti kile kinachoweza kufikiwa, kikiwa kimepangwa kwa hatari. Hii ni crate ya Rust, yenye leseni mbili ya MIT au Apache 2.0. Toleo la 0.2.2 lilichapishwa tarehe 29 Julai 2026 na bado ndilo jipya zaidi kwenye crates.io kufikia tarehe 10 Oktoba 2026. Sakinisha toleo lililofungwa (pinned) badala ya lile jipya zaidi:
cargo install skillspec --version 0.2.2 --locked
skillspec --versionTangu Cargo 1.100, iliyotolewa tarehe 12 Novemba 2026, cargo install hutumia faili ya lock iliyopakiwa kwa chaguo-msingi, na --locked haifanyi kazi yoyote. skillspec --version inapaswa kuchapisha 0.2.2. Namba tofauti inamaanisha binary ya zamani iliyo mapema kwenye PATH yako ndiyo inayotumika.
Mazoea ya uuzaji (Vendor practice). Google ilielezea jinsi inavyojenga ujuzi katika google/skills kwenye chapisho kuhusu jinsi inavyojenga, kujaribu na kupima ujuzi wa wakala. Ondoa kipimo na utaratibu huo ni ujumuishaji endelevu (CI) wa kawaida. Kila ujuzi hupita linters kwa ajili ya metadata ya frontmatter, idadi ya mistari, mpangilio wa saraka na majina kabla ya kuunganishwa. Kichunguzi cha viungo (link checker) husimamisha ujenzi kwenye URL yoyote inayorejesha 404, jambo linalokamata kiungo kinachoonekana kuwa sahihi ambacho wakala alikibuni. Waandishi lazima watoe seti ya maelekezo ya tathmini na mwongozo wa alama pamoja na ujuzi huo. Kazi za tathmini zilizopangwa kisha huendeshwa kila wiki dhidi ya maktaba nzima ili kukamata hitilafu, na kila ujuzi una mmiliki aliyetajwa ambaye anatarajiwa kuurekebisha wakati ubora unaposhuka.
Muundo ulio chini ya majibu yote matatu
Si lazima uchague mojawapo. Chini yake kuna muundo mmoja, na git ya kawaida inakupa kila kitu unachohitaji.
- Chanzo kimoja cha ukweli. Skill ina mahali pamoja pekee, na kila repository hurejelea mahali hapo badala ya kuhifadhi nakala.
- Toleo lililofungwa kwa kila repository. Kila mradi huhifadhi revision halisi unayotumia, kwa hiyo kuboresha ni kufanya commit katika mradi huo ikiwa na mwandishi na tarehe.
- Smoke test kwa kila skill. Kuna ukaguzi mmoja unaoweza kuendeshwa unaothibitisha kwamba skill bado inazalisha matokeo iliyoahidi.
- Njia ya ukaguzi. Mabadiliko kwenye skill inayoshirikiwa hupitia ukaguzi, na kila mtumiaji huona tofauti kabla ya kuyapokea.
Huo ndio muundo wa dependency. Skills zikawa artifact inayoshirikiwa kwa kasi zaidi kuliko zana zilivyokua kuziunga mkono, kwa hiyo zana unazoziamini tayari ndizo salama zaidi kutumia.
Muundo wa timu ndogo inayotumia git remote iliyojihostia
Repository moja huhifadhi maarifa ya timu. Hakuna kitu kingine kinachowekwa humo, kwa hiyo 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.mdReleases ni tags. Tumia annotated tags kwa sababu hubeba ujumbe na tarehe. Andika ujumbe huo ukieleza sababu ambayo mtumiaji angependa kufanya bump:
git tag -a v1.4.0 -m "api-review: require pagination on list endpoints"
git push origin v1.4.0Ikiwa remote yako ni Gitea, Forgejo, GitLab au bare repository kupitia SSH kwenye VPS yako, hakuna kinachobadilika katika hatua zinazofuata. Kila kitu hapa ni git pamoja na symlink.
Kuweka commit maalum kwa kutumia git submodule
Submodule huhifadhi commit moja maalum ya repository nyingine ndani ya repository yako. Rekodi hiyo ndiyo pin. Katika kila project inayotumia submodule:
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 inayofanya utaratibu huu ufanye kazi. Skill entry ya kiwango cha project inaweza kuwa symlink inayoelekeza kwenye directory nyingine kwenye disk, na Claude Code huifuata na kusoma SKILL.md kutoka kwenye target. Kwa hiyo, skill hupakiwa kama project skill ya kawaida, huku bytes zikiwa kwenye submodule katika commit uliyochagua.
Kagua pin:
git submodule statusMstari sahihi huanza na space, ukifuatiwa na commit, path, kisha tag iliyo karibu zaidi:
4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602 vendor/agent-skills (v1.4.0)- mwanzoni humaanisha kuwa submodule haikuwahi kuanzishwa, kwa hiyo .claude/skills/api-review haielekezi popote na skill haipakii bila kutoa ujumbe. Rekebisha hilo kwa git submodule update --init. + mwanzoni humaanisha kuwa commit iliyokaguliwa inatofautiana na ile iliyohifadhiwa, kwa hiyo developer huyo anaendesha instructions ambazo wengine hawana. Clone mpya zinahitaji git clone --recurse-submodules, na mstari huo unapaswa kuwekwa kwenye README, kwa sababu clone ya kawaida huacha vendor/agent-skills ikiwa tupu na haitoi error.
Kuboresha hufanywa kwa makusudi, na hilo ndilo 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 ndiyo njia ya review. Unaonyesha mabadiliko yaleyale ambayo kila repo nyingine inayotumia submodule itaona, na unaweza kuuweka kwenye pull request.
Kufunga toleo (pinning) kwa kutumia soko la plugin badala yake
Ikiwa hutaki kuwataka watengenezaji wote wajifunze submodules, mfumo wa plugin wa Claude Code hukufanyia usambazaji, na hufanya kazi dhidi ya remote inayojiendesha (self-hosted). Weka katalogi kwenye .claude-plugin/marketplace.json katika 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), kumaanisha mahali ambapo katalogi yenyewe huchotwa, hukubali ref kwa ajili ya branch au tag na, katika Claude Code v2.1.324 au matoleo mapya zaidi, commit SHA kamili ya herufi ndogo; haikubali uwanja tofauti wa sha. Chanzo cha plugin ndani ya katalogi hukubali vyote viwili, na wakati vyote vikiwa vimewekwa, sha ndiyo inayotumika kama pin halisi. Funga katalogi kupitia ref ya chanzo chake cha soko na plugin kupitia sha ya ingizo la katalogi. Majina ya aina (type names) pia hutofautiana. Ndani ya katalogi, url inamaanisha hazina ya git ya ku-clone. Katika chanzo cha soko, url inamaanisha kiungo cha moja kwa moja cha faili ya marketplace.json, na hazina ya git ni git.
Kila hazina inayotumia (consuming repository) hutangaza soko hilo katika faili yake ya .claude/settings.json iliyohifadhiwa:
{
"extraKnownMarketplaces": {
"acme-agents": {
"source": {
"source": "git",
"url": "https://git.example.com/team/agent-skills.git",
"ref": "v1.4.0"
}
}
},
"enabledPlugins": {
"team-skills@acme-agents": true
}
}Claude Code husajili soko hilo kwa mfanyakazi mwenza mara tu anapokubali mazungumzo ya uaminifu wa workspace (workspace trust dialog) kwa folda ya mradi, bila kuhitaji ukurasa wa wiki kumwambia afanye hivyo. Ingizo la katalogi huelekeza kwenye URL ya git badala ya njia ya jamaa (relative path), kwa hivyo plugin yenyewe haisakinishwi kutoka kwa mipangilio ya hazina pekee. Kila mfanyakazi mwenza huendesha claude plugin install team-skills@acme-agents --scope project mara moja, na hadi wakati huo Claude Code huripoti kuwa plugin imewezeshwa katika mipangilio ya mradi lakini haijasakinishwa. Skills kisha hujibu kwa /team-skills:api-review, kwa sababu skills za plugin huwekwa kwenye namespace kwa jina la plugin na haziwezi kugongana na skill ya mradi yenye jina sawa. Baada ya kusukuma (push) tag mpya na kusasisha pins kwenye katalogi na hazina zinazotumia, watumiaji huburudisha kwa /plugin marketplace update acme-agents, kisha huendesha /reload-plugins ikiwa muhtasari wa usakinishaji utaiomba.
Kuandika smoke test kwa ajili ya skill moja
Smoke test ni script ya agent inayofanya kazi dhidi ya fixture yenye kosa linalojulikana, pamoja na assertion moja. Claude Code hufanya kazi bila mwingiliano na -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/nullfixtures/orders-api.md ni faili fupi lenye kosa moja la makusudi. Assertion ni kwamba skill hiyo inalitaja kosa hilo. jq -e hutoka kwa status isiyo zero wakati filter yake inazalisha null, kwa hiyo skill inayoacha kunasa kosa lililopandikizwa itafanya script hiyo ifeli. claude yenyewe hutoka kwa status isiyo zero wakati run inafeli, na set -euo pipefail hubadilisha failure yoyote kuwa test iliyofeli.
Model hubadilisha maneno ya majibu yake kati ya run moja na nyingine, kwa hiyo usiwahi kufanya assertion kwenye sentensi nzima. Fanya assertion kwenye kitambulishi (identifier) ambacho skill inatakiwa kukitoa, au kwenye field ya schema uliyoiomba, na iweke fixture hiyo ndogo ili run iwe ya gharama nafuu.
Katika CI, ongeza --bare. Bila hiyo, claude -p hupakia muktadha uleule ambao session ya mwingiliano ingekuwa nao, ikijumuisha hooks, plugins na CLAUDE.md kutoka kwenye mashine inayoendesha, kwa hiyo configuration ya kibinafsi ya mfanyakazi mwenzako inaweza kubadilisha matokeo. Bare mode huruka auto-discovery isipokuwa kwa skills zilizopo kwenye .claude/skills/ chini ya directory iliyotolewa waziwazi na --add-dir; inaruka project skill unayoijaribu hapa, kwa hiyo ipakie hiyo moja waziwazi. Bare mode haisomi pia login yako ya usajili, kwa hiyo 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 jsonPlugin iliyopakiwa na --plugin-dir huchukua jina lake kutoka .claude-plugin/plugin.json, na bila manifest hiyo inaitwa kwa jina la directory yake. Commit plugin.json yenye "name": "team-skills" karibu na catalog katika repository ya skills, au amri iliyo hapo juu italazimika kuita /agent-skills:api-review badala yake.
Kwa --output-format stream-json, tukio la system/init huripoti ni plugins zipi zilizopakiwa na hubeba array ya plugin_errors kwa zile ambazo hazikupakiwa. Hufungua stream isipokuwa matukio ya startup yakija kwanza. Fanya CI job ifeli kwenye plugin_errors isiyo tupu. Hiyo 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 hili kuwa 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 kwenye mwili wa maandishi ni preprocessing:
- Current branch: !`git rev-parse --abbrev-ref HEAD`Amri hiyo huendeshwa kwenye mashine inayopakia ujuzi huo, na matokeo yake huchukua nafasi ya placeholder katika maandishi yanayopokelewa na modeli. Kizuizi kilichofungwa kwa alama tatu za backtick kikifuatiwa na ! huendesha amri kadhaa kwa njia hiyo hiyo. Hakuna mtu anayeulizwa idhini kwa lolote kati ya haya wakati wa utekelezaji. Claude Code hukagua kila amri dhidi ya sheria zako za ruhusa. Nje ya hali ya auto, amri ambayo sheria hizo haziruhusu husitisha ujuzi huo, isipokuwa ujuzi huo uwe umeikubali mapema kupitia kipengele cha pili hapa chini. Sheria za kukataa (deny) na kuuliza (ask) bado hupuuza idhini hiyo ya awali. 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 iliyoitisha ujuzi huo. Uaminifu wa workspace hauzuii idhini hiyo: Claude Code hutumia allowed-tools ya ujuzi wa mradi hata katika -p inayofanywa kwenye folda ambayo hakuna mtu aliyeiamini. Nyaraka za Claude Code zinaeleza matokeo yake wazi: ujuzi unaweza kujipa ufikiaji mpana wa zana, kwa hivyo kagua allowed-tools ya ujuzi uliowekwa kwenye repository kabla ya kuendesha Claude Code hapo. Shirika linaweza kuzuia sehemu hiyo kutoka kwa ujuzi wa mradi na ujuzi wa kibinafsi kwa kuweka allowManagedPermissionRulesOnly katika mipangilio inayodhibitiwa (managed settings), ambayo inahitaji Claude Code v2.1.282 au toleo jipya zaidi.
Kwa hivyo, shughulikia sasisho la ujuzi (skill bump) kama unavyoshughulikia sasisho la dependency. Funga toleo kwa kutumia commit kamili popote utaratibu unaporuhusu, kwa sababu tag inaweza kubadilishwa 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 kuipuuza. Ujuzi uliounganishwa (bundled) na unaodhibitiwa (managed) hauhusiki na mpangilio huo.
Tahadhari hiyo hiyo inatumika 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 ufunuo huo huo 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.
Cha kusoma wakati wa kusasisha toleo
- Diff ya kila
SKILL.mdbody, kwa sababu maandishi hayo ndiyo maagizo ambayo agent yako itafuata. - Kila command substitution, kwa sababu hizo hutekelezwa kwenye mashine yako skill inapopakia.
- Mabadiliko yoyote kwenye
allowed-tools, kwa sababu mstari huo hutoa zana bila kuomba uthibitisho. - Utekelezaji wa test ulio nyuma ya tag. Ikiwa repository inayoshirikiwa huendesha smoke tests zake katika CI, tag unayoweka pin inapaswa kuwa na run iliyofanikiwa iliyoambatishwa.
Reviewer ambaye hawezi kusoma diff yote ndani ya dakika kumi anaangalia skill iliyokua kubwa kupita kiasi. Igawanye. Hoja hiyo hiyo inatumika kwa nyaraka za repository ambazo agents wako husoma: weka kanuni za kudumu katika faili zilizoelezwa kwenye mgawanyo wa AGENTS.md na HUMAN.md, na hoja za usanifu katika DESIGN.md iliyoandikwa kwa agents, kisha acha skills zibaki kuwa procedures finyu.
Mabadiliko ya model au tool yanapoharibu skill
Mambo kadhaa yanaweza kubadilika ndani ya skill bila mtu yeyote kuihariri. Upgrade ya model hubadilisha jinsi inavyofuata kwa uhakika instruction ndefu, hivyo skill iliyotegemea model kufikia hatua ya tisa inaweza kuacha kuifikia. Command line tool inaweza kubadilisha jina la flag, hivyo agent ikaendesha flag ya zamani, ikasoma error, kisha ikaamua hatua kwa kubahatisha. URL iliyorejelewa inaweza kuanza kurudisha 404. Agent harness inaweza kubadilisha jinsi inavyochagua skills, hivyo description iliyokuwa ikishinda ulinganifu inaweza isishinde tena. Procedure inapoanza kumalizika mapema kwa njia hiyo, kuongeza version hakutarekebisha tatizo. Maelekezo yenyewe yanahitaji muundo unaolazimisha hatua za mwisho kukamilishwa. Huo ndio msingi wa skill ya unlazy na mbinu yake ya Depth Tree.
Ndiyo maana smoke test huwa na uzito katika mpangilio huu. Endesha test ya kila skill kwa ratiba, na pia kila unapofanya push. Google huendesha evaluation jobs zake kila wiki dhidi ya library nzima kwa sababu hii. Kwa timu yenye skills kumi, weekly cron job kwenye VPS ndogo inatosha. Hii ndiyo njia pekee ya kupata taarifa kuhusu kuvurugika kabla developer hajakugundua.
Portability pia husaidia. Agent Skills spec inaweka frontmatter kwenye keys sita, hivyo skill iliyoandikwa kulingana na spec hiyo inaweza kupakiwa kwenye tools nyingine zaidi ya ile iliyoandikiwa. Kila key maalum kwa harness unayoongeza ni kamari kwenye vendor mmoja. Kuandika skills zinazostahimili kubadilishwa kwa model ni discipline yake yenyewe. Imeelezwa katika jinsi ya kufanya skill ifanye kazi kwenye model 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 uelekeze kwenye tag 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 isomeke 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 matokeo ya agent fulani.
Je, ninaweza kuweka pin ya ujuzi wa agent kwenye toleo maalum?
Huwezi kufanya hivyo kutoka ndani ya SKILL.md, kwa sababu frontmatter hiyo haina ufunguo wa version. Pin lazima itoke kwenye safu inayozunguka faili hiyo. Git submodule huweka pin kwenye 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 ikiwa zote zipo. Chanzo cha soko lenyewe hukubali ref kwa ajili ya branch, tag, au katika Claude Code v2.1.324 au matoleo mapya zaidi, SHA kamili ya commit kwa herufi ndogo. Pendelea kutumia commit kama pin, 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 --output-format json na --json-schema hufanya uhakiki kuwa sahihi, na jq -e husababisha script kufeli wakati thamani hiyo haipo. Usiwahi kuhakiki sentensi nzima, kwa sababu model hubadilisha maneno ya majibu yake kati ya uendeshaji mmoja na mwingine.
Je, ni salama kusakinisha ujuzi ulioshirikiwa kutoka kwenye repository ya timu nyingine?
Ichukulie kama dependency ya msimbo, kwa sababu ni maelekezo yanayoweza kutekelezwa. SKILL.md inaweza kuendesha amri za shell wakati wa kupakia (load time) kupitia mfumo wa ! wa kubadilisha amri, na uwanja wa allowed-tools kwenye frontmatter unaweza kuidhinisha zana mapema bila kuuliza. Soma diff kila wakati toleo linapopanda, weka pin kwenye commit kamili badala ya branch, na pendelea chanzo ambacho timu yako inakidhibiti. Kwenye mashine zinazosimamiwa, "disableSkillShellExecution": true katika mipangilio huzuia ubadilishaji wa amri katika ujuzi wa mtumiaji, mradi, plugin, na saraka za ziada; ujuzi uliounganishwa (bundled) na unaosimamiwa haujaathiriwa na hili.
Je, ujuzi ulioshirikiwa utafanya kazi katika agents nyingine mbali na Claude Code?
Hiyo inategemea ni frontmatter ipi unayotumia. Ufafanuzi wa Agent Skills unafunguo sita: name, description, license, compatibility, metadata na allowed-tools. Ujuzi uliopunguzwa kwenye funguo hizo hupakia katika zana zinazotekeleza ufafanuzi huo, na pia hupakia katika Claude Code bila mabadiliko. Funguo maalum za harness na vipengele vya mwili (body features) vilivyo nje ya ufafanuzi huo hupuuzwa au kukataliwa kwingineko, kwa hivyo yaepuke kwenye ujuzi wowote unaokusudia kuushiriki kwa mapana.