{"id":"017c6f84-039c-46eb-8a4f-70689144e148","shortId":"UtG5F7","kind":"skill","title":"create-skill","tagline":"Use when creating, writing, or authoring a new Cursor agent skill, or when asking about skill structure, SKILL.md format, or skill best practices.","description":"# Create Skill\n\n## Skill Types\n\nCategorize before writing -- this determines structure, degrees of freedom, and testing approach:\n\n- **Technique**: concrete method with steps (e.g. condition-based-waiting)\n- **Pattern**: mental model / way of thinking (e.g. flatten-with-flags)\n- **Reference**: API docs, syntax guides, tool documentation\n- **Workflow**: multi-step process with decision points (e.g. ship-it)\n\n## Requirements Gathering\n\nInfer from conversation context when possible. If clarification is needed, use AskQuestion (or ask conversationally if unavailable). Capture:\n\n1. **Purpose and scope**: what specific task or workflow\n2. **Storage location**: personal (`~/.cursor/skills/`) or project (`.cursor/skills/`)\n3. **Trigger scenarios**: when should the agent apply this skill\n4. **Domain knowledge**: what the agent wouldn't already know\n5. **Output format**: templates, styles, or conventions required\n6. **Existing patterns**: examples or conventions to follow\n\n## Design\n\n### Name\n\n- Lowercase letters, numbers, hyphens only. Max 64 chars\n- Prefer verb-first or gerund form: `create-skill` > `skill-creation`, `analyze-sessions` > `session-analysis`\n- Name by what you DO or core insight, not generic labels\n- Avoid: `helper`, `utils`, `tools`, `misc`\n\n### Description (CSO-Critical)\n\nThe description determines whether the agent loads this skill. Max 1024 chars, third person.\n\n**Start with \"Use when...\"** -- describe ONLY triggering conditions (symptoms, situations, contexts).\n\n**NEVER summarize the skill's workflow or process.** Testing shows agents follow descriptions as shortcuts, skipping the full skill body. A description saying \"does X then Y\" causes agents to do exactly X then Y without reading the actual detailed instructions.\n\nInclude concrete triggers: error messages, symptoms, tool names, synonyms.\n\n```yaml\n# BAD: workflow summary -- agent will shortcut to this\ndescription: Analyzes code diffs, generates commit messages, and pushes to remote.\n\n# BAD: too vague\ndescription: Helps with documents.\n\n# GOOD: triggering conditions only\ndescription: Use when reviewing pull requests, examining code changes, or when asked for a code review.\n\n# GOOD: specific triggers with keywords\ndescription: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently.\n```\n\n### Directory Layout\n\n```\nskill-name/\n├── SKILL.md              # Required -- main instructions\n├── reference.md          # Optional -- detailed docs (progressive disclosure)\n└── scripts/              # Optional -- utility scripts\n    └── validate.py\n```\n\n## Authoring Principles\n\n### Conciseness\n\nThe context window is shared. Only add what the agent doesn't already know. Challenge each paragraph: \"Does this justify its token cost?\"\n\n```markdown\n# GOOD (~50 tokens): assumes agent knows what PDFs are\n## Extract PDF text\nUse pdfplumber:\n  import pdfplumber\n  with pdfplumber.open(\"file.pdf\") as pdf:\n      text = pdf.pages[0].extract_text()\n\n# BAD (~150 tokens): explains what a PDF is\nPDF (Portable Document Format) files are a common file format...\n```\n\n### Progressive Disclosure\n\nKeep SKILL.md under 500 lines. Put detailed reference material in separate files the agent reads only when needed. Keep references **one level deep** from SKILL.md -- deeply nested references may be partially read.\n\n```markdown\n## Advanced features\n**Form filling**: See [FORMS.md](FORMS.md) for complete guide\n**API reference**: See [REFERENCE.md](REFERENCE.md) for all methods\n```\n\nFor reference files over 100 lines, include a table of contents at the top.\n\n### Degrees of Freedom\n\nMatch specificity to task fragility:\n\n- **High freedom** (text instructions): multiple valid approaches, context-dependent. Example: code review guidelines\n- **Medium freedom** (pseudocode/templates): preferred pattern with acceptable variation. Example: report generation\n- **Low freedom** (exact scripts): fragile operations, consistency critical. Example: database migrations -- \"Run exactly this. Do not modify.\"\n\n### Token Efficiency\n\n- Move details to `--help` flags or reference files\n- Cross-reference other skills instead of repeating content\n- One excellent example beats many mediocre ones\n- Compress examples: show minimal input/output, not verbose narratives\n\n## Common Patterns\n\nBrief summary below. See [best-practices.md](best-practices.md) for detailed examples with good/bad comparisons.\n\n- **Template**: provide output format templates (strict for APIs, flexible for analysis)\n- **Examples**: input/output pairs showing desired style and detail level\n- **Workflow/Checklist**: sequential steps with copy-paste progress checklist\n- **Conditional workflow**: decision points guiding to different paths\n- **Feedback loop**: validate → fix → re-validate cycle for quality-critical tasks\n\n## Script Guidelines\n\nWhen including utility scripts:\n\n- **Solve, don't punt**: handle errors explicitly instead of failing and letting the agent figure it out\n- **Self-documenting constants**: no magic numbers -- comment why each value was chosen\n- **Clear intent**: state whether the agent should **execute** the script (\"Run `analyze.py`\") or **read** it as reference (\"See `analyze.py` for the algorithm\")\n- Pre-made scripts are more reliable than generated code, save tokens, and ensure consistency\n\n## MCP Tool References\n\nAlways use fully qualified names: `ServerName:tool_name`\n\n```markdown\nUse the GitHub:create_issue tool to create issues.\nUse the Atlassian:getJiraIssueTypeMetaWithFields tool to discover custom fields.\n```\n\n## External Content and Licensing\n\nWhen incorporating content from web sources or OSS into a skill:\n\n- **Inline the content** -- skills should be self-contained with no runtime web lookups\n- **Always cite the source URL** even when content is fully inlined\n- **Comply with licensing terms**: MIT/Apache/etc. require copyright notice preserved\n- Include a **Sources** section in the skill with attribution and license type\n- For OSS: link to the repo/file, note the license, credit the author(s)\n- For web content (docs, blog posts): link to the source URL for reference\n\n## Testing and Validation\n\nSkills are TDD applied to process documentation. If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.\n\n### RED -- Baseline\n\nRun a representative scenario WITHOUT the skill. Document:\n- What choices did the agent make?\n- What rationalizations did it use (verbatim)?\n- Which pressures triggered violations?\n\n### GREEN -- Write Minimal Skill\n\nWrite the skill addressing those specific failures. Run the same scenario WITH the skill. The agent should now comply.\n\n### REFACTOR -- Close Loopholes\n\nAgent found a new rationalization? Add an explicit counter. Re-test until the skill is robust.\n\n### Testing by Skill Type\n\n- **Discipline-enforcing** (rules/requirements): pressure scenarios combining time + sunk cost + exhaustion\n- **Technique** (how-to guides): application scenarios + edge cases + missing-information tests\n- **Pattern** (mental models): recognition scenarios + counter-examples (when NOT to apply)\n- **Reference** (documentation): retrieval scenarios + application scenarios + gap testing\n\n### Bulletproofing Discipline Skills\n\nFor skills that enforce rules, agents will rationalize under pressure:\n\n- Don't just state the rule -- forbid specific workarounds\n- Build a rationalization table: `| Excuse | Reality |`\n- Create a red flags list for self-checking\n- Address \"spirit vs letter\" arguments: \"Violating the letter of the rules IS violating the spirit\"\n\n## Verification Checklist\n\nBefore finalizing:\n\n- [ ] Description starts with \"Use when...\" -- triggering conditions only, no workflow summary\n- [ ] SKILL.md body is under 500 lines\n- [ ] Consistent terminology throughout (pick one term, use it everywhere)\n- [ ] File references are one level deep from SKILL.md\n- [ ] No time-sensitive information (use \"old patterns\" section if needed)\n- [ ] Examples are concrete, not abstract\n- [ ] Tested with a representative scenario (baseline → with skill)\n- [ ] External content is inlined with source attribution\n\n## Anti-Patterns\n\n- **Narrative storytelling**: \"In session 2025-10-03, we found...\" -- too specific, not reusable\n- **Multi-language dilution**: one excellent example in the most relevant language beats mediocre examples in five languages\n- **Workflow summary in description**: causes agents to shortcut past the actual skill body\n- **Generic labels**: helper1, step3, pattern4 -- labels should have semantic meaning\n- **Windows-style paths**: always use forward slashes (`scripts/helper.py`)\n- **Too many options**: provide a default with an escape hatch, not a menu of five libraries\n- **Vague names**: `helper`, `utils`, `tools` -- name by what the skill does\n- **Inconsistent terminology**: pick one term (e.g. always \"API endpoint\", not mixing \"URL\", \"route\", \"path\")\n\n---\n\n## Sources\n\nContent in this skill and [best-practices.md](best-practices.md) incorporates material from:\n\n- [Anthropic: Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)\n- [obra/superpowers: writing-skills](https://github.com/obra/superpowers/blob/main/skills/writing-skills/SKILL.md) -- used under [MIT License](https://github.com/obra/superpowers/blob/main/LICENSE), copyright Jesse Vincent","tags":["create","skill","issue","paultyng","agent-skills","ai-tools","claude-code","cursor","dotfiles"],"capabilities":["skill","source-paultyng","skill-create-skill","topic-agent-skills","topic-ai-tools","topic-claude-code","topic-cursor","topic-dotfiles"],"categories":["skill-issue"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/paultyng/skill-issue/create-skill","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add paultyng/skill-issue","source_repo":"https://github.com/paultyng/skill-issue","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 (9,350 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:00.696Z","embedding":null,"createdAt":"2026-05-18T13:21:25.590Z","updatedAt":"2026-05-18T19:09:00.696Z","lastSeenAt":"2026-05-18T19:09:00.696Z","tsv":"'-03':1119 '-10':1118 '/.cursor/skills':116 '/docs/en/agents-and-tools/agent-skills/best-practices)':1235 '/obra/superpowers/blob/main/license),':1249 '/obra/superpowers/blob/main/skills/writing-skills/skill.md)':1242 '0':414 '1':103 '100':492 '1024':215 '150':418 '2':112 '2025':1117 '3':120 '4':130 '5':140 '50':392 '500':440,1060 '6':148 '64':164 'abstract':1094 'accept':530 'actual':268,1154 'add':373,929 'address':905,1026 'advanc':470 'agent':13,126,135,210,240,258,284,376,395,450,669,691,856,886,917,924,997,1149 'algorithm':707 'alreadi':138,379 'alway':726,782,1171,1209 'analysi':184,610 'analyz':180,290 'analyze-sess':179 'analyze.py':697,704 'anthrop':1228 'anti':1111 'anti-pattern':1110 'api':65,480,607,1210 'appli':127,846,980 'applic':961,985 'approach':42,516 'argument':1030 'ask':17,98,322 'askquest':96 'assum':394 'atlassian':746 'attribut':810,1109 'author':9,364,825,1230 'avoid':196 'bad':281,300,417 'base':51 'baselin':873,1100 'beat':574,1138 'best':25,1231 'best-practices.md':592,593,1223,1224 'blog':831 'bodi':249,1057,1156 'brief':588 'build':1011 'bulletproof':989 'captur':102 'case':964 'categor':31 'caus':257,1148 'challeng':381 'chang':319 'char':165,216 'check':1025 'checklist':628,1042 'choic':883 'chosen':685 'cite':783 'clarif':92 'clear':686 'close':922 'code':291,318,325,521,717 'combin':951 'comment':680 'commit':294 'common':432,586 'comparison':599 'complet':478 'compli':793,920 'compress':578 'concis':366 'concret':44,272,1092 'condit':50,226,309,338,629,1051 'condition-based-wait':49 'consist':541,722,1062 'constant':676 'contain':776 'content':498,570,754,759,770,789,829,1104,1218 'context':88,229,368,518 'context-depend':517 'convent':146,153 'convers':87,99 'copi':625 'copy-past':624 'copyright':799,1250 'core':191 'cost':389,954 'counter':932,975 'counter-exampl':974 'creat':2,6,27,174,738,742,1017 'create-skil':1,173 'creation':178 'credit':823 'critic':204,542,648 'cross':563 'cross-refer':562 'cso':203 'cso-crit':202 'cursor':12 'cursor/skills':119 'custom':751 'cycl':644 'databas':544 'decis':77,631 'deep':459,1076 'deepli':462 'default':1181 'degre':37,502 'depend':340,519 'describ':223 'descript':201,206,242,251,289,303,311,332,1045,1147 'design':156 'desir':615 'detail':269,355,443,555,595,618 'determin':35,207 'didn':852 'diff':292 'differ':635 'dilut':1129 'directori':344 'disciplin':946,990 'discipline-enforc':945 'disclosur':358,436 'discov':750 'doc':66,356,830 'document':70,306,427,675,849,881,982 'doesn':377 'domain':131 'e.g':48,59,79,1208 'edg':963 'effici':553 'endpoint':1211 'enforc':947,995 'ensur':721 'error':274,661 'escap':1184 'even':787 'everywher':1070 'exact':261,537,547 'examin':317 'exampl':151,520,532,543,573,579,596,611,976,1090,1132,1140 'excel':572,1131 'excus':1015 'execut':693 'exhaust':955 'exist':149 'explain':420 'explicit':662,931 'extern':753,1103 'extract':400,415 'fail':665,857 'failur':908 'featur':471 'feedback':637 'field':752 'figur':670 'file':429,433,448,490,561,1071 'file.pdf':409 'fill':473 'final':1044 'first':169 'five':1142,1190 'fix':640 'flag':63,558,1020 'flatten':61 'flatten-with-flag':60 'flexibl':608 'follow':155,241 'forbid':1008 'form':172,472 'format':22,142,428,434,603 'forms.md':475,476 'forward':1173 'found':925,1121 'fragil':509,539 'freedom':39,504,511,525,536 'full':247 'fulli':728,791 'gap':987 'gather':84 'generat':293,534,716 'generic':194,1157 'gerund':171 'getjiraissuetypemetawithfield':747 'github':737 'github.com':1241,1248 'github.com/obra/superpowers/blob/main/license),':1247 'github.com/obra/superpowers/blob/main/skills/writing-skills/skill.md)':1240 'good':307,327,391 'good/bad':598 'green':898 'guid':68,479,633,960 'guidelin':523,651 'handl':660 'hatch':1185 'help':304,557 'helper':197,1194 'helper1':1159 'high':510 'how-to':957 'hyphen':161 'import':405 'includ':271,494,653,802 'inconsist':343,1203 'incorpor':758,1225 'infer':85 'inform':967,1083 'inlin':768,792,1106 'input/output':582,612 'insight':192 'instead':567,663 'instruct':270,352,513 'intent':687 'issu':739,743 'jess':1251 'justifi':386 'keep':437,455 'keyword':331 'know':139,380,396,864 'knowledg':132 'label':195,1158,1162 'languag':1128,1137,1143 'layout':345 'let':667 'letter':159,1029,1033 'level':458,619,1075 'librari':1191 'licens':756,795,812,822,1246 'line':441,493,1061 'link':816,833 'list':1021 'load':211 'locat':114 'lookup':781 'loop':638 'loophol':923 'low':535 'lowercas':158 'made':710 'magic':678 'main':351 'make':887 'mani':575,1177 'markdown':390,469,734 'match':505 'materi':445,1226 'max':163,214 'may':465 'mcp':723 'mean':1166 'mediocr':576,1139 'medium':524 'mental':54,970 'menu':1188 'messag':275,295 'method':45,487 'migrat':545 'minim':581,900 'misc':200 'miss':966 'missing-inform':965 'mit':1245 'mit/apache/etc':797 'mix':1213 'model':55,971 'modifi':551 'move':554 'multi':73,1127 'multi-languag':1126 'multi-step':72 'multipl':514 'name':157,185,278,348,730,733,1193,1197 'narrat':585,1113 'need':94,454,1089 'nest':463 'never':230 'new':11,927 'note':820 'notic':800 'number':160,679 'obra/superpowers':1236 'old':1085 'one':457,571,577,1066,1074,1130,1206 'oper':540 'option':354,360,1178 'oss':764,815 'output':141,602 'pair':613 'paragraph':383 'partial':467 'pass/fail':342 'past':626,1152 'path':636,1170,1216 'pattern':53,150,528,587,969,1086,1112 'pattern4':1161 'pdf':401,411,423,425 'pdf.pages':413 'pdfplumber':404,406 'pdfplumber.open':408 'pdfs':398 'person':115,218 'pick':1065,1205 'platform.claude.com':1234 'platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)':1233 'point':78,632 'portabl':426 'possibl':90 'post':832 'practic':26,1232 'pre':709 'pre-mad':708 'prefer':166,527 'preserv':801 'pressur':895,949,1001 'principl':365 'process':75,237,848 'progress':357,435,627 'project':118 'provid':601,1179 'pseudocode/templates':526 'pull':315 'punt':659 'purpos':104 'push':297 'put':442 'qualifi':729 'qualiti':647 'quality-crit':646 'race':337 'ration':889,928,999,1013 're':642,934 're-test':933 're-valid':641 'read':266,451,468,699 'realiti':1016 'recognit':972 'red':872,1019 'refactor':921 'refer':64,444,456,464,481,489,560,564,702,725,839,981,1072 'reference.md':353,483,484 'relev':1136 'reliabl':714 'remot':299 'repeat':569 'repo/file':819 'report':533 'repres':876,1098 'request':316 'requir':83,147,350,798 'retriev':983 'reusabl':1125 'review':314,326,522 'right':870 'robust':940 'rout':1215 'rule':996,1007,1036 'rules/requirements':948 'run':546,696,874,909 'runtim':779 'save':718 'say':252 'scenario':122,877,912,950,962,973,984,986,1099 'scope':106 'script':359,362,538,650,655,695,711 'scripts/helper.py':1175 'section':805,1087 'see':474,482,591,703 'self':674,775,1024 'self-check':1023 'self-contain':774 'self-docu':673 'semant':1165 'sensit':1082 'separ':447 'sequenti':621 'servernam':731 'session':181,183,1116 'session-analysi':182 'share':371 'ship':81 'ship-it':80 'shortcut':244,286,1151 'show':239,580,614 'situat':228 'skill':3,14,19,24,28,29,129,175,177,213,233,248,347,566,767,771,808,843,860,867,880,901,904,915,938,943,991,993,1102,1155,1201,1221,1229,1239 'skill-creat':176 'skill-create-skill' 'skill-nam':346 'skill.md':21,349,438,461,1056,1078 'skip':245 'slash':1174 'solv':656 'sourc':762,785,804,836,1108,1217 'source-paultyng' 'specif':108,328,506,907,1009,1123 'spirit':1027,1040 'start':219,1046 'state':688,1005 'step':47,74,622 'step3':1160 'storag':113 'storytel':1114 'strict':605 'structur':20,36 'style':144,616,1169 'summar':231 'summari':283,589,1055,1145 'sunk':953 'symptom':227,276 'synonym':279 'syntax':67 'tabl':496,1014 'task':109,508,649 'tdd':845 'teach':868 'techniqu':43,956 'templat':143,600,604 'term':796,1067,1207 'terminolog':1063,1204 'test':41,238,335,840,935,941,968,988,1095 'text':402,412,416,512 'thing':871 'think':58 'third':217 'throughout':1064 'time':339,952,1081 'time-sensit':1080 'token':388,393,419,552,719 'tool':69,199,277,724,732,740,748,1196 'top':501 'topic-agent-skills' 'topic-ai-tools' 'topic-claude-code' 'topic-cursor' 'topic-dotfiles' 'trigger':121,225,273,308,329,896,1050 'type':30,813,944 'unavail':101 'url':786,837,1214 'use':4,95,221,312,333,403,727,735,744,892,1048,1068,1084,1172,1243 'util':198,361,654,1195 'vagu':302,1192 'valid':515,639,643,842 'validate.py':363 'valu':683 'variat':531 'verb':168 'verb-first':167 'verbatim':893 'verbos':584 'verif':1041 'vincent':1252 'violat':897,1031,1038 'vs':1028 'wait':52 'watch':854 'way':56 'web':761,780,828 'whether':208,689 'window':369,1168 'windows-styl':1167 'without':265,858,878 'workaround':1010 'workflow':71,111,235,282,630,1054,1144 'workflow/checklist':620 'wouldn':136 'write':7,33,899,902,1238 'writing-skil':1237 'x':254,262 'y':256,264 'yaml':280","prices":[{"id":"2cb068dc-5532-44f8-a0b6-15e7c3a160f4","listingId":"017c6f84-039c-46eb-8a4f-70689144e148","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"paultyng","category":"skill-issue","install_from":"skills.sh"},"createdAt":"2026-05-18T13:21:25.590Z"}],"sources":[{"listingId":"017c6f84-039c-46eb-8a4f-70689144e148","source":"github","sourceId":"paultyng/skill-issue/create-skill","sourceUrl":"https://github.com/paultyng/skill-issue/tree/main/skills/create-skill","isPrimary":false,"firstSeenAt":"2026-05-18T13:21:25.590Z","lastSeenAt":"2026-05-18T19:09:00.696Z"}],"details":{"listingId":"017c6f84-039c-46eb-8a4f-70689144e148","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"paultyng","slug":"create-skill","github":{"repo":"paultyng/skill-issue","stars":8,"topics":["agent-skills","ai-tools","claude-code","cursor","dotfiles"],"license":"mit","html_url":"https://github.com/paultyng/skill-issue","pushed_at":"2026-05-18T18:26:54Z","description":"Personal Claude Code / Cursor agent skills, rules, and config","skill_md_sha":"49cd9f87868c919e7a0f49e6fb2dfa5b697c1ec5","skill_md_path":"skills/create-skill/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/paultyng/skill-issue/tree/main/skills/create-skill"},"layout":"multi","source":"github","category":"skill-issue","frontmatter":{"name":"create-skill","description":"Use when creating, writing, or authoring a new Cursor agent skill, or when asking about skill structure, SKILL.md format, or skill best practices."},"skills_sh_url":"https://skills.sh/paultyng/skill-issue/create-skill"},"updatedAt":"2026-05-18T19:09:00.696Z"}}