SSD Nodes Learn Hosting plans →
Mga Gabay Matt ConnorNi Matt Connor

Paano Magbahagi ng Agent Skills Nang Walang Drift

Alamin kung paano palitan ang pagkopya sa walong repo: isang shared skills repo, naka-pin na version bawat proyekto, smoke test, at review sa update.

Paano magbahagi ng agent skills sa iba’t ibang repo

Para magbahagi ng agent skills sa iba’t ibang repo, itigil ang pagkopya ng file at gawin itong dependency. Magpanatili ng isang skills repository, lagyan ito ng tag, at hayaan ang bawat proyekto na mag-pin sa isang tag. Pagkatapos, magdagdag ng smoke test para sa bawat skill, at i-review ang bawat pag-update nito gaya ng pag-review sa pag-update ng dependency.

Apat ang bahaging ito: isang shared source of truth, naka-pin na bersyon para sa bawat repository, smoke test para sa bawat skill, at review path. Ipinapaliwanag sa ibaba kung bakit kailangan ang bawat bahagi, paano ito hinahandle ng mga tool na nire-release sa 2026, at paano buuin ang buong setup gamit ang self-hosted git remote nang walang external git host o package registry. Ang smoke tests ang tanging exception. Pinapatakbo ng mga ito ang Claude Code, na nagpapadala ng bawat request sa isang model API, kaya lumalabas pa rin sa server mo ang hakbang na iyon.

Ang agent skill ay isang folder na naglalaman ng SKILL.md file, kasama ang anumang script at reference file na kailangan nito. Kung bago sa iyo ang unit na ito, basahin muna ang ano ang agent skill at paano gumagana ang SKILL.md. Tungkol ang page na ito sa supply chain na nakapalibot sa unit na iyon.

Kung saan nakalagay ang skill, at bakit mahirap itong ibahagi

Nilo-load ng Claude Code ang mga skill mula sa mga sumusunod na lokasyon, bukod sa iba pa, at tinutukoy ng dokumentasyon ng skills ang bawat path.

  • Ang .claude/skills/<skill-name>/SKILL.md sa loob ng managed settings directory ang lokasyon para sa enterprise. Nilo-load ito para sa bawat user sa mga machine kung saan dine-deploy ito ng isang organisasyon.
  • Personal ang ~/.claude/skills/<skill-name>/SKILL.md. Nilo-load ito sa lahat ng iyong project, pero hindi sa project ng iba.
  • Project level ang .claude/skills/<skill-name>/SKILL.md. Nilo-load ito para sa sinumang nag-checkout ng repository na iyon.
  • Kasama sa isang plugin ang <plugin>/skills/<skill-name>/SKILL.md. Nilo-load ito saanman naka-enable ang plugin na iyon.

Nilo-load din ng Claude Code ang mga skill mula sa nested project directory, mga directory na ibinibigay gamit ang --add-dir, at mga skill na naka-enable para sa iyong claude.ai account.

Ang project-level na lokasyon ang kapaki-pakinabang para sa isang team dahil naka-commit ito, at makukuha ito ng lahat ng nag-clone ng repository. Dito rin nagsisimula ang problema. Ang skill sa .claude/skills/ ay pagmamay-ari ng isang repository. Mayroon kang walong repository. Kaya walong beses nakokopya ang skill.

Walang naitutulong ang frontmatter. Pinapayagan ng Agent Skills spec ang anim na key, at inililista ng mga distribution path na nagpapatupad nito ang mga key na iyon kapag gumamit ka ng iba:

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

Pansinin kung ano ang wala: walang version key. Maaaring itala ang isang version sa ilalim ng metadata, pero walang tinutukoy ang spec na dependency pin o mekanismo para sa update. Makatuwiran ito dahil document ang isang skill, hindi package. Nangangahulugan ito na kailangang manggaling sa layer sa paligid ng file ang versioning, at ikaw ang kailangang mamahala sa layer na iyon.

Problema isa: walong kopya na tahimik na naghihiwalay

Gumagana ang copy-paste sa unang araw. Nabibigo ito sa ika-animnapung araw. May nag-aayos ng maling instruction sa payments repo at hindi nito ginalaw ang pito pang iba. May iba namang nagdagdag ng rule tungkol sa pagination sa orders. Ngayon, ang parehong skill name ay nagbibigay ng dalawang magkaibang review depende sa kung saang directory nagsimula ang agent, at walang alam ang mga developer.

Ang pagkabigo ay tahimik dahil walang error state. Ang isang skill ay prose. Ang lumang instruction ay nagbubunga ng kampante ngunit maling sagot, na siyang magastos na uri ng pagkakamali. Walang anuman sa agent ang nagkukumpara ng iyong kopya laban sa iba, kaya ang tanging signal ay ang mapansin ng isang tao na hindi magkatugma ang dalawang repo.

Problema dalawa: walang naka-pin na bersyon

Kahit na pinapanatili ng isang team ang mga skill sa iisang lugar, ang karaniwang paraan ng pagbabahagi ay sa pamamagitan ng pag-copy: isang setup script, isang curl line sa onboarding doc, o isang shell alias na nag-si-sync ng folder. Lahat ng ito ay nag-i-install ng kung ano man ang nasa head ng branch sa kasalukuyan.

Ibig sabihin nito, ang dalawang developer na nasa parehong commit ng parehong application ay maaaring nagpapatakbo ng magkaibang instruction, dahil nag-sync sila sa magkaibang araw. Ibig sabihin din nito, hindi mo masasagot ang tanong na mahalaga matapos ang isang bad agent run: anong bersyon ng skill ang gumawa nito? Kung walang naitalang revision, hindi ma-reproduce ang run, kaya hindi rin maaksyunan ang bug report.

Problema tatlo: walang nakakaalam kung gumagana pa ang skill

Ang isang skill ay walang compiler. Ito ay mga instruction na nakatuon sa isang model, kaya maaari itong huminto sa paggana kahit na ang file ay nananatiling byte-for-byte na pareho. Ang pag-upgrade ng model ay nagbabago sa kung gaano kahigpit sinusunod ang isang mahabang instruction. Ang isang command line tool na tinatawag ng skill ay maaaring mag-rename ng flag. Ang isang URL sa isang reference file ay maaaring magsimulang mag-return ng 404 at ang agent ay magtatrabaho base sa error page.

Walang maingay na failure sa alinman sa mga kasong ito. Sumasagot pa rin ang agent. Ang sagot ay mas malala lang kaysa noong nakaraang buwan, na isang mahirap mapansin na bagay kung isa-isang pull request ang titingnan.

Mga Isinasaayos ng Mga Tool na Inilabas noong 2026

May ilang sagot na lumalabas ngayon, at hindi pare-pareho ang pananaw ng mga ito kung saan dapat ilagay ang bersyon.

Lockfiles. Ang skills command line tool mula sa Vercel Labs (vercel-labs/skills, lisensyado sa ilalim ng MIT, v1.7.2 noong 9 October 2026) ay nag-i-install ng skills mula sa isang git repository papunta sa directory na inaasahan ng iyong agent. Alam nito ang layout para sa mahigit pitumpung agent. Nag-i-install ang npx skills add <repo>, nag-a-upgrade ang npx skills update, at ipinapakita ng npx skills list kung ano ang mayroon ka. Dalawang lock file ang pinapanatili nito. Ang global na file sa ~/.agents/.skill-lock.json ay nagtatala ng mga na-install ng isang user. Mula noong v1.4.1 (20 February 2026), ang pag-install sa project scope ay sumusulat din ng skills-lock.json sa project root. Ayon sa source code ng tool, dapat isama ang file na ito sa version control. Nire-restore ng npx skills experimental_install ang skills ng isang project mula rito. Isinara ang Issue 283, na humihiling ng skills install command para ma-restore ang global lock file sa ibang machine, bilang hindi planado noong 5 November 2026. Itinuturing ito ng maintainer na kapareho ng request sa issue 549. Basahin ang dalawang isyung ito bilang ulat ng status. Umiiral ang per-project lockfile. Sa inilabas na v1.8.1, experimental pa rin ang label ng restore command sa help, ngunit nire-restore din ng npx skills install na walang source ang project lockfile.

Mga Spec at Test. Ibang direksiyon ang tinatahak ng SkillSpec. Itinuturing nito ang isang SKILL.md bilang kontratang dapat suriin, hindi prose na basta dapat pagkatiwalaan. Nakasaad na layunin nitong gawing “followable, testable, at provable” ang skills. Iniuulat ng skillspec doctor <path> kung saan malamang na mawalan ng thread ang isang agent. Ipinapakita ng skillspec boundary map <path> kung ano ang nilalaman ng skill, at iniuulat ng skillspec boundary assess <path> kung ano ang maaari nitong maabot, na inayos ayon sa risk. Isa itong Rust crate na dual licensed sa ilalim ng MIT o Apache 2.0. Inilabas ang Version 0.2.2 noong 29 July 2026 at ito pa rin ang pinakabago sa crates.io noong 10 October 2026. I-install ang naka-pin na bersyon sa halip na ang pinakabago:

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

Mula sa Cargo 1.100, na inilabas noong 12 November 2026, ginagamit ng cargo install ang naka-package na lockfile bilang default, at walang ginagawa ang --locked. Dapat i-print ng skillspec --version ang 0.2.2. Nangangahulugan ang ibang numero na mas lumang binary na mas nauuna sa iyong PATH ang ginagamit.

Paraan ng Vendor. Inilarawan ng Google kung paano nito binubuo ang mga skill sa google/skills sa isang post tungkol sa kung paano nito binubuo, tine-test, at pinapalawak ang agent skills. Kung aalisin ang usapin ng laki, ordinaryong continuous integration (CI) ang mekanismo. Dumadaan ang bawat skill sa mga linter para sa frontmatter metadata, bilang ng mga linya, directory layout, at naming bago ito ma-merge. Pinapabagsak ng link checker ang build kapag may URL na nagbabalik ng 404. Nahuhuli nito ang mukhang makatotohanang link na inimbento ng isang agent. Kailangang magbigay ang mga author ng evaluation prompt suite at scoring rubric kasabay ng skill. Pagkatapos, lingguhang tumatakbo ang mga naka-iskedyul na evaluation job laban sa buong library upang makahuli ng regressions. May nakatalagang owner ang bawat skill na inaasahang mag-aayos nito kapag bumaba ang kalidad.

Ang pattern sa ilalim ng tatlong sagot

Hindi mo kailangang pumili ng isa sa mga iyon. Sa ilalim ng mga ito ay may iisang hugis, at ibinibigay ito sa iyo ng plain git.

  1. Isang source of truth. Ang skill ay may iisang home lamang, at bawat repository ay tumutukoy sa home na iyon sa halip na magtabi ng kopya.
  2. Isang pinned version bawat repository. Itinatala ng bawat project ang eksaktong revision na ginagamit nito, kaya ang pag-upgrade ay isang commit sa project na iyon na may author at petsa.
  3. Isang smoke test bawat skill. Isang runnable check na nagpapatunay na ang skill ay naglalabas pa rin ng resultang ipinapangako nito.
  4. Isang review path. Ang pagbabago sa isang shared skill ay dumadaan sa review, at nakikita ng bawat consumer ang diff bago ito tanggapin.

Iyan ang hugis ng isang dependency. Mas mabilis naging shared artifact ang mga skill kaysa sa paglago ng tooling sa paligid nito, kaya ang tooling na pinagkakatiwalaan mo na ang pinakaligtas na gamitin.

Layout para sa maliit na team sa isang self-hosted git remote

Isang repository lang ang naglalaman ng mga skill. Walang ibang nakalagay dito, kaya ang history nito ay nagsisilbing changelog ng mga instruction.

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

Ang mga release ay mga tag. Gumamit ng annotated tags dahil nagdadala ang mga ito ng mensahe at petsa. Isulat ang mensahe bilang dahilan kung bakit kailangan ng consumer ang update:

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

Kung ang remote mo ay Gitea, Forgejo, GitLab, o isang bare repository sa pamamagitan ng SSH sa sarili mong VPS, walang magbabago sa mga susunod na hakbang. Ang lahat ng nakasaad dito ay git at isang symlink lamang.

Pag-pin gamit ang git submodule

Ang isang submodule ay nagtatala ng eksaktong commit ng isa pang repository sa loob ng iyong repository. Ang tala na iyon ang nagsisilbing pin. Sa bawat consuming project:

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"

Ang symlink ang bahaging nagpapagana nito. Ang isang skill entry sa antas ng project ay maaaring maging symlink patungo sa isang directory sa ibang bahagi ng disk, at sinusundan ito ng Claude Code para basahin ang SKILL.md mula sa target. Kaya naman, naglo-load ang skill bilang isang normal na project skill, habang ang mga byte ay nasa loob ng submodule sa commit na pinili mo.

I-check ang pin:

git submodule status

Ang isang maayos na linya ay nagsisimula sa space, susundan ng commit, pagkatapos ay ang path, at ang pinakamalapit na tag:

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

Ang panimulang - ay nangangahulugang hindi na-initialise ang submodule, kaya ang .claude/skills/api-review ay walang tinutukoy at tahimik na hindi maglo-load ang skill. Ayusin ito gamit ang git submodule update --init. Ang panimulang + ay nangangahulugang ang naka-check out na commit ay iba sa nakatala, kaya ang developer na iyon ay gumagamit ng mga instruction na wala sa iba. Kailangan ng mga bagong clone ang git clone --recurse-submodules, at ang linyang iyon ay dapat nasa README, dahil ang isang simpleng clone ay nag-iiwan sa vendor/agent-skills na walang laman at hindi naglalabas ng error.

Ang pag-upgrade ay sinasadya, na siyang pangunahing layunin nito:

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"

Ang linyang diff ang nagsisilbing review path. Ipinapakita nito ang parehong pagbabago na makikita ng iba pang consuming repo, at angkop ito sa isang pull request.

Sa halip, gumamit ng pinning sa pamamagitan ng plugin marketplace

Kung ayaw mong turuan ang bawat developer tungkol sa submodules, ang Claude Code plugin system na ang namamahala sa distribution para sa iyo, at gumagana ito sa self-hosted remote. Maglagay ng catalog sa .claude-plugin/marketplace.json sa skills repository:

{
  "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"
      }
    }
  ]
}

Dalawang magkaibang source ang ginagamit dito, at ang pagkalito sa mga ito ang karaniwang pagkakamali. Ang marketplace source, o ang lokasyon kung saan kinukuha ang catalog mismo, ay tumatanggap ng ref para sa branch o tag at, sa Claude Code v2.1.324 o mas bago, ng buong lowercase commit SHA; hindi ito tumatanggap ng hiwalay na sha field. Ang plugin source sa loob ng catalog ay tumatanggap ng pareho, at kapag parehong nakatakda ang mga ito, ang sha ang aktuwal na pin. I-pin ang catalog sa pamamagitan ng ref ng marketplace source nito, at i-pin ang plugin sa pamamagitan ng sha ng entry nito sa catalog. Magkaiba rin ang mga pangalan ng type. Sa loob ng catalog, ang url ay nangangahulugang git repository na ika-clone. Sa marketplace source, ang url ay nangangahulugang direktang link sa marketplace.json file, at ang git repository ay git.

Idinedeklara naman ng bawat consuming repository ang marketplace sa committed nitong .claude/settings.json:

{
  "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
  }
}

Ire-register ng Claude Code ang marketplace para sa isang teammate kapag tinanggap nila ang workspace trust dialog para sa project folder, nang hindi kailangan ng wiki page na nagsasabing gawin nila ito. Tumuturo ang catalog entry sa isang git URL sa halip na relative path, kaya hindi nai-install ang plugin mula sa settings lang ng repository. Isinasagawa ng bawat teammate ang claude plugin install team-skills@acme-agents --scope project nang isang beses, at hanggang hindi ito nagagawa, iniuulat ng Claude Code na enabled ang plugin sa project settings pero hindi ito installed. Dahil dito, available ang skills sa ilalim ng /team-skills:api-review, dahil naka-namespace ang plugin skills ayon sa plugin name at hindi sila maaaring magbanggaan sa project skill na may parehong pangalan. Pagkatapos mong mag-push ng bagong tag at i-update ang mga pin sa catalog at sa mga consuming repository, nagre-refresh ang mga consumer gamit ang /plugin marketplace update acme-agents, at saka nila pinapatakbo ang /reload-plugins kung hinihingi ito ng install summary.

Pagsulat ng smoke test para sa isang skill

Ang smoke test ay isang scripted na agent run laban sa fixture na may kilalang fault, kasama ang isang assertion. Tumatakbo ang Claude Code nang non-interactively gamit ang -p, at gumagana roon ang skill na tinatawag ng user: ilagay ang /skill-name sa prompt string at ie-expand ito bago magsimula ang run.

#!/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

Ang fixtures/orders-api.md ay isang maikling file na may isang sinadyang fault. Ang assertion ay dapat pangalanan ito ng skill. Nag-e-exit ang jq -e nang non-zero kapag nagbunga ang filter nito ng null, kaya mabibigo ang script kapag hindi na natutukoy ng skill ang seeded fault. Nag-e-exit din ang claude nang non-zero kapag nabigo ang run, at ginagawang failed test ng set -euo pipefail ang alinman sa dalawang failure.

Binabago ng model ang pagkakabuo ng mga sagot nito sa bawat run, kaya huwag mag-assert batay sa isang buong pangungusap. Mag-assert batay sa identifier na dapat i-emit ng skill, o sa field ng schema na hiniling mo, at panatilihing maliit ang fixture para hindi maging magastos ang run.

Sa CI, idagdag ang --bare. Kung wala ito, nilo-load ng claude -p ang parehong context na ginagamit ng interactive session, kasama ang hooks, plugins, at CLAUDE.md mula sa machine kung saan ito tumatakbo. Dahil dito, maaaring baguhin ng personal na configuration ng isang teammate ang resulta. Nilalaktawan ng bare mode ang auto-discovery, maliban sa mga skill sa .claude/skills/ sa loob ng directory na tahasang ibinigay gamit ang --add-dir. Nilalaktawan nito ang project skill na sinusubukan mo rito, kaya i-load ito nang tahasan. Hindi rin binabasa ng bare mode ang iyong subscription login, kaya itakda muna ang ANTHROPIC_API_KEY sa environment:

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

Ang plugin na nilo-load gamit ang --plugin-dir ay kumukuha ng pangalan nito mula sa .claude-plugin/plugin.json. Kung wala ang manifest na iyon, ipinapangalan ito batay sa directory nito. Mag-commit ng plugin.json kasama ang "name": "team-skills" sa tabi ng catalog sa skills repository. Kung hindi, kailangang tawagin ng command sa itaas ang /agent-skills:api-review.

Kapag ginamit ang --output-format stream-json, iniuulat ng system/init event kung aling mga plugin ang na-load at naglalaman ito ng plugin_errors array para sa mga hindi na-load. Binubuksan nito ang stream maliban kung mauuna ang startup events. I-fail ang CI job kapag hindi walang laman ang plugin_errors. Natutukoy nito ang pin na tumutukoy sa revision na wala na, na kung hindi ay magmumukhang tahimik na binabalewala ng agent ang mga house rule mo.

Ang shared skill ay executable instruction

Dalawang feature ang dahilan kung bakit literal itong executable, at parehong mahalaga kapag galing sa ibang team ang file.

Una, maaaring magpatakbo ng shell commands ang isang SKILL.md bago magbasa ng anuman ang model. Ang ganitong linya sa body ay preprocessing:

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

Tumatakbo ang command sa machine na naglo-load ng skill, at pinapalitan ng output nito ang placeholder sa text na natatanggap ng model. Ang fenced block na binuksan ng tatlong backtick na sinusundan ng ! ay nagpapatakbo ng ilang command sa parehong paraan. Walang nagtatanong ng approval para sa mga ito habang tumatakbo ang skill. Sinusuri ng Claude Code ang bawat command laban sa permission rules mo. Kapag wala sa auto mode, mag-a-abort ang skill kapag hindi pinapayagan ng mga rule na iyon ang command, maliban kung paunang inaprubahan ito ng skill sa pamamagitan ng ikalawang feature sa ibaba. Nanaig pa rin sa paunang approval na iyon ang deny at ask rules. Ang pagbabasa ng shared skill ay nangangahulugan ding pagbabasa ng command substitutions nito.

Ikalawa, maaaring magpaunang mag-approve ng tools ang frontmatter. Ibinibigay ng allowed-tools ang mga nakalistang tool nang walang permission prompt para sa turn na tumawag sa skill. Hindi hinaharangan ng workspace trust ang grant na ito: ipinapatupad ng Claude Code ang allowed-tools ng isang project skill kahit sa -p run sa folder na hindi pinagkakatiwalaan ng sinuman. Malinaw ang sinasabi ng dokumentasyon ng Claude Code tungkol sa epekto nito: maaaring bigyan ng skill ang sarili nito ng malawak na tool access, kaya suriin ang allowed-tools ng mga skill na naka-check in sa isang repository bago mo patakbuhin ang Claude Code doon. Maaaring ipagbawal ng isang organization ang field na ito para sa project at personal skills sa pamamagitan ng pag-set ng allowManagedPermissionRulesOnly sa managed settings; kailangan nito ang Claude Code v2.1.282 o mas bago.

Kaya ituring ang pag-update ng skill na katulad ng pag-update ng dependency. Gumamit ng eksaktong commit bilang pin kung pinapayagan ito ng mechanism, dahil maaaring ilipat ang tag at likas na nagbabago ang branch. Sa isang locked-down machine, pinapalitan ng "disableSkillShellExecution": true sa settings ang bawat command substitution ng literal na text na [shell command execution disabled by policy] sa halip na patakbuhin ito; kapag inilapat ito sa managed settings, hindi ito maaaring i-override ng user. Exempt sa setting na ito ang bundled at managed skills.

Nalalapat din ang parehong pag-iingat sa binabasa ng skill. Ang skill na nagpapatakbo ng env o nagbubukas ng config file ay kumukuha ng anumang makita nito papunta sa context ng model. Ito ang failure na tinatalakay sa pag-iwas na mapunta ang mga secret sa mga agent na pinapatakbo mo. Ang skill na kumukuha ng page o nagpapatakbo ng query ay kaparehong exposure na nakaturo naman palabas, dahil napupunta sa context ang retrieved text at nagmumukhang eksaktong katulad ng mga instruction na isinulat mo. Mahalagang basahin ang tungkol sa boundary na ito bago mo ituro ang isang agent sa sarili mong SearXNG instance para sa web search.

Ano ang dapat basahin sa version bump

  • Ang diff ng bawat SKILL.md body, dahil ang text na iyon ang susundin ng iyong agent.
  • Bawat command substitution, dahil tumatakbo ang mga ito sa iyong machine kapag nag-load ang skill.
  • Anumang pagbabago sa allowed-tools, dahil ang linyang iyon ang nagbibigay ng access sa mga tool nang walang prompt.
  • Ang test run sa likod ng tag. Kung ang shared repository ay nagpapatakbo ng sarili nitong smoke tests sa CI, dapat ay may green run na naka-attach sa tag na iyong pinipili.

Ang reviewer na hindi kayang basahin ang buong diff sa loob ng sampung minuto ay tumitingin sa isang skill na masyado nang malaki. Hatiin ito. Ang parehong argumento ay nalalapat sa mga repository document na binabasa ng iyong mga agent: panatilihin ang mga permanenteng panuntunan sa mga file na inilarawan sa paghihiwalay ng AGENTS.md at HUMAN.md at ang architectural reasoning sa isang DESIGN.md na isinulat para sa mga agent, at hayaang manatiling mga tiyak na procedure ang mga skill.

Kapag ang pagbabago sa model o tool ay sumira sa isang skill

May mga bagay na nagbabago sa ilalim ng isang skill kahit walang nag-e-edit nito. Ang upgrade sa model ay nagpapabago sa pagiging reliable ng pagsunod sa mahabang instruction, kaya ang isang skill na nakadepende sa pag-abot ng model sa step nine ay maaaring huminto na sa pag-abot nito. Ang isang command line tool ay nagpapalit ng pangalan ng flag, kaya ang agent ay tatakbo gamit ang lumang flag, babasahin ang error, at mag-i-improvise. Ang isang referenced URL ay nagsisimulang mag-return ng 404. Ang isang agent harness ay nagbabago sa paraan ng pagpili nito ng mga skill, kaya ang isang description na dati ay nananalo sa match ay hindi na ngayon. Kapag ang isang procedure ay nagsimulang matapos nang maaga nang ganyan, walang version bump ang makakaayos nito at ang mga instruction mismo ay nangangailangan ng structure na pumipilit sa mga huling step, na siyang approach sa likod ng the unlazy skill and its Depth Tree method.

Ito ang dahilan kung bakit ang smoke test ang may pinakamabigat na papel sa setup na ito. Patakbuhin ang test ng bawat skill ayon sa schedule at tuwing may push. Ang Google ay nagpapatakbo ng kanilang evaluation jobs linggu-linggo laban sa buong library dahil dito, at ang isang lingguhang cron job sa isang maliit na VPS ay sapat na para sa isang team na may sampung skill. Ito lang ang tanging paraan para malaman mo ang sira bago pa ito mapansin ng developer.

Nakakatulong din ang portability. Ang Agent Skills spec ay naglilimita sa frontmatter sa anim na key, kaya ang isang skill na isinulat ayon sa spec na iyon ay gagana sa mga tool na labas sa ginamit mo noong isinulat mo ito, habang ang bawat harness-specific key na idadagdag mo ay isang taya sa isang vendor. Ang pagsusulat ng mga skill na nakaka-survive sa model swap ay isang disiplina sa sarili nito, na tinatalakay sa making a skill work on any model.

FAQ

Paano ko maibabahagi ang isang agent skill sa ilang repository?

Ilagay ang skill sa isang dedikadong git repository, lagyan ito ng mga release tag, at ipa-reference sa bawat consuming project ang isang tag sa halip na kopyahin ang file. Dalawang mekanismo ang maaaring gamitin. Nagtatala ang git submodule ng eksaktong commit, at ginagawa ng symlink mula .claude/skills/<name> papunta sa submodule na ma-load ito bilang normal na project skill. Pareho rin ang ginagawa ng plugin marketplace sa pamamagitan ng /plugin, kung saan idinedeklara ang pin sa .claude/settings.json ng consuming repository. Nailalagay ng dalawang paraang ito ang bersyon sa git history, kaya matutukoy mo kung aling instructions ang gumawa ng isang partikular na agent run.

Maaari ko bang i-pin ang isang agent skill sa partikular na bersyon?

Hindi mula sa loob ng SKILL.md, dahil walang version key ang frontmatter na iyon. Kailangang manggaling ang pin sa layer na nakapaligid sa file. Awtomatikong nagpi-pin ang git submodule sa eksaktong commit. Sa Claude Code plugin marketplace, tumatanggap ang plugin source ng ref para sa branch o tag at sha para sa eksaktong commit, at mananaig ang sha kapag parehong nakalagay. Tumatanggap naman ang marketplace source ng ref para sa branch, tag, o, sa Claude Code v2.1.324 o mas bago, buong lowercase commit SHA. Mas mainam ang commit pin, dahil maaaring ilipat ang isang tag matapos mo itong ma-review.

Ano ang dapat i-assert ng isang skill smoke test?

Mag-assert sa isang stable na value. Patakbuhin ang skill nang non-interactive laban sa fixture na may kilalang fault, pagkatapos ay tingnan kung lumilitaw sa output ang isang partikular na identifier, gaya ng rule id na dapat i-report ng skill. Mas eksakto ang check kapag humiling ng structured output gamit ang --output-format json at --json-schema, at pinapabagsak ng jq -e ang script kapag nawawala ang value. Huwag kailanman mag-assert sa buong sentence, dahil maaaring baguhin ng model ang pagkakasulat ng sagot nito sa bawat run.

Ligtas bang mag-install ng shared skill mula sa repository ng ibang team?

Ituring ito bilang code dependency, dahil executable instruction ito. Maaaring magpatakbo ang isang SKILL.md ng shell commands sa oras ng pag-load sa pamamagitan ng ! command substitution form, at maaaring mag-pre-approve ng tools nang walang prompt ang allowed-tools field ng frontmatter. Basahin ang diff sa bawat bump, mag-pin sa eksaktong commit sa halip na branch, at mas piliin ang source na kontrolado ng sarili mong team. Sa managed machines, pinipigilan ng "disableSkillShellExecution": true sa settings na tumakbo ang command substitutions sa user, project, plugin, at additional-directory skills; hindi saklaw nito ang bundled at managed skills.

Gagana ba ang shared skill sa mga agent na hindi Claude Code?

Depende ito sa frontmatter na gagamitin mo. Tinutukoy ng Agent Skills spec ang anim na key: name, description, license, compatibility, metadata at allowed-tools. Maikakarga ang skill na limitado sa mga iyon sa mga tool na nagpapatupad ng spec, at gagana rin ito sa Claude Code nang walang pagbabago. Hindi pinapansin o tinatanggihan sa ibang tool ang harness-specific keys at mga body feature na lampas sa spec, kaya huwag isama ang mga ito sa skill na balak mong malawakang ibahagi.

Nakatulong ba ang artikulong ito?

#agent-skills#versioning#claude-code#team-standards#self-hosting