SSD Nodes Learn Hosting plans →

రెపోల మధ్య agent skills ను drift లేకుండా పంచుకోవడం

ఎనిమిది రెపోల్లో skill కాపీలు వేర్వేరు కావడం ఆపండి. ఒక shared repo, ప్రతి project కు pinned version, smoke tests, review విధానాన్ని ఏర్పాటు చేయండి.

రిపోజిటరీల మధ్య agent skills ను ఎలా పంచుకోవాలి

రిపోజిటరీల మధ్య agent skills ను పంచుకోవడానికి, ఫైల్‌ను కాపీ చేయడం ఆపి, దానిపై dependency గా ఆధారపడటం ప్రారంభించండి. ఒక skills repository ను నిర్వహించి, దానికి tag ఇవ్వండి. ప్రతి project ఆ tag ను pin చేయాలి. తరువాత ప్రతి skill కు smoke test జోడించండి. Dependency bump ను సమీక్షించిన విధంగానే ప్రతి version bump ను సమీక్షించండి.

దీనిలో నాలుగు భాగాలు ఉన్నాయి: shared source of truth, ప్రతి repository కు pinned version, ప్రతి skill కు smoke test, మరియు review path. ప్రతి భాగం ఎందుకు అవసరమో, 2026లో విడుదలైన tools దీనిని ఎలా నిర్వహిస్తాయో, బయట git host లేదా package registry అవసరం లేకుండా self-hosted git remote పై మొత్తం వ్యవస్థను ఎలా నిర్మించాలో కింది వివరణలో ఉంది. Smoke tests మాత్రమే దీనికి మినహాయింపు. అవి Claude Code ను నడుపుతాయి. Claude Code ప్రతి అభ్యర్థనను model API కు పంపుతుంది. అందువల్ల ఆ దశలో మీ server వెలుపలికి అభ్యర్థన వెళ్తుంది.

Agent skill అనేది SKILL.md ఫైల్‌ను కలిగి ఉన్న folder. దానికి అవసరమైన scripts మరియు reference files కూడా అందులో ఉండవచ్చు. ఈ unit మీకు కొత్తదైతే, ముందుగా agent skill అంటే ఏమిటి, SKILL.md ఎలా పనిచేస్తుంది చదవండి. ఈ పేజీ ఆ unit చుట్టూ ఉన్న supply chain గురించి వివరిస్తుంది.

నైపుణ్యం ఎక్కడ ఉంటుంది, మరియు పంచుకోవడం ఎందుకు కష్టం

Claude Code కింది స్థానాల నుండి నైపుణ్యాలను (skills) లోడ్ చేస్తుంది, మరిన్ని వివరాల కోసం skills documentation లోని ప్రతి path ను చూడవచ్చు.

  • .claude/skills/<skill-name>/SKILL.md అనేది మేనేజ్డ్ సెట్టింగ్స్ డైరెక్టరీలో ఉంటుంది, ఇది ఎంటర్‌ప్రైజ్ స్థానం. సంస్థ దీనిని డిప్లాయ్ చేసిన మెషీన్‌లలోని ప్రతి వినియోగదారు కోసం ఇది లోడ్ అవుతుంది.
  • ~/.claude/skills/<skill-name>/SKILL.md అనేది వ్యక్తిగతమైనది. ఇది మీ అన్ని ప్రాజెక్ట్‌లలో లోడ్ అవుతుంది, వేరే ఎవరి ప్రాజెక్ట్‌లలోనూ కాదు.
  • .claude/skills/<skill-name>/SKILL.md అనేది ప్రాజెక్ట్ స్థాయికి చెందినది. ఆ రిపోజిటరీని చెక్ అవుట్ చేసే ఎవరికైనా ఇది లోడ్ అవుతుంది.
  • <plugin>/skills/<skill-name>/SKILL.md అనేది ఒక ప్లగిన్ లోపల ఉంటుంది. ఆ ప్లగిన్ ఎక్కడ ఎనేబుల్ చేయబడితే అక్కడ ఇది లోడ్ అవుతుంది.

Claude Code నెస్టెడ్ ప్రాజెక్ట్ డైరెక్టరీల నుండి, --add-dir తో అందించబడిన డైరెక్టరీల నుండి, మరియు మీ claude.ai ఖాతా కోసం ఎనేబుల్ చేయబడిన నైపుణ్యాలను కూడా లోడ్ చేస్తుంది.

ప్రాజెక్ట్ స్థాయి నైపుణ్యం బృందానికి చాలా ఉపయోగకరంగా ఉంటుంది, ఎందుకంటే ఇది కమిట్ చేయబడుతుంది మరియు రిపోజిటరీని క్లోన్ చేసే ప్రతి ఒక్కరికీ ఇది లభిస్తుంది. ఇక్కడే సమస్య మొదలవుతుంది. .claude/skills/ లోని ఒక నైపుణ్యం ఒక రిపోజిటరీకి మాత్రమే చెందుతుంది. మీ దగ్గర ఎనిమిది రిపోజిటరీలు ఉంటే, ఆ నైపుణ్యం ఎనిమిది సార్లు కాపీ చేయబడుతుంది.

ఫ్రంట్‌మేటర్ (frontmatter) దీనికి ఎటువంటి సహాయం చేయదు. Agent Skills స్పెసిఫికేషన్ ఆరు కీలను అనుమతిస్తుంది, మరియు మీరు మరొక కీని ఉపయోగించినప్పుడు డిస్ట్రిబ్యూషన్ పాత్‌లు ఆ జాబితాను ప్రింట్ చేస్తాయి:

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

ఏమి లేదో గమనించండి: అక్కడ version కీ లేదు. ఒక వెర్షన్‌ను metadata కింద రికార్డ్ చేయవచ్చు, కానీ ఈ స్పెసిఫికేషన్ ఎటువంటి డిపెండెన్సీ పిన్ లేదా అప్‌డేట్ మెకానిజంను నిర్వచించదు. ఇది సహేతుకమే, ఎందుకంటే నైపుణ్యం అనేది ఒక ప్యాకేజీ కంటే ఒక డాక్యుమెంట్ లాంటిది. దీని అర్థం వెర్షనింగ్ అనేది ఫైల్ చుట్టూ ఉన్న లేయర్ నుండి రావాలి, మరియు ఆ లేయర్‌ను నిర్వహించడం మీ బాధ్యత.

సమస్య ఒకటి: నిశ్శబ్దంగా భిన్నంగా మారే ఎనిమిది కాపీలు

మొదటి రోజున copy-paste పనిచేస్తుంది. అరవయ్యవ రోజున అది విఫలమవుతుంది. ఎవరో payments repo లోని తప్పు సూచనను సరిచేస్తారు, కానీ మిగిలిన ఏడింటిని మార్చరు. మరొకరు orders లో pagination గురించి ఒక నియమాన్ని జోడిస్తారు. ఇప్పుడు agent ప్రారంభమైన directory ఆధారంగా, అదే skill పేరు రెండు భిన్నమైన reviews ను ఇస్తుంది. ఈ విషయం ఏ developer కు తెలియదు.

ఇక్కడ error state ఏదీ లేకపోవడం వల్ల ఈ వైఫల్యం నిశ్శబ్దంగా జరుగుతుంది. skill అనేది prose. పాత సూచన నమ్మకంగా కనిపించే తప్పు సమాధానాన్ని ఉత్పత్తి చేస్తుంది. ఇదే అత్యంత ఖరీదైన రకం. మీ కాపీని ఇతరుల కాపీలతో agent పోల్చదు. అందువల్ల రెండు repos మధ్య తేడాను ఒక వ్యక్తి గమనించడమే ఏకైక సంకేతం.

సమస్య రెండు: ఏదీ ఒక version ను నిర్దిష్టంగా pin చేయదు

ఒక బృందం skills ను ఒకే చోట నిర్వహించినప్పటికీ, సాధారణ sharing పద్ధతి copy దశపైనే ఆధారపడుతుంది: setup script, onboarding doc లోని ఒక curl line, లేదా folder ను sync చేసే shell alias. ఇవన్నీ ఆ సమయంలో branch head వద్ద ఉన్నదానినే install చేస్తాయి.

దీని వల్ల ఒకే application లోని ఒకే commit పై ఇద్దరు developers పనిచేస్తున్నప్పటికీ, వారు వేర్వేరు instructions ను అమలు చేయవచ్చు. కారణం, వారు sync ను వేర్వేరు రోజుల్లో నిర్వహించారు. అలాగే, agent అమలు విఫలమైన తర్వాత ముఖ్యమైన ప్రశ్నకు మీరు సమాధానం ఇవ్వలేరు: దీన్ని ఏ version లోని skill ఉత్పత్తి చేసింది? Recorded revision లేకపోతే ఆ run ను మళ్లీ పునరుత్పత్తి చేయలేం. అందువల్ల bug report పై చర్య తీసుకోవడం సాధ్యం కాదు.

సమస్య మూడు: నైపుణ్యం ఇప్పటికీ పనిచేస్తుందో ఎవరికీ తెలియదు

ఒక skill కు compiler ఉండదు. అది model కు ఇచ్చే సూచనల సమాహారం మాత్రమే. అందువల్ల ఫైలు byte for byte ఒకేలా ఉన్నప్పటికీ అది పనిచేయడం ఆపివేయవచ్చు. Model upgrade వల్ల దీర్ఘమైన instruction ను ఎంతవరకు అనుసరిస్తుందో మారవచ్చు. Skill ఉపయోగించే command line tool ఒక flag పేరు మార్చవచ్చు. Reference file లోని URL 404 status ను ఇవ్వడం ప్రారంభిస్తే, agent ఆ error page ఆధారంగా పనిచేయవచ్చు.

ఈ పరిస్థితుల్లో ఏదీ స్పష్టమైన వైఫల్యాన్ని చూపదు. Agent ఇప్పటికీ సమాధానం ఇస్తుంది. అయితే ఆ సమాధానం గత నెలతో పోలిస్తే కేవలం నాణ్యతలో తగ్గిపోయి ఉంటుంది. ప్రతి pull request ను విడిగా పరిశీలించినప్పుడు ఈ మార్పును గుర్తించడం కష్టం.

2026లో విడుదలవుతున్న టూల్స్ పరిష్కరించే సమస్యలు

ప్రస్తుతం అనేక సమాధానాలు అందుబాటులోకి వస్తున్నాయి, అయితే వెర్షన్ ఎక్కడ ఉండాలనే విషయంలో వాటి మధ్య ఏకాభిప్రాయం లేదు.

Lockfiles. Vercel Labs నుండి వచ్చిన skills కమాండ్ లైన్ టూల్ (vercel-labs/skills, MIT లైసెన్స్, 9 అక్టోబర్ 2026 నాటికి v1.7.2), మీ ఏజెంట్ ఆశించే డైరెక్టరీలోకి git రిపోజిటరీ నుండి స్కిల్స్‌ను ఇన్‌స్టాల్ చేస్తుంది. ఇది డెబ్బైకి పైగా ఏజెంట్ల లేఅవుట్‌ను గుర్తిస్తుంది. npx skills add <repo> ఇన్‌స్టాల్ చేస్తుంది, npx skills update అప్‌గ్రేడ్ చేస్తుంది, మరియు npx skills list మీ వద్ద ఉన్నవాటిని చూపిస్తుంది. ఇది రెండు లాక్ ఫైళ్లను నిర్వహిస్తుంది. ~/.agents/.skill-lock.json వద్ద ఉండే గ్లోబల్ ఫైల్, ఒక వినియోగదారు ఏమి ఇన్‌స్టాల్ చేశారో రికార్డ్ చేస్తుంది. v1.4.1 (20 ఫిబ్రవరి 2026) నుండి, ప్రాజెక్ట్ స్కోప్‌లో ఇన్‌స్టాల్ చేయడం వల్ల ప్రాజెక్ట్ రూట్ వద్ద skills-lock.json కూడా తయారవుతుంది. ఈ ఫైల్‌ను వెర్షన్ కంట్రోల్‌లోకి పంపాలని టూల్ సోర్స్ కోడ్ సూచిస్తుంది. npx skills experimental_install దీని ద్వారా ప్రాజెక్ట్ స్కిల్స్‌ను పునరుద్ధరిస్తుంది. మరొక మెషీన్‌లో గ్లోబల్ లాక్ ఫైల్‌ను పునరుద్ధరించడానికి skills install కమాండ్ కావాలని కోరిన Issue 283, 5 నవంబర్ 2026న 'not planned'గా మూసివేయబడింది; మెయింటైనర్ దీనిని Issue 549 లోని అభ్యర్థనగానే పరిగణించారు. రెండింటినీ స్టేటస్ రిపోర్టుగా చదవండి. ప్రాజెక్ట్-వారీ లాక్ ఫైల్ అందుబాటులో ఉంది. విడుదలైన v1.8.1లో, రీస్టోర్ కమాండ్ హెల్ప్‌లో ఇంకా experimental అని ఉంది, కానీ సోర్స్ లేకుండా npx skills install వాడితే అది ప్రాజెక్ట్ లాక్ ఫైల్‌ను కూడా పునరుద్ధరిస్తుంది.

Specs and tests. SkillSpec మరో కోణాన్ని తీసుకుంటుంది. ఇది SKILL.mdని నమ్మదగిన సమాచారం కంటే, తనిఖీ చేయాల్సిన కాంట్రాక్టుగా పరిగణిస్తుంది. స్కిల్స్ "అనుసరించదగినవిగా, పరీక్షించదగినవిగా మరియు నిరూపించదగినవిగా" ఉండాలనేది దీని లక్ష్యం. skillspec doctor <path> ఏజెంట్ ఎక్కడ తడబడే అవకాశం ఉందో రిపోర్ట్ చేస్తుంది. skillspec boundary map <path> స్కిల్‌లో ఏముందో చూపిస్తుంది, మరియు skillspec boundary assess <path> అది దేనిని చేరుకోగలదో రిస్క్ ఆధారంగా క్రమబద్ధీకరించి చూపిస్తుంది. ఇది Rust క్రేట్, MIT లేదా Apache 2.0 లైసెన్స్‌లతో లభిస్తుంది. వెర్షన్ 0.2.2, 29 జూలై 2026న ప్రచురించబడింది మరియు 10 అక్టోబర్ 2026 నాటికి crates.ioలో ఇదే కొత్తది. సరికొత్త వెర్షన్‌కు బదులుగా పిన్ చేసిన వెర్షన్‌ను ఇన్‌స్టాల్ చేయండి:

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

12 నవంబర్ 2026న విడుదలైన Cargo 1.100 నుండి, cargo install డిఫాల్ట్‌గా ప్యాకేజ్డ్ లాక్ ఫైల్‌ను ఉపయోగిస్తుంది, మరియు --locked ఏ పని చేయదు. skillspec --version కమాండ్ 0.2.2ని ప్రింట్ చేయాలి. వేరే నంబర్ కనిపిస్తే, మీ PATHలో ఉన్న పాత బైనరీ అమలు అవుతోందని అర్థం.

Vendor practice. google/skillsలో స్కిల్స్‌ను ఎలా నిర్మిస్తారో, ఏజెంట్ స్కిల్స్‌ను ఎలా నిర్మించాలి, పరీక్షించాలి మరియు స్కేల్ చేయాలి అనే పోస్ట్‌లో గూగుల్ వివరించింది. స్కేలింగ్ అంశాలను పక్కన పెడితే, దీని వెనుక ఉన్న విధానం సాధారణ కంటిన్యూయస్ ఇంటిగ్రేషన్ (CI). ప్రతి స్కిల్ మెర్జ్ అయ్యే ముందు ఫ్రంట్‌మేటర్ మెటాడేటా, లైన్ కౌంట్, డైరెక్టరీ లేఅవుట్ మరియు నామింగ్ కోసం లింటర్ల ద్వారా పరీక్షించబడుతుంది. లింక్ చెకర్ 404 ఎర్రర్ ఇచ్చే ఏ URL కైనా బిల్డ్‌ను ఆపివేస్తుంది, దీనివల్ల ఏజెంట్ సృష్టించిన తప్పుడు లింకులు బయటపడతాయి. రచయితలు స్కిల్‌తో పాటు ఎవాల్యుయేషన్ ప్రాంప్ట్ సూట్ మరియు స్కోరింగ్ రూబ్రిక్‌ను అందించాలి. షెడ్యూల్ చేసిన ఎవాల్యుయేషన్ జాబ్స్ ప్రతి వారం మొత్తం లైబ్రరీపై రన్ అవుతాయి, తద్వారా రిగ్రెషన్లను గుర్తించవచ్చు. ప్రతి స్కిల్‌కు ఒక బాధ్యతాయుతమైన వ్యక్తి (owner) ఉంటారు, నాణ్యత తగ్గినప్పుడు వారు దానిని సరిచేయాల్సి ఉంటుంది.

మూడు సమాధానాల వెనుక ఉన్న నమూనా

మీరు వాటిలో ఏదో ఒకదాన్ని ఎంచుకోవాల్సిన అవసరం లేదు. వాటి వెనుక ఒకే నిర్మాణం ఉంది. plain git మీకు దాని మొత్తాన్ని అందిస్తుంది.

  1. ఒకే నిజమైన మూలం. ప్రతి skill కు ఖచ్చితంగా ఒకే స్థానం ఉంటుంది. ప్రతి repository కాపీని ఉంచకుండా ఆ స్థానాన్నే సూచిస్తుంది.
  2. ప్రతి repository కు స్థిరపరచిన version. ప్రతి project తాను ఉపయోగించే ఖచ్చితమైన revision ను నమోదు చేస్తుంది. అందువల్ల upgrade అనేది author మరియు date ఉన్న ఆ project లోని ఒక commit అవుతుంది.
  3. ప్రతి skill కు smoke test. skill వాగ్దానం చేసిన ఫలితాన్ని ఇప్పటికీ ఇస్తోందని నిర్ధారించే ఒక runnable check ఉంటుంది.
  4. ఒక review మార్గం. shared skill లో మార్పు review ద్వారా వెళ్తుంది. దాన్ని స్వీకరించే ముందు ప్రతి consumer diff ను చూస్తుంది.

అదే dependency యొక్క నిర్మాణం. tooling దాని చుట్టూ అభివృద్ధి చెందకముందే skills shared artifact గా మారాయి. అందువల్ల మీరు ఇప్పటికే విశ్వసించే tooling ను ఉపయోగించడం అత్యంత సురక్షితమైన ఎంపిక.

స్వయంగా నిర్వహించే git remote పై చిన్న బృందం కోసం ఒక నిర్మాణం

ఒక repository లో skills మాత్రమే ఉంటాయి. అందులో మరే ఇతర కంటెంట్ ఉండదు. అందువల్ల దాని history సూచనల changelog లా ఉంటుంది.

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

Releases tags గా ఉంటాయి. annotated tags ఉపయోగించండి. వాటిలో message మరియు date ఉంటాయి. ఆ message ను consumer ఈ bump ను ఎందుకు కోరుకుంటుందో తెలిపే కారణంగా రాయండి:

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

మీ remote Gitea, Forgejo, GitLab లేదా మీ స్వంత VPS పై SSH ద్వారా అందుబాటులో ఉన్న bare repository అయినా, తరువాతి దశల్లో ఎలాంటి మార్పు ఉండదు. ఇక్కడ ఉపయోగించేది git మరియు ఒక symlink మాత్రమే.

git submoduleతో commit ను స్థిరపరచడం

ఒక submodule మీ repository లోపల మరొక repository యొక్క ఒక నిర్దిష్ట commit ను నమోదు చేస్తుంది. ఆ నమోదు చేసిన commit నే pin అంటారు. ప్రతి వినియోగించే 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"

ఈ విధానం పనిచేయడానికి symlink కీలకం. Project స్థాయిలోని skill entry, disk పై మరెక్కడైనా ఉన్న directory కు symlink అయి ఉండవచ్చు. Claude Code ఆ symlink ను అనుసరించి target నుంచి SKILL.md ను చదువుతుంది. అందువల్ల skill సాధారణ project skill లా load అవుతుంది, కానీ దాని ఫైళ్లు మీరు ఎంచుకున్న commit వద్ద ఉన్న submodule లో ఉంటాయి.

Pin ను తనిఖీ చేయండి:

git submodule status

సరైన line లో మొదట ఒక ఖాళీ ఉంటుంది. తరువాత commit, path, చివరగా సమీప tag ఉంటాయి:

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

ప్రారంభంలో - ఉంటే submodule ఇంకా initialise కాలేదని అర్థం. అందువల్ల .claude/skills/api-review ఏదీ చూపదు, skill కూడా ఎటువంటి సందేశం లేకుండా load కాదు. దీన్ని git submodule update --init తో సరిచేయండి. ప్రారంభంలో + ఉంటే checkout చేసిన commit, నమోదు చేసిన commit తో సరిపోలడం లేదని అర్థం. అంటే ఆ developer, మరెవరూ ఉపయోగించని instructions ను నడుపుతున్నారు. కొత్త clone లకు git clone --recurse-submodules అవసరం. ఆ line README లో ఉండాలి, ఎందుకంటే సాధారణ clone తర్వాత vendor/agent-skills ఖాళీగా ఉంటుంది, ఎటువంటి error కూడా చూపదు.

Upgrade ను ఉద్దేశపూర్వకంగా చేయాలి. ఈ విధానానికి ఇదే ప్రధాన ఉద్దేశం:

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"

diff line review కు ఉపయోగపడుతుంది. ప్రతి ఇతర consuming repo లో కనిపించే అదే మార్పును ఇది చూపిస్తుంది. అలాగే దీన్ని pull request లో చేర్చడం సులభం.

ప్లగిన్ మార్కెట్‌ప్లేస్‌తో పిన్నింగ్ (Pinning) చేయడం

ప్రతి డెవలపర్‌కు సబ్‌మాడ్యూల్స్ (submodules) నేర్పించడం ఇష్టం లేకపోతే, Claude Code ప్లగిన్ సిస్టమ్ మీ కోసం పంపిణీని చేస్తుంది మరియు ఇది self-hosted రిమోట్ సర్వర్‌తో పనిచేస్తుంది. స్కిల్స్ రిపోజిటరీలోని .claude-plugin/marketplace.json వద్ద ఒక క్యాటలాగ్‌ను ఉంచండి:

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

ఇక్కడ రెండు వేర్వేరు మూలాలు (sources) ఉన్నాయి, వీటిని గందరగోళానికి గురిచేయడం సాధారణ పొరపాటు. మార్కెట్‌ప్లేస్ సోర్స్, అంటే క్యాటలాగ్ ఎక్కడి నుండి పొందబడుతుందో, అది బ్రాంచ్ లేదా ట్యాగ్ కోసం ref ని అంగీకరిస్తుంది. Claude Code v2.1.324 లేదా ఆ తర్వాత వెర్షన్లలో, ఇది పూర్తి lowercase కమిట్ SHA ని కూడా అంగీకరిస్తుంది; ఇది విడిగా sha ఫీల్డ్‌ను అంగీకరించదు. క్యాటలాగ్‌లోని ప్లగిన్ సోర్స్ రెండింటినీ అంగీకరిస్తుంది, మరియు రెండూ సెట్ చేసినప్పుడు sha అనేది ప్రభావవంతమైన పిన్‌గా పనిచేస్తుంది. మార్కెట్‌ప్లేస్ సోర్స్ యొక్క ref ద్వారా క్యాటలాగ్‌ను మరియు క్యాటలాగ్ ఎంట్రీ యొక్క sha ద్వారా ప్లగిన్‌ను పిన్ చేయండి. వీటి టైప్ పేర్లు కూడా వేరుగా ఉంటాయి. క్యాటలాగ్ లోపల, url అంటే క్లోన్ చేయడానికి ఒక git రిపోజిటరీ అని అర్థం. మార్కెట్‌ప్లేస్ సోర్స్‌లో, url అంటే marketplace.json ఫైల్‌కు నేరుగా లింక్ అని అర్థం, మరియు git రిపోజిటరీని git అని సూచిస్తారు.

ప్రతి కన్స్యూమింగ్ రిపోజిటరీ అప్పుడు మార్కెట్‌ప్లేస్‌ను దాని కమిట్ చేసిన .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
  }
}

టీమ్ సభ్యులు ప్రాజెక్ట్ ఫోల్డర్ కోసం వర్క్‌స్పేస్ ట్రస్ట్ డైలాగ్‌ను అంగీకరించిన తర్వాత, Claude Code వారికి మార్కెట్‌ప్లేస్‌ను రిజిస్టర్ చేస్తుంది, దీని కోసం వికీ పేజీ అవసరం లేదు. క్యాటలాగ్ ఎంట్రీ సాపేక్ష మార్గం (relative path) కంటే git URL ని సూచిస్తుంది, కాబట్టి ప్లగిన్ కేవలం రిపోజిటరీ సెట్టింగ్‌ల నుండి ఇన్‌స్టాల్ అవ్వదు. ప్రతి టీమ్ సభ్యుడు ఒకసారి claude plugin install team-skills@acme-agents --scope project ని రన్ చేయాలి, అప్పటి వరకు Claude Code ప్లగిన్ ప్రాజెక్ట్ సెట్టింగ్‌లలో ఎనేబుల్ చేయబడిందని, కానీ ఇన్‌స్టాల్ కాలేదని చూపిస్తుంది. అప్పుడు స్కిల్స్ /team-skills:api-review కి సమాధానమిస్తాయి, ఎందుకంటే ప్లగిన్ స్కిల్స్ ప్లగిన్ పేరుతో నేమ్‌స్పేస్ చేయబడతాయి మరియు అదే పేరుతో ఉన్న ప్రాజెక్ట్ స్కిల్‌తో ఘర్షణ చెందవు. మీరు కొత్త ట్యాగ్‌ను పుష్ చేసి, క్యాటలాగ్ మరియు కన్స్యూమింగ్ రిపోజిటరీలలో పిన్‌లను అప్‌డేట్ చేసిన తర్వాత, కన్స్యూమర్లు /plugin marketplace update acme-agents తో రిఫ్రెష్ చేయాలి, ఆపై ఇన్‌స్టాల్ సమ్మరీ అడిగితే /reload-plugins ని రన్ చేయాలి.

ఒక skill కోసం smoke test రాయడం

Smoke test అనేది తెలిసిన లోపం ఉన్న fixture పై script ద్వారా agent ను నడిపి, ఒక assertion చేయడం. Claude Code ను -p తో non-interactive గా నడపవచ్చు. వినియోగదారు ప్రారంభించే skill అక్కడ కూడా పనిచేస్తుంది: prompt string లో /skill-name ఉంచితే, 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

fixtures/orders-api.md అనేది ఉద్దేశపూర్వకంగా ఉంచిన ఒక లోపం కలిగిన చిన్న file. Skill ఆ లోపాన్ని పేరుతో గుర్తించాలి అనేదే assertion. Filter నుంచి null వచ్చినప్పుడు jq -e non-zero తో ముగుస్తుంది. అందువల్ల ముందుగా ఉంచిన లోపాన్ని skill గుర్తించడం ఆపితే script విఫలమవుతుంది. Run విఫలమైతే claude కూడా non-zero తో ముగుస్తుంది. ఈ రెండు వైఫల్యాల్లో ఏదైనా సంభవిస్తే set -euo pipefail test ను విఫలమైనదిగా గుర్తిస్తుంది.

Run ల మధ్య model తన సమాధానాలను వేరే విధంగా రాయవచ్చు. కాబట్టి పూర్తి వాక్యంపై ఎప్పుడూ assertion చేయకండి. Skill ఉత్పత్తి చేయాల్సిన identifier పై లేదా మీరు కోరిన schema లోని field పై assertion చేయండి. Run తక్కువ ఖర్చుతో ఉండేలా fixture ను చిన్నదిగా ఉంచండి.

CI లో --bare జోడించండి. ఇది లేకపోతే claude -p interactive session ఉపయోగించే అదే context ను లోడ్ చేస్తుంది. ఇందులో hooks, plugins మరియు అది నడుస్తున్న machine నుంచి CLAUDE.md కూడా ఉంటాయి. అందువల్ల సహచరుడి వ్యక్తిగత configuration ఫలితాన్ని మార్చవచ్చు. Bare mode లో, --add-dir తో స్పష్టంగా ఇచ్చిన directory కింద ఉన్న .claude/skills/ లోని skills మినహా auto-discovery నిలిపివేయబడుతుంది. మీరు ఇక్కడ test చేస్తున్న project skill కూడా ఇది skip చేస్తుంది. కాబట్టి ఆ skill ను explicit గా load చేయండి. Bare mode మీ subscription login ను కూడా చదవదు. అందువల్ల ముందుగా environment లో ANTHROPIC_API_KEY సెట్ చేయండి:

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

--plugin-dir తో load చేసిన plugin, దాని పేరును .claude-plugin/plugin.json నుంచి తీసుకుంటుంది. ఆ manifest లేకపోతే దాని directory పేరును plugin పేరుగా ఉపయోగిస్తుంది. Skills repository లో catalog పక్కన "name": "team-skills" తో కూడిన plugin.json ను commit చేయండి. లేకపోతే పై command బదులుగా /agent-skills:api-review ను call చేయాలి.

--output-format stream-json తో, system/init event ఏ plugins load అయ్యాయో తెలియజేస్తుంది. Load కాని plugins కోసం ఇది plugin_errors array ను కూడా అందిస్తుంది. Startup events ముందుగా రాకపోతే ఇది stream ను తెరుస్తుంది. plugin_errors ఖాళీగా లేకపోతే CI job ను విఫలంగా గుర్తించండి. లేకపోతే agent మీ సంస్థ నియమాలను నిశ్శబ్దంగా పట్టించుకోకుండా ఉండేలా చేసే, ప్రస్తుతం లేని revision ను సూచించే pin ను ఇది గుర్తించదు.

షేర్ చేసిన skill అనేది అమలు చేయగల సూచన

ఫైల్ మరొక బృందం నుంచి వచ్చినప్పుడు, రెండు లక్షణాలు ఈ విషయాన్ని అక్షరాలా నిజం చేస్తాయి. రెండూ ముఖ్యమైనవే.

మొదట, ఒక SKILL.md మోడల్ ఏదైనా చదవకముందే shell commands ను అమలు చేయగలదు. Bodyలోని ఇలాంటి పంక్తి preprocessing చేస్తుంది:

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

ఈ command skillను load చేస్తున్న machineపై అమలవుతుంది. దాని output మోడల్ స్వీకరించే textలో placeholder స్థానాన్ని భర్తీ చేస్తుంది. మూడు backticks తరువాత ! తో ప్రారంభమయ్యే fenced block కూడా ఇదే విధంగా అనేక commands ను అమలు చేస్తుంది. Runtimeలో వీటిలో దేనికీ prompt చూపించబడదు. Claude Code ప్రతి commandను మీ permission rulesతో తనిఖీ చేస్తుంది. Auto mode వెలుపల, ఆ rules అనుమతించని command skillను నిలిపివేస్తుంది. అయితే క్రింద వివరించిన రెండవ feature ద్వారా skill దానికి ముందస్తు అనుమతి ఇస్తే ఇది వర్తించదు. అయినప్పటికీ deny మరియు ask rules ఆ ముందస్తు అనుమతిపై కూడా ప్రాధాన్యం కలిగి ఉంటాయి. Shared skillను చదవడం అంటే దాని command substitutionsను కూడా చదవడమే.

రెండవది, frontmatter toolsకు ముందస్తు అనుమతి ఇవ్వగలదు. allowed-tools పేర్కొన్న toolsకు, skillను invoke చేసిన turnలో permission prompt లేకుండా అనుమతి ఇస్తుంది. Workspace trust ఈ grantను నియంత్రించదు. Trusted కాని folderలో -p runలో ఉన్నా, Claude Code project skillకు చెందిన allowed-tools ను వర్తింపజేస్తుంది. Claude Code documentation ఈ ప్రభావాన్ని స్పష్టంగా చెబుతుంది: ఒక skill తనకు విస్తృత tool accessను మంజూరు చేసుకోగలదు. అందువల్ల అక్కడ Claude Codeను run చేయకముందు repositoryలో check-in చేసిన skills యొక్క allowed-tools ను పరిశీలించండి. Managed settingsలో allowManagedPermissionRulesOnly ను సెట్ చేయడం ద్వారా organization project మరియు personal skills నుంచి ఈ fieldను తొలగించగలదు. దీనికి Claude Code v2.1.282 లేదా తరువాతి version అవసరం.

కాబట్టి skillలో bumpను dependency bumpలాగే నిర్వహించండి. Mechanism అనుమతించే చోట exact commitతో pin చేయండి. Tagను మార్చవచ్చు, branch నిర్వచనం ప్రకారమే మారుతూ ఉంటుంది. Lock-down చేసిన machineలో settingsలో "disableSkillShellExecution": true ఉంచితే ప్రతి command substitution అమలు చేయకుండా, దాని స్థానంలో literal text [shell command execution disabled by policy] ను ఉంచుతుంది. Managed settings ద్వారా ఇది వర్తింపజేస్తే user దాన్ని override చేయలేరు. Bundled మరియు managed skillsకు ఈ setting వర్తించదు.

Skill ఏ విషయాలను చదువుతుందో కూడా ఇదే జాగ్రత్తతో పరిశీలించాలి. env ను run చేసే లేదా config fileను తెరిచే skill, అందులో కనిపించే మొత్తం సమాచారాన్ని మోడల్ contextలోకి తీసుకువస్తుంది. మీరు run చేసే agentsలో secretsను ఉంచకుండా ఉండటంలో వివరించిన failure ఇదే. Pageను fetch చేసే లేదా queryను run చేసే skill కూడా ఇదే exposureను బయటికి మళ్లిస్తుంది. Retrieved text మీరు రాసిన instructionsలాగే contextలో కనిపిస్తుంది. అందువల్ల web search కోసం మీ స్వంత SearXNG instanceకు agentను point చేయడంకు ముందు ఈ boundary గురించి చదవడం మంచిది.

వెర్షన్ bump సమయంలో చదవాల్సినవి

  • ప్రతి SKILL.md body యొక్క diff, ఎందుకంటే మీ agent అనుసరించే సూచన అదే.
  • ప్రతి command substitution, ఎందుకంటే skill load అయినప్పుడు అవి మీ machine పై అమలవుతాయి.
  • allowed-tools లోని ఏ మార్పైనా, ఎందుకంటే ఆ line prompt లేకుండానే tools ను అనుమతిస్తుంది.
  • tag వెనుక జరిగిన test run. Shared repository CIలో స్వంత smoke tests అమలు చేస్తే, మీరు pin చేస్తున్న tag కు green run జతచేయబడి ఉండాలి.

పది నిమిషాల్లో మొత్తం diff చదవలేని reviewer, అతిగా పెరిగిన skill ను పరిశీలిస్తున్నాడు. దాన్ని విడగొట్టండి. మీ agents చదివే repository documents కు కూడా ఇదే వర్తిస్తుంది: శాశ్వత నియమాలను AGENTS.md మరియు HUMAN.md విభజనలో వివరించిన files లో ఉంచండి, architectural reasoning ను agents కోసం రాసిన DESIGN.md లో ఉంచండి, skills ను పరిమిత విధానాలుగానే ఉంచండి.

మోడల్ లేదా tool మార్పు వల్ల skill పనిచేయకపోతే

ఎవరూ skill ను సవరించకపోయినా, దాని అంతర్గత ఆధారాలలో అనేక మార్పులు జరగవచ్చు. Model upgrade వల్ల దీర్ఘ instruction ను ఎంత విశ్వసనీయంగా అనుసరిస్తుందో మారుతుంది. అందువల్ల model తొమ్మిదో దశకు చేరుకోవడంపై ఆధారపడిన skill, ఆ దశకు చేరుకోకుండా ఆగిపోవచ్చు. Command line tool ఒక flag పేరు మార్చవచ్చు. అప్పుడు agent పాత flag ను అమలు చేసి, error ను చదివి, తనంతట తానే పరిష్కారం ఊహించవచ్చు. Referenced URL 404 తిరిగి ఇవ్వడం ప్రారంభించవచ్చు. Agent harness skills ను ఎంచుకునే విధానం మారవచ్చు. దాంతో గతంలో match లో గెలిచిన description ఇప్పుడు గెలవకపోవచ్చు. Procedure ఇలా మధ్యలోనే ముగియడం ప్రారంభమైనప్పుడు version bump చేయడం వల్ల సమస్య పరిష్కారం కాదు. చివరి దశలు తప్పనిసరిగా అమలయ్యేలా instructions కు నిర్మాణం అవసరం. the unlazy skill and its Depth Tree method వెనుక ఉన్న విధానం ఇదే.

అందుకే ఈ అమరికలో smoke test కీలక పాత్ర పోషిస్తుంది. ప్రతి skill యొక్క test ను push సమయంలోనే కాకుండా, నిర్దిష్ట schedule ప్రకారం కూడా అమలు చేయండి. ఈ కారణంగానే Google తన evaluation jobs ను మొత్తం library పై వారానికి ఒకసారి అమలు చేస్తుంది. పది skills ఉన్న team కు చిన్న VPS పై వారానికి ఒకసారి నడిచే cron job సరిపోతుంది. Developer గుర్తించేలోపు సమస్య గురించి తెలుసుకునే ఏకైక మార్గం ఇదే.

Portability కూడా సహాయపడుతుంది. Agent Skills spec frontmatter ను ఆరు keys కు పరిమితం చేస్తుంది. అందువల్ల ఆ spec కు అనుగుణంగా రాసిన skill, దాన్ని రాసిన tool మాత్రమే కాకుండా ఇతర tools లో కూడా load అవుతుంది. మీరు చేర్చే ప్రతి harness-specific key ఒక vendor పై చేసే పందెం వంటిది. Model మారినప్పటికీ పనిచేసే skills రాయడం ప్రత్యేకమైన పద్ధతి. దీని గురించి making a skill work on any model లో వివరించబడింది.

FAQ

ఒక agent skill ను అనేక repositories మధ్య ఎలా పంచుకోవాలి?

ఆ skill ను ఒక ప్రత్యేక git repository లో ఉంచి, దానికి releases ను tag చేయండి. ఫైల్‌ను కాపీ చేసే బదులు, ప్రతి ప్రాజెక్ట్ ఒక నిర్దిష్ట tag ను reference చేసేలా చూడండి. దీని కోసం రెండు పద్ధతులు ఉన్నాయి. ఒక git submodule ఖచ్చితమైన commit ను నమోదు చేస్తుంది, మరియు .claude/skills/<name> నుండి ఒక symlink ను submodule కు ఇవ్వడం ద్వారా అది సాధారణ ప్రాజెక్ట్ skill లాగా లోడ్ అవుతుంది. ఒక plugin marketplace కూడా /plugin ద్వారా ఇదే పనిని చేస్తుంది, ఇక్కడ వినియోగించే repository యొక్క .claude/settings.json లో pin ను పేర్కొనాలి. ఈ రెండు పద్ధతులు version ను git history లో ఉంచుతాయి, కాబట్టి ఒక నిర్దిష్ట agent run ఏ సూచనల ద్వారా జరిగిందో మీరు తెలుసుకోవచ్చు.

నేను ఒక agent skill ను నిర్దిష్ట version కు pin చేయవచ్చా?

SKILL.md లోపల నుండి ఇది సాధ్యం కాదు, ఎందుకంటే ఆ frontmatter లో version కీ లేదు. ఆ ఫైల్ చుట్టూ ఉన్న layer నుండే pin చేయాలి. Git submodule డిజైన్ ప్రకారం ఒక ఖచ్చితమైన commit ను pin చేస్తుంది. Claude Code plugin marketplace లో, ఒక plugin source బ్రాంచ్ లేదా tag కోసం ref ను, మరియు ఖచ్చితమైన commit కోసం sha ను అంగీకరిస్తుంది. రెండూ ఉన్నప్పుడు sha ప్రాధాన్యత పొందుతుంది. Marketplace source స్వయంగా బ్రాంచ్, tag లేదా Claude Code v2.1.324 లేదా ఆ తర్వాత వెర్షన్లలో, పూర్తి lowercase commit SHA కోసం ref ను అంగీకరిస్తుంది. Commit pin నే ఎంచుకోండి, ఎందుకంటే మీరు review చేసిన తర్వాత tag ను మార్చే అవకాశం ఉంది.

ఒక skill smoke test దేనిని నిర్ధారించాలి?

స్థిరంగా ఉండే అంశాలపైనే పరీక్షించండి. ఒక తెలిసిన లోపం (known fault) ఉన్న fixture పై skill ను non-interactive గా రన్ చేయండి. ఆ తర్వాత అవుట్‌పుట్‌లో ఒక నిర్దిష్ట identifier కనిపిస్తుందో లేదో చూడండి, ఉదాహరణకు skill రిపోర్ట్ చేయాల్సిన rule id. --output-format json మరియు --json-schema తో structured output ను అడగడం ద్వారా ఈ తనిఖీ ఖచ్చితంగా ఉంటుంది, మరియు విలువ లేనప్పుడు jq -e ఆ script ను విఫలం చేస్తుంది. పూర్తి వాక్యంపై ఎప్పుడూ assert చేయవద్దు, ఎందుకంటే ప్రతి run మధ్యలో మోడల్ తన సమాధానాలను మార్చవచ్చు.

ఇతర టీమ్ repository నుండి పంచుకున్న skill ను ఇన్‌స్టాల్ చేయడం సురక్షితమేనా?

దీనిని ఒక code dependency లాగా పరిగణించండి, ఎందుకంటే ఇది అమలు చేయదగిన సూచన (executable instruction). ఒక SKILL.md, ! command substitution రూపం ద్వారా load అయ్యే సమయంలో shell commands ను రన్ చేయగలదు. అలాగే frontmatter లోని allowed-tools ఫీల్డ్ ప్రాంప్ట్ లేకుండానే tools ను ముందే ఆమోదించగలదు. ప్రతి bump వద్ద diff ను చదవండి, బ్రాంచ్ కంటే ఖచ్చితమైన commit కే pin చేయండి, మరియు మీ టీమ్ నియంత్రణలో ఉన్న source నే ఎంచుకోండి. Managed machines లో, settings లోని "disableSkillShellExecution": true, user, project, plugin మరియు additional-directory skills లో command substitutions రన్ అవ్వకుండా ఆపుతుంది; bundled మరియు managed skills కు ఇది వర్తించదు.

పంచుకున్న skill, Claude Code కాకుండా ఇతర agents లో పనిచేస్తుందా?

అది మీరు ఏ frontmatter ఉపయోగిస్తున్నారనే దానిపై ఆధారపడి ఉంటుంది. Agent Skills spec ఆరు కీలను నిర్వచిస్తుంది: name, description, license, compatibility, metadata మరియు allowed-tools. వీటికి పరిమితమైన skill, ఈ spec ను అమలు చేసే ఇతర tools లో లోడ్ అవుతుంది, మరియు Claude Code లో కూడా ఎటువంటి మార్పులు లేకుండా లోడ్ అవుతుంది. Spec లో లేని Harness-specific కీలు మరియు body ఫీచర్లు ఇతర చోట్ల విస్మరించబడతాయి లేదా తిరస్కరించబడతాయి, కాబట్టి మీరు విస్తృతంగా పంచుకోవాలనుకునే ఏ skill లోనూ వాటిని చేర్చవద్దు.

ఈ వ్యాసం ఉపయోగకరంగా ఉందా?

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