skill creator

{
  "schema_version": 1,
  "type": "skill",
  "slug": "skill-creator",
  "title": "skill creator",
  "brief": "Authors, tests, iterates on, and submits Claude Code skills (SKILL.md files) for the Adom ecosystem. Use when the user wants to create a new skill, write or update a SKILL.md, contribute a skill back",
  "version": "1.0.0",
  "tags": [],
  "license": "MIT",
  "sample_prompts": [
    {
      "label": "New skill",
      "prompt": "Help me create a new skill for the parts-search CLI"
    },
    {
      "label": "Skill description",
      "prompt": "Rewrite my SKILL.md description so it triggers reliably"
    },
    {
      "label": "Test a skill",
      "prompt": "Test that my skill triggers on the right prompts"
    },
    {
      "label": "Submit skill",
      "prompt": "Submit this skill back to the gallia repo"
    },
    {
      "label": "Skill iteration",
      "prompt": "My skill isn't being matched — help me fix the description"
    }
  ],
  "source_path": "SKILL.md",
  "readme": "---\nname: skill-creator\ndescription: Authors, tests, iterates on, and submits Claude Code skills (SKILL.md files) for the Adom ecosystem. Use when the user wants to create a new skill, write or update a SKILL.md, contribute a skill back to Adom's gallia repo, or asks how skills work. Covers frontmatter conventions, writing effective descriptions, progressive disclosure with reference files, deploying to ~/.claude/skills/, iterating on failures, and PR submission.\n---\n\n# Creating Adom Skills\n\nSkills are Markdown documents that teach Claude Code how to perform specialized tasks. They live in the `gallia` repo and get distributed to all Adom users via `node install.mjs`, which copies every directory under `skills/` that contains a `SKILL.md` into `~/.claude/skills/`.\n\nOnly the `name` and `description` from each skill's frontmatter are pre-loaded at startup. SKILL.md is read when the description matches the user's task; reference files are read only when SKILL.md points to them. This progressive disclosure is why keeping SKILL.md concise matters — every token loaded competes with conversation history.\n\n> **IMPORTANT — Always show the result to the user.** After creating or updating a visual skill, you MUST open the output in front of the user (a Hydrogen webview panel tab) so they can see it immediately. Never tell the user to navigate there themselves — drive it for them.\n>\n> **Use `app-creator` for any new visual skill.** Adom Viewer (AV) is\n> **deprecated** and is no longer the canonical display surface. New\n> skills that render HTML, charts, 3D content, dashboards, or widgets\n> should ship as Hydrogen webview apps via the `app-creator` skill, not\n> as `av_display` pushes. The `av-creator` skill is kept only for\n> maintaining un-ported legacy AV views.\n\n## Architecture\n\n```\n/home/adom/gallia/skills/my-skill/\n    SKILL.md              # main instructions (under 500 lines)\n    reference.md          # optional, loaded only when needed\n    examples.md           # optional, loaded only when needed\n    scripts/              # optional, executed not loaded\n    preferences.json      # optional, user-configurable defaults\n\n# After `node install.mjs`:\n~/.claude/skills/my-skill/SKILL.md\n```\n\n## Workflow Checklist\n\nCopy and track progress:\n\n```\n- [ ] Step 1: Scope and name the skill\n- [ ] Step 2: Write SKILL.md frontmatter and body\n- [ ] Step 3: Deploy to ~/.claude/skills/ and test real trigger phrases\n- [ ] Step 4: Iterate — fix trigger misses and instruction failures\n- [ ] Step 5: Submit to gallia (see submission.md)\n```\n\n## Step 1: Scope and Name\n\nOne skill, one purpose. If the scope is growing, split it — a 50-line skill that solves one problem beats a 500-line skill covering everything.\n\nUse kebab-case for the directory, matching the `name` field:\n\n```bash\nmkdir -p /home/adom/gallia/skills/my-skill-name\n```\n\nBefore creating a new skill, check whether one already covers the need. Search `/home/adom/gallia/skills/` and the Adom Wiki (`adom-wiki` skill) for overlapping triggers.\n\n## Step 2: Write SKILL.md\n\n### Frontmatter\n\n```yaml\n---\nname: my-skill-name\ndescription: <third person, what + when, includes trigger phrases>\n---\n```\n\nThe Claude Code skill-frontmatter schema supports exactly these fields: `name`, `description`, `argument-hint`, `compatibility`, `disable-model-invocation`, `license`, `metadata`, `user-invocable`. Anything else (including `author`) is silently ignored at runtime but flagged as unsupported by the IDE's skill linter — don't set it.\n\n| Field | Required | Convention |\n|-------|----------|------------|\n| `name` | yes | Matches the skill directory name. Convention: kebab-case, short and descriptive. Avoid `claude` and `anthropic` even though the Claude Code loader accepts them. |\n| `description` | yes | Must be a string scalar. Target ≤1024 chars — fits inside the 1,536-char listing cap. Empty descriptions get auto-synthesized from the body, so always set one explicitly. |\n| `user-invocable` | no | `true` if the user can trigger it with `/skill-name`. Default: auto-trigger only. The gallia ecosystem commonly uses `user-invokable` (with `k`) — that's a misspelling; the supported field is `user-invocable`. |\n| `argument-hint` | no | Short hint shown when the skill takes `/skill-name <args>`. String. |\n| `compatibility` | no | Version-constraint metadata. Rare; see existing plugin skills. |\n| `disable-model-invocation` | no | `true` to make a skill purely user-invocable (no auto-trigger). |\n| `license` | no | SPDX-style license string. |\n| `metadata` | no | Free-form map for tool-specific extensions (e.g., `effort` values). |\n\n### Constraints and caps\n\n**Hard runtime limits:**\n\n- Descriptions are capped at **1,536 chars** in the skill listing the selector reads. Anything past that is invisible — the selector can't match text it never sees.\n- Listing budget is **2% of the context window**, shared across all skills.\n- `description` must be a string scalar; arrays and objects are rejected.\n- Empty `description` is silently auto-synthesized from the body's first heading/paragraph, which is usually worse than what you'd write — always set one.\n- Hooks and `metadata.effort` are schema-validated when present.\n- The IDE linter warns on frontmatter fields outside the supported set.\n\n**Authoring targets** — good practice, not enforced:\n\n- `description` ≤ 1024 chars. Fits well inside the 1,536-char listing cap and keeps the skill from crowding the shared budget.\n- Name in kebab-case; avoid `claude` and `anthropic` even though the loader accepts them.\n- SKILL.md body ≤ 500 lines; split into reference files past that.\n- No XML tags in `name` or `description`.\n\nThe loader does not check name length, name charset, reserved words, description length, tag content, or body size. These are style rules — useful to follow, but violations load without error. Rely on the IDE linter and review, not runtime feedback.\n\nLong trigger lists belong in the body (a \"Trigger phrases\" section), not in the frontmatter description — once the skill is selected, the whole body loads. The frontmatter only needs enough signal for the selector to pick it.\n\n### Writing the description\n\nThe description is injected into the system prompt and is how Claude picks this skill from 100+ candidates. Write it in **third person**, stating both what the skill does and when to use it. Include quoted trigger phrases the user might say.\n\n**Good:**\n\n```yaml\ndescription: Creates KiCad footprints (.kicad_mod files) from datasheet dimensions, validates pad placement, and previews in a Hydrogen webview tab. Use when the user says \"create a footprint\", \"make a .kicad_mod\", or wants to visualize a footprint.\n```\n\n**Bad:**\n\n```yaml\ndescription: A tool for making footprints.              # vague\ndescription: I can help you make footprints.             # first person\ndescription: You can use this to make footprints.        # second person\n```\n\n### Body: tone and structure\n\nWrite imperative, technical instructions for Claude, not for the user.\n\n- **Keep the body under 500 lines.** Past that, move details into reference files (see \"Progressive disclosure\" below).\n- **Number steps when order matters.** Use `##` headers.\n- **Always tag code blocks** with the language.\n- **Use absolute file paths** starting from `/home/adom/`. Never relative paths.\n- **Forward slashes only** — never `\\`, even for Windows-hosted content.\n- **MCP tools:** reference as `ServerName:tool_name` so Claude can find them when multiple MCP servers are loaded. Example: `GitHub:create_issue`.\n- **KiCad S-expression files** (`.kicad_sym`, `.kicad_mod`, `.kicad_sch`) reject `;;` and `#` comments — never add them to those files.\n- **No time-sensitive info.** \"As of August 2025...\" rots. Put deprecated patterns in a collapsed \"Old patterns\" section instead.\n- **Consistent terminology.** Pick one term (e.g., \"Adom Viewer\", or consistently \"AV\" after first definition) and stick with it.\n\n### Matching specificity to task fragility\n\nThe guide distinguishes three levels of instruction freedom:\n\n- **High freedom** (narrative steps) — when multiple approaches are valid and context determines the best one. Example: a code-review skill that lists what to look for but doesn't mandate an exact workflow.\n- **Medium freedom** (templates or parameterized scripts) — when a preferred pattern exists but some variation is acceptable.\n- **Low freedom** (one exact command, no flags) — when the operation is fragile, order-sensitive, or destructive. Example: database migrations, KiCad file edits, publish commands.\n\nFavor low freedom for anything that touches user data, shared state, or the wiki.\n\n### Content patterns\n\n**Template pattern** — for strict output formats. See [examples.md](examples.md) → \"Template Pattern\".\n\n**Examples pattern** — when output quality depends on seeing concrete input/output pairs. See [examples.md](examples.md) → \"Examples Pattern\".\n\n**Workflow with feedback loop** — validator → fix → retry, for quality-critical multi-step tasks. See [examples.md](examples.md) → \"Workflow with Feedback Loop\".\n\n### Progressive disclosure\n\nIf SKILL.md approaches 500 lines, split content into reference files and link from SKILL.md.\n\n**Keep references one level deep.** If SKILL.md points to `reference.md`, don't have `reference.md` point to `deeper.md` — Claude may partial-read deeply-chained files with `head` and miss content. Every reference file should link directly from SKILL.md.\n\n```\nmy-skill/\n├── SKILL.md        # overview + pointers\n├── reference.md    # API or schema reference\n└── examples.md     # usage examples\n```\n\nIn SKILL.md:\n\n```markdown\n**Advanced features**: See [reference.md](reference.md)\n**Examples**: See [examples.md](examples.md)\n```\n\nFor any reference file over 100 lines, add a table of contents at the top so Claude sees the full scope even when previewing with `head`.\n\n## Step 3: Deploy for Testing\n\nCopy the skill to `~/.claude/skills/` so Claude Code picks it up in the current session:\n\n```bash\ncp -r /home/adom/gallia/skills/my-skill-name /home/adom/.claude/skills/my-skill-name\n```\n\nOpen a new Claude Code session and try a trigger phrase from the description. Verify:\n\n1. The skill appears in the session's skills list (check the system reminder)\n2. Claude invokes it on the expected phrase\n3. The instructions produce correct output on at least one real task\n4. Edge cases and errors are handled\n\n## Step 4: Iterate\n\nEdit the source file in gallia, then re-copy to `~/.claude/skills/`:\n\n```bash\ncp -r /home/adom/gallia/skills/my-skill-name /home/adom/.claude/skills/my-skill-name\n```\n\nCommon failure modes:\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| Skill doesn't trigger | Description too vague or missing the user's phrasing | Add specific quoted trigger phrases; include file formats and key nouns |\n| Claude ignores instructions | SKILL.md too long or too vague | Be specific and imperative; split into reference files |\n| Wrong file paths | Relative paths confuse Claude across sessions | Use absolute paths starting from `/home/adom/` |\n| Reference file ignored | Linked from another reference, not SKILL.md | Flatten to one level — link from SKILL.md directly |\n| Claude reads only the top of a long reference file | No table of contents | Add TOC to any reference file > 100 lines |\n| Two skills fight over the same trigger | Overlapping descriptions | Narrow each description; the more specific wins |\n\n**Test with the models you plan to use.** What works for Opus may need more detail for Haiku. Adom defaults to Opus/Sonnet but some users run Haiku for speed — aim for instructions that work with all three.\n\n**Test with real usage, not just contrived prompts.** Watch what Claude actually reads, what it skips, and where it misinterprets. Adjust based on observed behavior, not assumed behavior.\n\n## Step 5: Submit to Gallia\n\nOnce the skill works, submit it so all Adom users benefit. The installer auto-discovers any `skills/*/SKILL.md`, so a merge is enough to deploy.\n\nSee [submission.md](submission.md) for the complete submission workflow: pre-flight checklist, PR template, updating `skills/README.md` and `skills/adom/SKILL.md` routing, direct push, and publishing to the Adom Wiki. For skills with a visual surface, route to `app-creator` instead of adding AV explainer entries.\n\n## Skill Complexity Guidelines\n\n| Type | Lines | Examples |\n|------|-------|---------|\n| **Reference** | 20-100 | `use-cases`, `adom-molecules-catalog` — static documentation, catalogs |\n| **Setup/Config** | 100-300 | `openclaw-setup` — step-by-step install guides with troubleshooting |\n| **Infrastructure** | 300-500 (split beyond) | `adom`, `adom-wiki` — MCP tool reference, API docs |\n| **Creator** | 500+ (use reference files) | `symbol-creator`, `footprint-creator` — multi-step workflows with validation, preview, delivery |\n\nStart small. Split into reference files before the body exceeds 500 lines.\n\n## Optional: Preferences File\n\nIf the skill has user-configurable settings, create `preferences.json`:\n\n```json\n{\n  \"default_library\": \"my-lib\",\n  \"verbose\": true\n}\n```\n\nLoad it at the start of the workflow:\n\n```markdown\n## Step 1: Load Preferences\n\nRead `/home/adom/.claude/skills/my-skill-name/preferences.json`. If the file doesn't exist, ask the user for their preferences and write defaults.\n```\n\n## Related Skills\n\nWhen the scope of what you're building extends past authoring:\n\n- **`app-creator`** — Building a visual skill as a Hydrogen webview app (mini HTTP server with a webview panel UI). The canonical display surface for new skills.\n- **`standalone-service`** — Skills backed by a dedicated container with a shared HTTP API (JLCPCB, Mouser, KiCad CLI patterns). Use when the skill needs a large shared dataset or persistent server.\n- **`wiki-submission`** — Publishing the skill's page to the Adom Wiki: demo viewers, red-box calibration, screenshot galleries, asset uploads.\n- **`av-creator`** (legacy) — Kept only for maintaining un-ported AV views. Do not use for new work.\n\n## Examples and Templates\n\nSee [examples.md](examples.md) for:\n\n- A minimal complete skill (copy as a starting point)\n- Template, examples, and workflow patterns\n- Script conventions — solve problems, not punt; justify constants\n\n## Anti-patterns\n\n- **Offering too many options.** Pick one default approach and an escape hatch, not a menu of five libraries.\n- **Verbose framing.** Don't explain what PDFs are or how libraries work — Claude knows.\n- **Scripts that re-raise to Claude.** Handle expected errors in the script; don't rely on Claude inspecting stack traces.\n- **\"Voodoo constants.\"** `TIMEOUT = 47` with no comment. If you don't know the right value, Claude can't either — justify it.\n- **Nested references.** `SKILL.md → a.md → b.md → c.md` loses content. Flatten to one level.\n\n## Troubleshooting\n\n| Symptom | Fix |\n|---------|-----|\n| `install.mjs` doesn't copy the skill | The directory must contain `SKILL.md` (exact capitalization), not `skill.md` or `SKILLS.md` |\n| Skill appears in the list but never triggers | Description is too generic or the match-worthy triggers are past ~240 chars and truncated — move them to the front |\n| Skill listing shows the description cut off mid-sentence | Expected at ~250 chars (`prompt.ts:29`). Rewrite the description so the load-bearing triggers come first |\n| Two skills claim the same triggers | Narrow each description; the more specific one wins in the model's selection |\n| Frontmatter parse error | YAML requires `---` on its own line. CRLF line endings (`\\r\\n`) break strict parsers — run `sed -i 's/\\r$//' SKILL.md` if the file was created on Windows |\n| Description comes out as unexpected text | If the YAML description is empty, the loader synthesizes one from the body's first heading/paragraph. Set an explicit description to control what the selector sees |\n",
  "author": {
    "id": "695820315b5f1e4db2fcf602",
    "name": "Kyle Bergstedt",
    "email": "[email protected]"
  },
  "visibility": {
    "public": true
  },
  "hero": null,
  "discovery_triggers": [],
  "discovery_pitch": null,
  "metadata": {},
  "created_at": "2026-05-28T05:29:43.824Z",
  "updated_at": "2026-05-28T05:29:43.824Z",
  "sub_skills": [],
  "parent_app": null
}