Paano Sumulat ng Sariling Agent Skill

Sumulat ng sariling agent skill mula sa isang totoong failure

Ang pinakamahusay na paraan para sumulat ng sariling agent skill ay ang kunin ito mula sa isang totoong failure. Maghanap ng task na dalawang beses nagawa nang mali ng coding agent, isulat ang correction na dalawang beses mong itinype, at i-save ang correction bilang SKILL.md file na kayang i-load ng agent nang mag-isa. Pagkatapos nito, mechanics na lang ang lahat: ang file layout at ang isang line na nagpapasya kung gagana ba ang skill.

Mahalaga ang pagkakasunod-sunod na ito. Ang skill na isinulat mula sa imahinasyon ay nagdodokumento ng problemang hindi mo pa nararanasan, at kumokonsumo pa rin ito ng context sa bawat session. Ang skill na hinango mula sa isang failure na nasaksihan mo ay may kasama nang sariling 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 agent, pagkatapos ay bumalik at sumulat ng isa.

Magsimula sa task na dalawang beses na maling ginawa ng agent

Ang isang beses ay maaaring nagkataon. Ang dalawang beses ay pattern na, at karapat-dapat bigyan ng file ang isang pattern.

Narito ang failure na paulit-ulit na nangyayari sa mga totoong server. Inuutusan mo ang agent na magdagdag ng reverse proxy block sa nginx. Ine-edit nito ang /etc/nginx/conf.d/app.conf, at pagkatapos ay pinapatakbo ang sudo systemctl restart nginx. May typo ang edit, kaya tumatangging mag-start ang nginx at down 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.

Itinutuwid mo ito sa chat. I-test ang config gamit ang sudo nginx -t bago galawin ang service, pagkatapos ay i-apply ito gamit ang reload sa halip na restart. Makalipas ang isang linggo, sa ibang task, inuulit ang parehong pagkakamali. Ang ikalawang pag-ulit ang signal.

Isulat ang dalawang bagay habang nakikita pa ang failure: ang request na itinype mo at ang correction na ibinigay mo, gamit ang mismong mga salitang ginamit mo. Ang dalawang linyang ito ang magiging skill. Sinasabi ng request kung ano ang dapat i-match ng trigger. Ang correction ang magiging buong content.

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

Anatomy ng isang skill

Ang 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

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

---
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, lowercase letters, digits, at hyphens lamang; hindi rin nito maaaring taglayin ang mga salitang claude o anthropic. Sa personal o project skill, ito lamang ang display label. Ang command na tina-type mo ay nagmumula sa directory name, kaya tumutugon ito sa /nginx-config-changes.
• description: inilalarawan kung ano ang ginagawa ng skill at kung kailan ito gagamitin, hanggang 1,024 characters. Ito ang aktuwal na gumagawa ng mahalagang gawain, 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 lamang ang lalim ng mga link, dahil ang file na nire-reference mula sa isa pang nire-reference na file ay madalas bahagyang nababasa lamang.
• scripts/: mga file na ine-execute ng agent sa halip na basahin. Ang output lamang ng mga ito ang kumokonsumo ng context, kaya mura sa context ang isang 300-line script.

Ang lokasyon ng directory ang nagtatakda kung sino ang makakagamit ng skill.

• .claude/skills/<name>/SKILL.md sa repository: para lamang sa project na ito, at kasama ito para sa lahat ng nagko-clone ng repo.
• ~/.claude/skills/<name>/SKILL.md: para sa bawat project sa machine mo, at hindi para sa 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. Minomonitor ni Claude Code ang mga directory na ito, kaya nagkakabisa sa kasalukuyang session ang pag-edit sa isang umiiral na skill. Kung gagawa ka ng top-level skills directory na wala noong nagsimula ang session, kailangan mong mag-restart dahil walang imo-monitor nang magsimula ang session.

Ang description field ang may pinakamalaking epekto sa file

Sa startup, 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 iisang linyang iyon ang buong batayan sa pagpapasya kung relevant 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, kung saan magmumukhang ang model ang nagsasalita kapag first person ang ginamit.

Isama rito ang dalawang bagay: kung ano ang ginagawa ng skill, at kung kailan ito ginagamit. Ilagay muna ang pangunahing use case, dahil tina-truncate ng Claude Code ang listing entry sa 1,536 characters. May optional na when_to_use field para sa dagdag na trigger phrase at example request. Idinadagdag ito sa description sa loob ng parehong limit.

Gamitin naman ang mga salitang aktuwal mong ita-type. Walang namamatch ang description: Helps with nginx dahil walang nagta-type ng “helps with.” Binabanggit ng naunang version ang /etc/nginx, server block, reverse proxy at TLS (transport layer security) certificate path, na halos tumutugma sa vocabulary ng anumang request na dapat mag-trigger dito.

Narito ang test para sa description. Ibigay ang iisang linyang iyon sa isang taong hindi pa nakakakita ng body, kasama ang request na ita-type mo, at tanungin kung applicable ang skill. Kung hindi niya matukoy, hindi rin ito matutukoy ng model.

Panatilihing maikli ang body dahil nananatili ito sa context

Kapag invoked ang isang skill, pumapasok ang rendered content nito sa conversation bilang isang message at nananatili roon sa buong session. Hindi na muling binabasa ng Claude Code ang file sa mga susunod na turn. Ang bawat linyang isinusulat mo ay cost para sa buong session, hindi lang para sa isang sagot.

Inirerekomenda ng Anthropic na panatilihing wala sa SKILL.md ang higit sa 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 para 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 na-invoke. Napuputol ang mahabang skill sa kalagitnaan. Kapag maraming mahahabang skill, maaari nilang tuluyang mapalabas ang isa't isa sa context.

Kaya isulat lamang ang mga bagay na 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, ilagay ang path gamit ang ${CLAUDE_SKILL_DIR} upang mag-resolve ito saanman naka-install ang skill, at i-pre-approve ang parehong command para hindi maantala ang run dahil 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 nag-invoke sa skill at nililinis ito kapag nagpadala ka ng susunod na message. Kaya hindi ito tahimik na nagiging permanenteng permission.

Paano patunayang gumagana ang skill

Ipinapakita ng pag-monitor sa pag-load ng skill na natagpuan ito ng agent. Hindi nito ipinapakitang nagbago ang sagot. Suriin ang dalawang ito, at gawin ang pagsusuri sa bagong session, dahil 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 ginagamit mo sa karaniwang araw ng trabaho, gamit ang sarili mong mga salita at hindi binabanggit ang skill.
3. Tingnan kung nagkaroon ng invocation. Kung hindi gumana ang skill, ayusin ang description. Hindi pa body ang problema.
4. Mano-manong i-invoke ito gamit ang /nginx-config-changes bilang control. Kung tama ang behavior kapag mano-manong ini-invoke ngunit mali kapag request ang nag-trigger, problema ito sa trigger at hindi sa instructions.
5. Patakbuhin ang parehong request nang naka-off ang skill at ikumpara ang dalawang sagot. Sa /skills menu, i-highlight ang skill, pindutin ang Space upang i-cycle ang state nito sa off, pagkatapos ay pindutin ang Enter upang i-save. Nagsusulat ito ng entry na skillOverrides sa .claude/settings.local.json, at kapag pinindot muli ang Space, mai-cycle ito pabalik sa on kapag tapos ka na.
6. Sumulat ng ilang request na hindi dapat mag-trigger sa skill, at tiyaking nananatili itong tahimik sa mga iyon.

Upang ma-automate ang loop na ito, 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. Ini-store 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 na sinusukat batay sa mga token at oras na ginugugol ng skill.

Failure mode: hindi kailanman nagti-trigger ang skill

I-type 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. Dahil dito, walang tumutugma sa request mo.
• Iniiwasan ng description ang mga salitang tina-type mo. Kung sasabihin mo ang "nginx", dapat ding sabihin ng description ang nginx.
• Naka-set ang disable-model-invocation: true sa frontmatter. Dahil dito, ganap na hindi nakikita ng model ang description, at ikaw lang ang makakatawag sa skill gamit ang /name.
• Nililimitahan ng paths glob sa frontmatter ang activation sa mga tumutugmang file, pero hindi tumutugma rito ang file na ginagawa mo.
• Nasa nested na .claude/skills/ directory ang skill sa ibaba ng starting directory mo. Naglo-load lamang ang mga ito matapos magbasa o mag-edit ang agent ng file sa loob ng subdirectory na iyon. Kaya hindi pa available ang skill bago iyon.

Mode ng failure: palaging nagti-trigger ang skill

Ang kabaligtarang problema ay isang paglalarawang sobrang lawak kaya nagti-trigger ang skill sa mga gawaing walang kaugnayan. Ang “Use when working on the 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 tukuyin ang mga file o command na saklaw nito. Magdagdag ng paths glob kapag ilang file lang 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.

Failure mode: ang skill ay dapat nasa rules file

Naglo-load ang isang rules file gaya ng CLAUDE.md o AGENTS.md sa simula ng bawat session at nalalapat sa bawat task. Naglo-load lamang ang skill body kapag nag-fire ang skill. Dalas ang batayan ng buong desisyon. Ang fact na nalalapat sa bawat task sa repository, gaya ng package manager na ginagamit mo, ay dapat nasa rules file. Ang procedure na nalalapat lamang sa maliit na bahagi ng mga task, gaya ng nginx rule sa itaas, ay dapat nasa skill, kung saan wala itong dagdag na gastos sa mga araw na walang nag-e-edit ng nginx.

Ang tunay na failure ay ang paglalagay nito sa parehong lugar. Magkakahiwalay ang dalawang kopya, at kapag mali ang ginawa ng agent, hindi mo matutukoy kung aling kopya ang sinunod nito. Pumili ng iisang lugar para sa bawat instruction. Tinutugunan ng hangganan sa pagitan ng skills, MCP servers, at rules files ang mas mahihirap na sitwasyon, kabilang ang mga pagkakataong 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 nito ang halaga nito

Ang skill na nakatagal sa isang linggo ng aktuwal na trabaho ay dapat nang i-commit. Sinusuri ang project skills sa .claude/skills/ na parang code, at kasama ang mga ito sa repository. Kaya kapag nag-clone ang isang teammate, makukuha niya ang iyong correction nang walang kailangang i-setup. Ang paglilipat ng skill sa pagitan ng mga repository nang hindi nagko-copy at paste ay hiwalay na problema, at saklaw ito ng 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 frontmatter fields, pero anim lang ang pinapahintulutan ng Agent Skills standard: name, description, license, compatibility, metadata at allowed-tools. Kung mag-upload ka ng skill sa claude.ai o i-package ito para sa Skills API na may ibang field sa frontmatter, tuluyang mabibigo ang pag-load nito 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 upang ma-load ang parehong file sa Claude Code at sa iba pang nagbabasa ng standard. Hiwalay na gawain ang pagsulat ng mismong mga instruction upang gumana ang mga ito kapag inilipat sa ibang model, at tinatalakay ito sa pagsulat ng skills na gumagana sa anumang model.

FAQ

Gaano dapat kahaba ang isang SKILL.md file?

Panatilihin itong mas maikli sa 500 linya, at asahang mas maikli pa rito ang karamihan ng mga kapaki-pakinabang na skill. Kapag na-invoke ang skill, pumapasok ang body nito sa conversation at nananatili roon hanggang sa matapos ang session. Ibig sabihin, recurring cost ang bawat linya at hindi one-time cost. Ilipat ang mahahabang reference material sa magkahiwalay na file sa skill directory at i-link ang mga ito mula sa SKILL.md, na isang level lang ang lalim, para basahin lamang ito ng agent kapag kailangan. Ine-execute ang bundled scripts sa halip na basahin, kaya output lang ng mga ito ang nagiging cost.

Bakit hindi kailanman nagti-trigger ang skill ko?

Karaniwang sanhi ang description, dahil ito lamang 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 na naglalaman ito ng mga salitang aktuwal mong tina-type sa mga request. Kung tama ang description, tingnan ang frontmatter para sa disable-model-invocation: true, na ganap na nagtatago sa skill mula sa model, at para sa isang 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: naglo-load lamang ito pagkatapos magbasa o mag-edit ang agent ng file sa subdirectory na iyon.

Skill ba ito o isang linya sa rules file ko?

Tingnan kung ilang task ang saklaw nito. Naglo-load ang rules file sa bawat session, kaya dapat naglalaman ito ng mga fact na totoo sa bawat task, gaya ng package manager o branch naming convention. Naglo-load lamang ang skill kapag nag-trigger ito, kaya ito ang tamang paglalagyan ng procedure na kailangan sa maliit na bahagi ng mga task. Huwag isulat ang parehong instruction sa dalawang lugar, dahil magdi-drift ang dalawang kopya at mawawala ang kakayahan mong malaman kung alin ang sinunod ng agent.

Paano ko malalaman kung nakatulong talaga ang isang skill?

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

Magagamit ko ba ang parehong SKILL.md sa ibang agent?

Oo, basta mananatili 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 ine-execute ng ibang tool. Kapag nag-upload ka ng skill na may field na wala sa standard, magfa-fail ito at magpapakita ng explicit error na naglilista sa mga pinapahintulutang property. Kaya magpasya agad kung mananatili ang skill sa Claude Code o gagamitin din sa ibang tool.