{"id":"22e3ea6e-8a0b-4cc4-9c58-03a3e0d6f0c2","shortId":"gktEq2","kind":"skill","title":"create-skill","tagline":"This skill should be used when the user asks to \"create a skill\", \"new skill\", \"scaffold a skill\", \"make a skill\", \"init a skill\", or wants to bootstrap a new agent skill in `.agents/skills` (default) or `~/.agents/skills` (with `--global`).","description":"# Create Skill\n\nBootstrap a new agent skill, then symlink it into `.claude/skills/` so Claude Code can discover it. Default to splitting bulk content into `references/` and `scripts/` so `SKILL.md` stays lean.\n\n## Arguments\n\n- **skill-name** (required): kebab-case name (e.g., `my-skill`). Stop if missing or invalid.\n- `--global` (optional): install under `~` instead of the current repo.\n\n## Resolved Paths\n\n| Mode            | Skill source               | Claude Code symlink       |\n| --------------- | -------------------------- | ------------------------- |\n| local (default) | `.agents/skills/<name>/`   | `.claude/skills/<name>`   |\n| `--global`      | `~/.agents/skills/<name>/` | `~/.claude/skills/<name>` |\n\nThe symlink target is always the relative path `../../.agents/skills/<name>` so it resolves correctly in both scopes.\n\n## Skill Layout\n\n```\n<name>/\n├── SKILL.md       # Required: frontmatter + lean workflow (aim for <500 lines)\n├── scripts/       # Optional: executable code (Bash/Python/etc.) the workflow invokes\n├── references/    # Optional: long-form docs loaded on demand\n└── assets/        # Optional: templates / fonts / images used in OUTPUT (never loaded into context)\n```\n\nAgents load skills via **progressive disclosure**, in three stages:\n\n1. **Discovery** — only `name` + `description` are visible at startup. Front-load triggers in `description`.\n2. **Activation** — the full `SKILL.md` body is read once a task matches.\n3. **Execution** — `scripts/` run without being read into context; `references/` are read only when `SKILL.md` explicitly links to them.\n\nKeep `SKILL.md` focused on workflow. Push bulk into `scripts/` (deterministic logic) or `references/` (documentation).\n\n## When to Split Content\n\n### Use `scripts/` when\n\n- The same code would be rewritten on every invocation (e.g., PDF rotate, JSON transform, curl wrapper).\n- Determinism matters more than flexibility (parsing, validation, codegen, idempotent setup).\n- A shell pipeline grows past ~5 lines or needs real error handling.\n- A long heredoc keeps appearing inside `SKILL.md`.\n\nScripts are token-efficient: the agent invokes them without reading them. Document the CLI signature in `SKILL.md` and leave the implementation in `scripts/`.\n\n### Use `references/` when\n\n- A topic exceeds ~100 lines of prose, examples, or schemas.\n- Content is conditionally relevant (variant-, framework-, or domain-specific) — splitting keeps irrelevant context out.\n- Detailed API surfaces, DB schemas, policies, or large templates would otherwise dominate `SKILL.md`.\n- The same explanation would be repeated across multiple skills (extract once, link from each).\n\nRules of thumb:\n\n- **One level deep** — link `references/placeholder.md` directly from `SKILL.md`, never reference-to-reference.\n- Files >100 lines: include a table of contents at the top.\n- Files >10k words: document grep patterns in `SKILL.md` so the agent can locate sections without reading the whole file.\n- **No duplication** — each fact lives in `SKILL.md` *or* a reference, never both.\n- For every reference, write one line in `SKILL.md` that says *when* to read it.\n\n### Reference organization patterns\n\n**Pattern A — High-level guide + topical references**\n\n```\nSKILL.md\nreferences/\n├── forms.md\n├── api.md\n└── examples.md\n```\n\n`SKILL.md` teaches the happy path; references hold deep-dive material.\n\n**Pattern B — Domain or variant split**\n\n```\nSKILL.md           # workflow + selection logic\nreferences/\n├── aws.md\n├── gcp.md\n└── azure.md\n```\n\nThe agent reads only the variant the user picked — irrelevant providers never enter context.\n\n**Pattern C — Conditional details**\n\nInline the basic case in `SKILL.md`, link advanced files for edge cases (`tracked-changes.md`, `ooxml.md`, etc.).\n\n### Do NOT add to a skill\n\n- `README.md`, `INSTALLATION.md`, `CHANGELOG.md`, `QUICK_REFERENCE.md` — extraneous.\n- Notes about how the skill was authored, test logs, scratch files.\n- Anything the agent will not use at runtime.\n\n## Workflow\n\n### 1. Fetch Agent Skills Docs\n\nAlways fetch the latest spec before authoring frontmatter or content:\n\n- https://agentskills.io\n\nUse `WebFetch` to confirm the current frontmatter schema, naming rules, and progressive-disclosure conventions. Do not guess — the spec evolves.\n\n### 2. Validate\n\n- Reject names that are not kebab-case or collide with an existing skill at the resolved path.\n- Stop if `<scope>/.agents/skills/<name>/` or `<scope>/.claude/skills/<name>` already exists.\n\n### 3. Plan the Layout\n\nBefore writing anything, decide what belongs where:\n\n- Will the workflow invoke helper code? → `scripts/<name>.{sh,py,ts}`\n- Schemas, long examples, variant guides, domain knowledge? → `references/<topic>.md`\n- Templates or files the skill writes into the user's output? → `assets/`\n- None of the above? → ship just `SKILL.md`.\n\nSketch the directory tree first, then create only the subdirectories the layout actually needs.\n\n### 4. Create the Skill\n\n```bash\nmkdir -p \"<scope>/.agents/skills/<name>\"\n# Add only the subdirectories the layout calls for:\n# mkdir -p \"<scope>/.agents/skills/<name>/scripts\"\n# mkdir -p \"<scope>/.agents/skills/<name>/references\"\n```\n\nWrite `<scope>/.agents/skills/<name>/SKILL.md` with:\n\n- Frontmatter sorted alphabetically, with `description` last. The `description` is the only field seen at discovery time — front-load trigger phrases there, not in the body.\n- A short `# Title`.\n- A one-line summary of what the skill does.\n- `## Arguments` (if any) and `## Workflow` sections in **imperative form** with concrete steps.\n- Explicit links to every `references/` file the workflow may need, each with a one-line note describing *when* to read it.\n- CLI signatures for any bundled scripts so the agent can call them without reading them.\n\nAim for `SKILL.md` under 500 lines. If a section grows past ~50 lines and is not core workflow, move it to `references/` and link it.\n\n### 5. Create the Claude Code Symlink\n\nAlways create a relative symlink so Claude Code picks the skill up from its own discovery path:\n\n```bash\nmkdir -p \"<scope>/.claude/skills\"\nln -s \"../../.agents/skills/<name>\" \"<scope>/.claude/skills/<name>\"\n```\n\n### 6. Verify\n\n- `test -f \"<scope>/.agents/skills/<name>/SKILL.md\"`\n- `readlink \"<scope>/.claude/skills/<name>\"` resolves to the source directory.\n- Print both absolute paths to the user.\n\n## Notes\n\n- Frontmatter rule: sort fields alphabetically, but always place `description` last.\n- \"When to use\" information belongs in `description` (discovery-time), not in the body (activation-time only).\n- Use imperative / infinitive form throughout `SKILL.md`.\n- All paths inside `SKILL.md` (e.g., `references/placeholder.md`, `scripts/example.sh`) are relative to the skill directory.\n- Bash scripts inside the skill must be compatible with Bash 3.2 (`/bin/bash`), since Codex uses the built-in Bash by default.\n- Do not commit the new skill — leave that to the user.","tags":["create","skill","agent","skills","paulrberg","agent-skills","ai-agents"],"capabilities":["skill","source-paulrberg","skill-create-skill","topic-agent-skills","topic-ai-agents"],"categories":["agent-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/PaulRBerg/agent-skills/create-skill","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add PaulRBerg/agent-skills","source_repo":"https://github.com/PaulRBerg/agent-skills","install_from":"skills.sh"}},"qualityScore":"0.478","qualityRationale":"deterministic score 0.48 from registry signals: · indexed on github topic:agent-skills · 56 github stars · SKILL.md body (6,916 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-18T18:57:36.199Z","embedding":null,"createdAt":"2026-04-18T22:17:41.655Z","updatedAt":"2026-05-18T18:57:36.199Z","lastSeenAt":"2026-05-18T18:57:36.199Z","tsv":"'/../.agents/skills':124,846 '/.agents/skills':40,114,608,683,694,698,701,852 '/.claude/skills':115,610,843,847,855 '/bin/bash':927 '/references':699 '/scripts':695 '/skill.md':702,853 '1':181,549 '100':323,389 '10k':400 '2':196,586 '3':208,613 '3.2':926 '4':676 '5':279,817 '50':803 '500':141,796 '6':848 'absolut':863 'across':364 'activ':197,894 'activation-tim':893 'actual':674 'add':520,684 'advanc':510 'agent':34,48,172,299,409,486,542,551,785 'agents/skills':37,111 'agentskills.io':564 'aim':139,792 'alphabet':706,873 'alreadi':611 'alway':120,554,823,875 'anyth':540,619 'api':346 'api.md':458 'appear':290 'argument':74,743 'ask':12 'asset':160,654 'author':535,560 'aws.md':482 'azure.md':484 'b':472 'bash':680,840,916,925,935 'bash/python/etc':147 'basic':505 'belong':622,883 'bodi':201,729,892 'bootstrap':31,45 'built':933 'built-in':932 'bulk':64,233 'bundl':781 'c':500 'call':690,787 'case':81,506,514,595 'changelog.md':526 'claud':56,106,820,829 'claude/skills':54,112 'cli':307,777 'code':57,107,146,250,629,821,830 'codegen':271 'codex':929 'collid':597 'commit':940 'compat':923 'concret':753 'condit':332,501 'confirm':568 'content':65,244,330,395,563 'context':171,216,343,498 'convent':579 'core':808 'correct':128 'creat':2,14,43,668,677,818,824 'create-skil':1 'curl':262 'current':99,570 'db':348 'decid':620 'deep':377,468 'deep-div':467 'default':38,61,110,937 'demand':159 'describ':772 'descript':185,195,708,711,877,885 'detail':345,502 'determin':264 'determinist':236 'direct':380 'directori':664,860,915 'disclosur':177,578 'discov':59 'discoveri':182,718,838,887 'discovery-tim':886 'dive':469 'doc':156,553 'document':240,305,402 'domain':338,473,639 'domain-specif':337 'domin':356 'duplic':419 'e.g':83,257,907 'edg':513 'effici':297 'enter':497 'error':284 'etc':517 'everi':255,431,758 'evolv':585 'exampl':327,636 'examples.md':459 'exceed':322 'execut':145,209 'exist':600,612 'explan':360 'explicit':223,755 'extract':367 'extran':528 'f':851 'fact':421 'fetch':550,555 'field':715,872 'file':388,399,417,511,539,645,760 'first':666 'flexibl':268 'focus':229 'font':163 'form':155,751,900 'forms.md':457 'framework':335 'front':191,721 'front-load':190,720 'frontmatt':136,561,571,704,869 'full':199 'gcp.md':483 'global':42,92,113 'grep':403 'grow':277,801 'guess':582 'guid':452,638 'handl':285 'happi':463 'helper':628 'heredoc':288 'high':450 'high-level':449 'hold':466 'idempot':272 'imag':164 'imper':750,898 'implement':314 'includ':391 'infinit':899 'inform':882 'init':25 'inlin':503 'insid':291,905,918 'instal':94 'installation.md':525 'instead':96 'invalid':91 'invoc':256 'invok':150,300,627 'irrelev':342,494 'json':260 'kebab':80,594 'kebab-cas':79,593 'keep':227,289,341 'knowledg':640 'larg':352 'last':709,878 'latest':557 'layout':133,616,673,689 'lean':73,137 'leav':312,944 'level':376,451 'line':142,280,324,390,435,736,770,797,804 'link':224,369,378,509,756,815 'live':422 'ln':844 'load':157,169,173,192,722 'local':109 'locat':411 'log':537 'logic':237,480 'long':154,287,635 'long-form':153 'make':22 'match':207 'materi':470 'matter':265 'may':763 'md':642 'miss':89 'mkdir':681,692,696,841 'mode':103 'move':810 'multipl':365 'must':921 'my-skil':84 'name':77,82,184,573,589 'need':282,675,764 'never':168,383,428,496 'new':17,33,47,942 'none':655 'note':529,771,868 'one':375,434,735,769 'one-lin':734,768 'ooxml.md':516 'option':93,144,152,161 'organ':445 'otherwis':355 'output':167,653 'p':682,693,697,842 'pars':269 'past':278,802 'path':102,123,464,605,839,864,904 'pattern':404,446,447,471,499 'pdf':258 'phrase':724 'pick':493,831 'pipelin':276 'place':876 'plan':614 'polici':350 'print':861 'progress':176,577 'progressive-disclosur':576 'prose':326 'provid':495 'push':232 'py':632 'quick_reference.md':527 'read':203,214,219,303,414,442,487,775,790 'readlink':854 'readme.md':524 'real':283 'refer':67,151,217,239,318,385,387,427,432,444,454,456,465,481,641,759,813 'reference-to-refer':384 'references/placeholder.md':379,908 'reject':588 'relat':122,826,911 'relev':333 'repeat':363 'repo':100 'requir':78,135 'resolv':101,127,604,856 'rewritten':253 'rotat':259 'rule':372,574,870 'run':211 'runtim':547 'say':439 'scaffold':19 'schema':329,349,572,634 'scope':131 'scratch':538 'script':69,143,210,235,246,293,316,630,782,917 'scripts/example.sh':909 'section':412,748,800 'seen':716 'select':479 'setup':273 'sh':631 'shell':275 'ship':659 'short':731 'signatur':308,778 'sinc':928 'sketch':662 'skill':3,5,16,18,21,24,27,35,44,49,76,86,104,132,174,366,523,533,552,601,647,679,741,833,914,920,943 'skill-create-skill' 'skill-nam':75 'skill.md':71,134,200,222,228,292,310,357,382,406,424,437,455,460,477,508,661,794,902,906 'sort':705,871 'sourc':105,859 'source-paulrberg' 'spec':558,584 'specif':339 'split':63,243,340,476 'stage':180 'startup':189 'stay':72 'step':754 'stop':87,606 'subdirectori':671,687 'summari':737 'surfac':347 'symlink':51,108,117,822,827 'tabl':393 'target':118 'task':206 'teach':461 'templat':162,353,643 'test':536,850 'three':179 'throughout':901 'thumb':374 'time':719,888,895 'titl':732 'token':296 'token-effici':295 'top':398 'topic':321,453 'topic-agent-skills' 'topic-ai-agents' 'tracked-changes.md':515 'transform':261 'tree':665 'trigger':193,723 'ts':633 'use':8,165,245,317,545,565,881,897,930 'user':11,492,651,867,948 'valid':270,587 'variant':334,475,490,637 'verifi':849 'via':175 'visibl':187 'want':29 'webfetch':566 'whole':416 'without':212,302,413,789 'word':401 'workflow':138,149,231,478,548,626,747,762,809 'would':251,354,361 'wrapper':263 'write':433,618,648,700","prices":[{"id":"a856553a-b8ca-496a-b4d3-654ef4fc7518","listingId":"22e3ea6e-8a0b-4cc4-9c58-03a3e0d6f0c2","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"PaulRBerg","category":"agent-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T22:17:41.655Z"}],"sources":[{"listingId":"22e3ea6e-8a0b-4cc4-9c58-03a3e0d6f0c2","source":"github","sourceId":"PaulRBerg/agent-skills/create-skill","sourceUrl":"https://github.com/PaulRBerg/agent-skills/tree/main/skills/create-skill","isPrimary":false,"firstSeenAt":"2026-04-18T22:17:41.655Z","lastSeenAt":"2026-05-18T18:57:36.199Z"}],"details":{"listingId":"22e3ea6e-8a0b-4cc4-9c58-03a3e0d6f0c2","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"PaulRBerg","slug":"create-skill","github":{"repo":"PaulRBerg/agent-skills","stars":56,"topics":["agent-skills","ai-agents"],"license":"mit","html_url":"https://github.com/PaulRBerg/agent-skills","pushed_at":"2026-05-17T10:33:19Z","description":"PRB's collection of agent skills","skill_md_sha":"68e6301f90179d11fb7b58d678041afa4999e7f1","skill_md_path":"skills/create-skill/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/PaulRBerg/agent-skills/tree/main/skills/create-skill"},"layout":"multi","source":"github","category":"agent-skills","frontmatter":{"name":"create-skill","description":"This skill should be used when the user asks to \"create a skill\", \"new skill\", \"scaffold a skill\", \"make a skill\", \"init a skill\", or wants to bootstrap a new agent skill in `.agents/skills` (default) or `~/.agents/skills` (with `--global`)."},"skills_sh_url":"https://skills.sh/PaulRBerg/agent-skills/create-skill"},"updatedAt":"2026-05-18T18:57:36.199Z"}}