{"id":"846d9187-ddda-493c-8f47-c566e1f0ab4d","shortId":"akyecH","kind":"skill","title":"write-a-skill","tagline":"Create new agent skills with proper structure and progressive disclosure. Use when user wants to create, write, or build a new skill, or asks \"make a skill for X\".","description":"# Write a Skill\n\n## Process\n\n1. **Clarify scope** -- ask the user (use AskUserQuestion when available; otherwise present as numbered options):\n   - \"What type of skill?\" — Options: \"Pure instructions (no scripts)\", \"Instructions + helper scripts\", \"Wrapper around CLI tool\"\n   - \"Does it need pre-loaded context?\" — Options: \"Yes — auto-run commands on load (Recommended)\", \"No — gather context during workflow\"\n2. **Explore existing skills** -- `ls` the skills repo, read similar skills for conventions\n3. **Draft** -- create `SKILL.md`\n4. **Review with user** -- confirm coverage, ask what's missing\n\n## Structure\n\n```\nskill-name/\n├── SKILL.md              # Required. All instructions live here.\n└── scripts/              # Optional. Executable helpers only.\n    └── scan-secrets.sh\n```\n\nKeep everything in SKILL.md. Only use `scripts/` for executable files (.sh, .py) that are called via Bash.\n\n## SKILL.md Template\n\n```md\n---\nname: skill-name\ndescription: One sentence what it does. Use when [triggers]. Don't use when [anti-triggers].\n---\n\n# Skill Name\n\n## Workflow\n[numbered steps]\n\n## Rules\n[hard constraints]\n\n## Error Handling\n[if X -- do Y]\n```\n\n## Frontmatter Fields\n\n| Field | Required | Notes |\n|---|---|---|\n| `name` | yes | kebab-case, matches directory |\n| `description` | yes | Agent's only signal for when to load this skill |\n\n## Description Rules\n\nThe description is the **only thing the agent sees** when choosing which skill to load.\n\n- Max 1024 chars\n- First sentence: what it does\n- Second sentence: `Use when [triggers]`\n- Third sentence (optional): `Don't use when [anti-triggers]`\n\n**Good:** `Groups unstaged changes into atomic commits by concern. Use when user says \"atomic commits\" or wants to split changes before pushing.`\n**Bad:** `Helps with commits.`\n\n## Examples\n\n**Minimal skill** -- pure instructions, fits in ~20 lines:\n```md\n---\nname: grill-me\ndescription: Interview the user relentlessly about a plan. Use when user says \"grill me\".\n---\n\n[instructions...]\n```\n\n**Pre-loaded context** -- `!` prefix auto-runs commands on load:\n```md\n## Pre-loaded context\n\n- Status: !`git status`\n- Diff: !`git diff HEAD`\n```\n\nAvoids wasting a turn fetching context the agent always needs.\n\n## Rules\n\n- No time-sensitive info (versions, dates) in skills\n- Include error handling for foreseeable failure modes\n- Test the skill by invoking it before shipping\n\n## Anti-patterns\n\n- Description without triggers: `\"Helps with testing.\"` -- useless\n- Hardcoded versions or dates that go stale\n- No error handling for skills that run Bash commands","tags":["write","skill","agent","skills","helderberto","agent-skills","ai-tools","antigravity","claude-code","cursor","developer-tools","gemini-cli"],"capabilities":["skill","source-helderberto","skill-write-a-skill","topic-agent-skills","topic-ai-tools","topic-antigravity","topic-claude-code","topic-cursor","topic-developer-tools","topic-gemini-cli","topic-markdown","topic-plugin","topic-sdlc","topic-skills","topic-tracer-bullet"],"categories":["agent-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/helderberto/agent-skills/write-a-skill","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add helderberto/agent-skills","source_repo":"https://github.com/helderberto/agent-skills","install_from":"skills.sh"}},"qualityScore":"0.454","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 8 github stars · SKILL.md body (2,564 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:09:15.410Z","embedding":null,"createdAt":"2026-05-18T13:14:55.642Z","updatedAt":"2026-05-18T19:09:15.410Z","lastSeenAt":"2026-05-18T19:09:15.410Z","tsv":"'1':38 '1024':229 '2':90 '20':284 '3':103 '4':107 'agent':7,201,220,336 'alway':337 'anti':171,249,365 'anti-pattern':364 'anti-trigg':170,248 'around':66 'ask':28,41,113 'askuserquest':45 'atom':256,264 'auto':79,312 'auto-run':78,311 'avail':47 'avoid':329 'bad':273 'bash':149,388 'build':23 'call':147 'case':196 'chang':254,270 'char':230 'choos':223 'clarifi':39 'cli':67 'command':81,314,389 'commit':257,265,276 'concern':259 'confirm':111 'constraint':180 'context':75,87,309,321,334 'convent':102 'coverag':112 'creat':5,20,105 'date':346,377 'descript':157,199,211,214,291,367 'diff':325,327 'directori':198 'disclosur':14 'draft':104 'error':181,350,382 'everyth':134 'exampl':277 'execut':129,141 'exist':92 'explor':91 'failur':354 'fetch':333 'field':188,189 'file':142 'first':231 'fit':282 'forese':353 'frontmatt':187 'gather':86 'git':323,326 'go':379 'good':251 'grill':289,303 'grill-m':288 'group':252 'handl':182,351,383 'hard':179 'hardcod':374 'head':328 'help':274,370 'helper':63,130 'includ':349 'info':344 'instruct':59,62,124,281,305 'interview':292 'invok':360 'kebab':195 'kebab-cas':194 'keep':133 'line':285 'live':125 'load':74,83,208,227,308,316,320 'ls':94 'make':29 'match':197 'max':228 'md':152,286,317 'minim':278 'miss':116 'mode':355 'name':120,153,156,174,192,287 'need':71,338 'new':6,25 'note':191 'number':51,176 'one':158 'option':52,57,76,128,243 'otherwis':48 'pattern':366 'plan':298 'pre':73,307,319 'pre-load':72,306,318 'prefix':310 'present':49 'process':37 'progress':13 'proper':10 'pure':58,280 'push':272 'py':144 'read':98 'recommend':84 'relentless':295 'repo':97 'requir':122,190 'review':108 'rule':178,212,339 'run':80,313,387 'say':263,302 'scan-secrets.sh':132 'scope':40 'script':61,64,127,139 'second':236 'see':221 'sensit':343 'sentenc':159,232,237,242 'sh':143 'ship':363 'signal':204 'similar':99 'skill':4,8,26,31,36,56,93,96,100,119,155,173,210,225,279,348,358,385 'skill-nam':118,154 'skill-write-a-skill' 'skill.md':106,121,136,150 'source-helderberto' 'split':269 'stale':380 'status':322,324 'step':177 'structur':11,117 'templat':151 'test':356,372 'thing':218 'third':241 'time':342 'time-sensit':341 'tool':68 'topic-agent-skills' 'topic-ai-tools' 'topic-antigravity' 'topic-claude-code' 'topic-cursor' 'topic-developer-tools' 'topic-gemini-cli' 'topic-markdown' 'topic-plugin' 'topic-sdlc' 'topic-skills' 'topic-tracer-bullet' 'trigger':165,172,240,250,369 'turn':332 'type':54 'unstag':253 'use':15,44,138,163,168,238,246,260,299 'useless':373 'user':17,43,110,262,294,301 'version':345,375 'via':148 'want':18,267 'wast':330 'without':368 'workflow':89,175 'wrapper':65 'write':2,21,34 'write-a-skil':1 'x':33,184 'y':186 'yes':77,193,200","prices":[{"id":"d0a157dc-c533-46a0-93f7-4dfbd388a874","listingId":"846d9187-ddda-493c-8f47-c566e1f0ab4d","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"helderberto","category":"agent-skills","install_from":"skills.sh"},"createdAt":"2026-05-18T13:14:55.642Z"}],"sources":[{"listingId":"846d9187-ddda-493c-8f47-c566e1f0ab4d","source":"github","sourceId":"helderberto/agent-skills/write-a-skill","sourceUrl":"https://github.com/helderberto/agent-skills/tree/main/skills/write-a-skill","isPrimary":false,"firstSeenAt":"2026-05-18T13:14:55.642Z","lastSeenAt":"2026-05-18T19:09:15.410Z"}],"details":{"listingId":"846d9187-ddda-493c-8f47-c566e1f0ab4d","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"helderberto","slug":"write-a-skill","github":{"repo":"helderberto/agent-skills","stars":8,"topics":["agent-skills","ai","ai-tools","antigravity","claude-code","cursor","developer-tools","gemini-cli","markdown","plugin","sdlc","skills","tracer-bullet"],"license":"mit","html_url":"https://github.com/helderberto/agent-skills","pushed_at":"2026-05-14T11:37:47Z","description":"My personal SDLC toolbelt for AI coding agents — PRD to ship.","skill_md_sha":"866785484facf15e74bf8dda7e5c38404a5dcb9e","skill_md_path":"skills/write-a-skill/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/helderberto/agent-skills/tree/main/skills/write-a-skill"},"layout":"multi","source":"github","category":"agent-skills","frontmatter":{"name":"write-a-skill","description":"Create new agent skills with proper structure and progressive disclosure. Use when user wants to create, write, or build a new skill, or asks \"make a skill for X\"."},"skills_sh_url":"https://skills.sh/helderberto/agent-skills/write-a-skill"},"updatedAt":"2026-05-18T19:09:15.410Z"}}