Paano Sumulat ng Sarili Mong Agent Skill

Sumulat ng sarili mong agent skill mula sa isang aktuwal na pagkakamali

Ang pinakamainam na paraan para sumulat ng sarili mong agent skill ay ang kunin ito mula sa isang aktuwal na pagkakamali. Maghanap ng task na dalawang beses nagawa nang mali ng coding agent mo, isulat ang correction na tina-type mo sa parehong pagkakataon, at i-save ang correction na iyon bilang SKILL.md file na kayang i-load ng agent nang mag-isa. Pagkatapos nito, mechanics na lang ang lahat: ang layout ng file at ang isang linyang nagpapasya kung kailan gagana ang skill.

Mahalaga ang pagkakasunod-sunod na ito. Ang skill na isinulat mula sa imahinasyon ay nagdodokumento ng problemang hindi mo pa naranasan, at kumokonsumo pa rin ito ng context sa bawat session. Ang skill na hinango mula sa isang pagkakamaling nasaksihan mo ay may kasamang test: itanong muli ang parehong bagay at tingnan kung tama na itong magagawa ng agent. Kung bago sa iyo ang format, basahin muna ang kung ano ang agent skills at kung paano ito nilo-load ng isang agent, saka bumalik at sumulat ng isa.

Magsimula sa isang task na dalawang beses nagkamali ang agent

Maaaring nagkataon ang isang beses. Ang dalawang beses ay pattern, at sulit itala sa isang file ang pattern.

Narito ang isang failure na paulit-ulit na nangyayari sa mga aktuwal na server. Hihilingin mo sa agent na magdagdag ng reverse proxy block sa nginx. Ie-edit nito ang /etc/nginx/conf.d/app.conf, pagkatapos ay tatakbuhin ang sudo systemctl restart nginx. May typo ang edit, kaya tumangging mag-start ang nginx at hindi gumagana ang site hanggang sa ayusin mo ito:

nginx: [emerg] unknown directive "proxy_pas" in /etc/nginx/conf.d/app.conf:12
Job for nginx.service failed because the control process exited with error code.

Itatama mo ito sa chat. I-test ang configuration gamit ang sudo nginx -t bago galawin ang service, pagkatapos ay i-apply ito gamit ang reload sa halip na restart. Pagkalipas ng isang linggo, mauulit ang parehong pagkakamali sa ibang task. Ang ikalawang pagkakamaling iyon ang signal.

Isulat ang dalawang bagay habang nasa harap mo pa ang failure: ang request na iyong tina-type at ang correction na ibinigay mo, gamit ang mismong mga salitang ginamit mo. Ang dalawang linyang iyon ang magiging skill. Sinasabi ng request kung ano ang dapat itugma ng trigger. Ang correction ang buong content.

Inilalagay ito sa unang bahagi ng sariling authoring guidance ng Anthropic. Patakbuhin ang agent sa mga representative na task nang walang skill, itala kung saan ito nagkakamali, pagkatapos ay isulat ang pinakamaliit na instruction na nag-aayos sa mga failure na iyon. Ang mga failure ang specification, kaya ang skill na hindi mo maiuugnay sa isang failure ay karaniwang skill na walang nangangailangan.

Para sa isang kumpletong halimbawa ng parehong distillation, mababasa mo nang buo ang Paano ginawang skill ng Ponytail ang isang paulit-ulit na failure, kung saan mas marami ang nire-rewrite ng agent kaysa sa iyong hiniling, bago gumawa ng sarili mong skill.

Anatomy ng isang skill

Ang isang skill ay isang directory na may isang kinakailangang file.

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

Nagsisimula ang SKILL.md sa isang frontmatter block, na binubuo ng ilang setting na nakasulat sa YAML (ang parehong configuration format na ginagamit ng Docker Compose files) sa pagitan ng mga marker na ---, at sinusundan ng mga instruction na nasa markdown. Narito ang buong skill para sa naunang failure.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
---

## Rules

Run `sudo nginx -t` after every edit under `/etc/nginx`. Do not touch the service until it prints `test is successful`.

Apply the change with `sudo systemctl reload nginx`. Never use `restart`. A reload keeps the running workers serving traffic until the new config parses, so a broken config leaves the site up. A restart stops nginx first, so a broken config takes the site down.

If `nginx -t` fails, fix the file and test again. Never reload a config that failed the test.

For the proxy header defaults this project expects, see [reference/proxy-headers.md](reference/proxy-headers.md).

Wala pang 20 lines ang file na iyon, at kumpletong skill na ito. Ang mga bahagi nito:

• name: hanggang 64 characters, maliliit na letra, digits, at hyphens lamang, at hindi nito maaaring taglayin ang mga salitang claude o anthropic. Sa personal o project skill, ito lamang ang display label. Mula sa directory name ang command na tina-type mo, kaya ang skill na ito ay tumutugon sa /nginx-config-changes.
• description: kung ano ang ginagawa ng skill at kung kailan ito gagamitin, hanggang 1,024 characters. Ang linyang ito ang gumaganap ng aktuwal na trabaho, at tungkol lamang dito ang susunod na section.
• Ang body: ang mga instruction na nilo-load lamang kapag aktuwal na nag-trigger ang skill.
• reference/: mga karagdagang file na binabasa ng agent kapag kinakailangan. I-link ang mga ito mula sa SKILL.md at panatilihing isang level lang ang lalim ng mga link, dahil ang file na nire-reference mula sa isa pang nire-reference na file ay kadalasang bahagya lamang nababasa.
• scripts/: mga file na ine-execute ng agent sa halip na basahin. Output lamang ng mga ito ang kumokonsumo ng context, kaya mura lang sa context ang 300-line script.

Lumalaki ang isang skill at nagiging ganap na layout kapag sapat na katigasan ang behavior na itinatama nito para mangailangan ng ganoong istruktura. Sa unlazy skill, ginagamit ang espasyong iyon para sa Depth Tree, isang set ng gates files, at PLAN.md contract upang pigilan ang agent na mag-anunsyong tapos na ito habang may buong mga branch pa ng trabaho na hindi nagagawa.

Tinutukoy ng lokasyon ng directory kung sino ang makakagamit ng skill.

• .claude/skills/<name>/SKILL.md sa repository: para lamang sa project na ito, at napupunta ito sa lahat ng nagki-clone ng repo.
• ~/.claude/skills/<name>/SKILL.md: para sa bawat project sa machine mo, at wala sa machine ng iba.
• <plugin>/skills/<name>/SKILL.md: kasama sa isang plugin, at available saanman naka-enable ang plugin na iyon.

Gumawa ng isa gamit ang mkdir -p .claude/skills/nginx-config-changes at isulat ang file. Binabantayan ni Claude Code ang mga directory na ito, kaya nagkakabisa sa kasalukuyang session ang pag-edit ng isang existing skill. Kung gagawa ka ng top-level skills directory na wala pa noong nagsimula ang session, kailangan ng restart, dahil walang babantayan noong nagsimula ang session.

Ang description field ang may pinakamalaking epekto sa file

Sa pagsisimula, nilo-load ng agent ang name at description ng bawat available na skill sa context nito. Hindi nito nilo-load ang mga body. Kapag dumating ang request mo, ang linyang iyon lamang ang batayan sa pagpapasya kung naaangkop ang skill na ito. Kaya hindi mababasa ang perpektong body kung malabo ang description.

Isulat ang description sa third person. Tama ang “Tests and reloads nginx safely.” Hindi tama ang “I can help you with nginx,” dahil ini-inject ang text sa system prompt. Dahil dito, magmumukhang nagsasalita ang model tungkol sa sarili nito kapag first person ang ginamit.

Maglagay ito ng dalawang bagay: ang ginagawa ng skill at ang kundisyong dapat matugunan bago ito gamitin. Ilagay muna ang pinakamahalagang use case, dahil tina-truncate ng Claude Code ang listing entry sa 1,536 character. May optional na when_to_use field para sa dagdag na trigger phrase at mga halimbawa ng request. Idinadagdag ang field na ito sa description, pero sakop pa rin ito ng parehong limitasyon.

Pagkatapos, gamitin ang mga salitang aktuwal mong ita-type. Walang tine-trigger ang description: Helps with nginx dahil walang nagta-type ng “helps with.” Binabanggit ng bersyon sa itaas ang /etc/nginx, server block, reverse proxy at TLS (transport layer security) certificate path. Ito ang halos buong bokabularyo ng mga request na dapat mag-trigger dito.

Narito ang test para sa isang description. Ibigay ang nag-iisang linyang iyon sa isang taong hindi pa nakakita ng body, kasama ang request na ita-type mo. Tanungin siya kung naaangkop ang skill. Kung hindi niya matukoy, hindi rin ito matutukoy ng model.

Panatilihing maikli ang body dahil nananatili ito sa context

Kapag tinawag ang isang skill, pumapasok ang na-render nitong content sa conversation bilang isang message at nananatili roon sa buong session. Hindi muling binabasa ng Claude Code ang file sa mga susunod na turn. Bawat line na isinusulat mo ay cost para sa buong session, hindi para sa isang sagot.

Inirerekomenda ng Anthropic na panatilihin ang SKILL.md sa ilalim ng 500 lines at ilipat ang mga detalye sa magkakahiwalay na file. Ipinapakita ng compaction kung bakit hindi arbitrary ang numerong iyon. Kapag sini-summarize ang conversation upang magbakante ng context, muling ikinakabit ng Claude Code ang pinakabagong invocation ng bawat skill, pinananatili lamang ang unang 5,000 tokens ng bawat isa, at pinupunan ang pinagsamang 25,000-token budget simula sa skill na pinakahuling tinawag. Napuputol sa kalagitnaan ang mahabang skill. Kapag maraming mahahabang skill, tuluyan nilang naaalis ang isa’t isa sa context.

Kaya isulat lamang ang hindi pa alam ng model. Alam nito kung ano ang nginx at kung ano ang ginagawa ng reverse proxy. Hindi nito alam ang house rule mo tungkol sa reload na lampas sa restart, at ang rule na iyon ang tanging dahilan kung bakit umiiral ang file na ito.

Kung inuutusan ng skill ang agent na magpatakbo ng bundled script, pangalanan ang path gamit ang ${CLAUDE_SKILL_DIR} upang mag-resolve ito saanman naka-install ang skill, at i-pre-approve ang parehong command upang hindi huminto ang run sa permission prompt.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/check-and-reload.sh *)
---

Saklaw ng grant ang turn na tumawag sa skill at nililinis ito kapag ipinadala mo ang susunod mong message, kaya hindi ito tahimik na nagiging permanenteng permission.

Paano patunayang gumagana ang skill

Ipinapakitang nahanap ng agent ang skill kapag nakita mong nag-load ito. Hindi nito pinatutunayang nagbago ang sagot. Suriin ang dalawang ito, at gawin ang pagsusuri sa bagong session. Nasa session kung saan mo isinulat ang skill ang lahat ng sinabi mo habang ginagawa ito. Maaaring itago ng natitirang context na iyon ang mga kakulangan sa file.

1. Magsimula ng bagong session gamit ang claude sa project.
2. I-type ang request sa paraang gagamitin mo sa karaniwang araw ng trabaho, gamit ang sarili mong mga salita at hindi binabanggit ang skill.
3. Tingnan kung nag-invoke ito. Kung hindi gumana ang skill, ayusin ang description. Hindi pa body ang problema.
4. Manu-manong i-invoke ito gamit ang /nginx-config-changes bilang control. Kung tama ang behavior kapag manu-manong ini-invoke ngunit mali kapag sa request ito nag-trigger, trigger problem ito at hindi instruction problem.
5. Patakbuhin ang parehong request nang naka-off ang skill at ikumpara ang dalawang sagot. Sa /skills menu, piliin ang skill, pindutin ang Space upang i-cycle ang state nito sa off, pagkatapos ay pindutin ang Enter upang i-save. Isinusulat nito ang entry na skillOverrides sa .claude/settings.local.json. Kapag pinindot muli ang Space, ibinabalik nito ang state sa on kapag tapos ka na.
6. Sumulat ng ilang request na hindi dapat mag-trigger sa skill, at tiyaking hindi ito nagre-react sa mga iyon.

Upang i-automate ang loop na iyon, i-install ang skill-creator plugin mula sa official marketplace.

/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official

Kung sinasabi ng install output na Run /reload-plugins to activate., patakbuhin ang command na iyon. Pagkatapos, hilingin kay Claude na i-evaluate ang skill ayon sa pangalan nito. Iniimbak ng plugin ang mga test case sa evals/evals.json sa loob ng skill directory at pinapatakbo ang bawat case sa sarili nitong subagent, kaya nagsisimula ang bawat run sa malinis na context. Pagkatapos, nagsusulat ito ng paghahambing na with-skill laban sa without-skill. Ito ang tapat na sukatan: ang improvement sa pass rate kumpara sa mga token at oras na ginagamit ng skill.

Maaari ring maglaman ang isang skill ng sarili nitong proof sa halip na ipaubaya ito sa hiwalay na eval run. Ito ang ginagawa ng Old Coder skill kapag ipinapagawa nito sa agent ang isang evidence report na maaari mong patakbuhin muli nang mag-isa.

Mode ng pagkabigo: hindi kailanman nagti-trigger ang skill

I-type mo ang request, ginagawa pa rin ng agent ang dating maling aksyon, at walang lumalabas na skill line. Suriin ang mga ito ayon sa pagkakasunod-sunod.

• Inilalarawan ng description kung ano ang ginagawa ng skill pero hindi nito sinasabi kung kailan ito gagamitin, kaya walang tumutugma rito sa request mo.
• Iniiwasan ng description ang mga salitang tina-type mo. Kung sasabihin mo ang "nginx", dapat ding banggitin ng description ang nginx.
• Naka-set ang disable-model-invocation: true sa frontmatter. Dahil dito, hindi napupunta ang description sa context ng model, at ikaw lang ang maaaring mag-invoke ng skill gamit ang /name.
• Nililimitahan ng paths glob sa frontmatter ang activation sa mga tumutugmang file, at hindi tumutugma rito ang file na ginagawa mo.
• Nasa nested na .claude/skills/ directory ang skill sa ibaba ng starting directory mo. Nilo-load lamang ang mga iyon matapos magbasa o mag-edit ang agent ng file sa loob ng subdirectory na iyon, kaya hindi pa available ang skill bago iyon.

Failure mode: palaging nagti-trigger ang skill

Ang kabaligtarang problema ay isang paglalarawang napakalawak kaya nagti-trigger ang skill sa mga gawaing walang kaugnayan. Ang “Gamitin kapag nagtatrabaho sa server” ay tumutugma sa halos anumang request sa isang server repository. Pagkatapos, nilo-load ng body ang sarili nito sa mga task na hindi nito matutulungan, at nananatili ito sa context sa natitirang bahagi ng session.

Limitahan ang description sa aktuwal na kundisyong mahalaga, at pangalanan ang mga file o command na saklaw nito. Magdagdag ng paths glob kapag partikular na mga file lamang ang saklaw ng skill. Para sa anumang may side effect, gaya ng deploy o commit, itakda ang disable-model-invocation: true at ikaw mismo ang mag-invoke nito gamit ang /name, para hindi kusang magpasya ang agent na magandang oras na para mag-deploy.

Mode ng pagkabigo: sa rules file dapat ilagay ang skill

Ang rules file gaya ng CLAUDE.md o AGENTS.md ay naglo-load sa simula ng bawat session at nalalapat sa bawat task. Naglo-load lamang ang skill body kapag nag-trigger ang skill. Frequency ang batayan ng buong desisyon. Kung naaangkop ang isang fact sa bawat task sa repository, gaya ng package manager na ginagamit mo, dapat itong ilagay sa rules file. Kung naaangkop lamang ang isang procedure sa maliit na bahagi ng mga task, gaya ng nginx rule sa itaas, dapat itong ilagay sa skill. Wala itong dagdag na gastos kapag walang nag-e-edit ng nginx.

Ang tunay na problema ay ang paglalagay nito sa parehong lugar. Magkakaroon ng dalawang kopya na magkakaiba sa paglipas ng panahon. Kapag mali ang ginawa ng agent, hindi mo matutukoy kung aling kopya ang sinunod nito. Pumili ng iisang lugar para sa bawat instruction. Kung nasa eksaktong isang lugar na ang isang rule ngunit nalalampasan pa rin ito, ibang problema iyon. Suriin muna ang mekanismo sa likod ng hindi pagsunod sa instruction bago mo ito ilipat sa isang skill at umasa na maaayos ng paglipat ang problema. Tinutugunan ng hangganan sa pagitan ng skills, MCP servers, at rules files ang mas mahihirap na kaso, kabilang ang mga sitwasyong ang tamang sagot ay isang MCP (model context protocol) server na nagbibigay sa agent ng bagong tool sa halip na bagong instruction.

Ibahagi ito kapag napatunayan na ang halaga nito

Ang skill na tumatagal sa isang linggong aktuwal na trabaho ay sulit nang i-commit. Ang project skills sa .claude/skills/ ay nire-review tulad ng code at kasama sa repository, kaya kapag ni-clone ito ng teammate, makukuha niya ang correction mo nang walang kailangang i-setup. Ang paglipat ng skill sa pagitan ng mga repository nang hindi nagko-copy at paste ay hiwalay na problema. Tinalakay ito sa kung paano magbahagi ng agent skills sa pagitan ng mga repo.

May isang paalala tungkol sa portability. Tumatanggap ang Claude Code ng mahabang listahan ng mga frontmatter field, pero anim lang ang pinapahintulutan ng Agent Skills standard: name, description, license, compatibility, metadata at allowed-tools. Kapag nag-upload ka ng skill sa claude.ai o ni-package ito para sa Skills API na may iba pang field sa frontmatter, tuluyan itong magfa-fail sa halip na balewalain ang field:

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

Manatili sa anim na field na ito para mag-load ang parehong file sa Claude Code at sa iba pang bumabasa ng standard. Kung saan naglo-load ang file ay tumutukoy pa rin sa kaya nitong gawin, dahil tumatakbo ang Cowork sa Anthropic sandbox habang tumatakbo ang Claude Code sa sarili mong machine o VPS. Kaya sulit dalhin ang nginx skill sa checkout ng teammate, pero wala itong silbi sa sandbox na hindi makakonekta sa server. Hiwalay na gawain ang pagsulat ng mga instruction mismo para gumana ang mga ito kapag inilipat sa ibang model, at tinatalakay ito sa pagsulat ng mga skill na gumagana sa anumang model.

FAQ

Gaano dapat kahaba ang SKILL.md file?

Panatilihin itong wala pang 500 linya, at asahan na mas maikli pa rito ang karamihan ng kapaki-pakinabang na skill. Inilalagay ang laman nito sa conversation kapag ginagamit ang skill at nananatili roon sa buong session, kaya bawat linya ay paulit-ulit na cost sa halip na isang beses lang. Ilipat ang mahahabang reference material sa magkakahiwalay na file sa skill directory at i-link ang mga ito mula sa SKILL.md nang isang level lang ang lalim, para basahin lamang ng agent kapag kailangan nito. Isinasagawa ang bundled scripts sa halip na basahin, kaya ang output lamang ng mga ito ang nagiging cost.

Bakit hindi kailanman nagti-trigger ang skill ko?

Karaniwang sanhi ang description, dahil ito lang ang bahagi ng skill na nasa context kapag nagpapasya ang model. Tiyaking sinasabi nito kung kailan gagamitin ang skill, hindi lamang kung ano ang ginagawa nito, at naglalaman ito ng mga salitang aktuwal mong tina-type sa mga request. Kung mukhang tama ang description, tingnan ang frontmatter para sa disable-model-invocation: true, na tuluyang nagtatago sa skill mula sa model, at para sa paths glob na naglilimita rito sa mga file na hindi mo ine-edit. Isa pang sanhi ang skill na nasa nested .claude/skills/ directory sa ibaba ng starting directory: nilo-load lamang ito matapos magbasa o mag-edit ang agent ng file sa subdirectory na iyon.

Skill ba ito o isang linya sa rules file ko?

Tingnan kung gaano karami sa iyong mga task ang saklaw nito. Nilo-load ang rules file sa bawat session, kaya dapat itong maglaman ng mga katotohanang totoo sa bawat task, gaya ng package manager o convention sa pagpapangalan ng branch. Nilo-load lamang ang skill kapag nagti-trigger ito, kaya ito ang tamang paglagyan ng procedure na mahalaga sa maliit na bahagi ng mga task. Huwag kailanman ilagay ang parehong instruction sa dalawang lugar, dahil magkaiba ang magiging kopya ng mga ito sa paglipas ng panahon at mawawala sa iyo ang kakayahang malaman kung alin ang sinunod ng agent.

Paano ko malalaman kung nakatulong talaga ang isang skill?

Ihambing ito sa baseline. Mangolekta ng ilang tunay na request, patakbuhin ang bawat isa sa isang bagong session na available ang skill, pagkatapos ay patakbuhin muli ang mga ito nang naka-off ang skill mula sa /skills menu, at basahin nang magkatabi ang dalawang sagot. Mahalaga ang bagong session dahil naglalaman pa rin ng iyong mga paliwanag ang conversation kung saan mo isinulat ang skill, kaya maaaring magmukhang kumpleto ang isang file na hindi naman kumpleto. Awtomatikong ginagawa ng skill-creator plugin ang paghahambing na ito at iniuulat ang pass rate kasama ng token cost.

Maaari ko bang gamitin ang parehong SKILL.md sa ibang agent?

Oo, basta manatili ka sa loob ng mga field na tinutukoy ng Agent Skills standard: name, description, license, compatibility, metadata at allowed-tools. Tumatanggap ang Claude Code ng marami pang field, at sinusuportahan din nito ang mga body feature gaya ng shell command injection na hindi pinapatakbo ng ibang tool. Kapag nag-upload ka ng skill na may field na wala sa standard, mabibigo ito na may tahasang error na naglilista ng mga pinapahintulutang property, kaya magpasya agad kung mananatili ang skill sa Claude Code o gagamitin sa ibang environment.