The 10-minute pre-share checklist

The 10 most common authoring mistakes

1. Description too vague. "A skill for Israeli things" routes badly. Use the "Use when X, Y, Z. Do NOT use for A, B" pattern.
2. No "Do NOT use for" clause. Without it, the LLM loads your skill in the wrong context and produces a confidently-wrong answer.
3. Hebrew calques in display_description or SKILL_HE.md. "שכבת האסטרטגיה", "שתי שאלות עוגן", literal English word order. A native Israeli reader spots this in 5 seconds.
4. Fabricated thresholds, form numbers, or law citations. Wrong tax brackets in 2026. Wrong Bituach Leumi form numbers. The reviewer cross-checks against primary sources; fabrications are rejected hard.
5. Slug does not match folder name. Sync pipeline picks up the folder name; metadata.name must match exactly.
6. No worked example in the body. Without examples, the LLM hallucinates edge cases.
7. References to files in references/ or scripts/ that do not exist. Local validator catches this. Run it.
8. Wrong supported_agents slugs. claude instead of claude-code, gemini instead of gemini-cli. Renders as empty gray icons on the card.
9. Em dashes anywhere in SKILL.md, SKILL_HE.md, or metadata.json. Project convention is no em dashes, period. Use commas, parens, colons.
10. Forgot to bump version in metadata.json after edits. Sync silently overwrites content but the catalog's version indicator stays stale and the update-skill admin flow has nothing to fan out to followers.

The 10-minute pre-publish checklist (literal)

Run these in order. Each is one shell command or a 30-second read.

1. Grep all three files for the em-dash character (U+2014). The output must be empty.
2. jq -r '.name' metadata.json and verify it equals basename "$(pwd)".
3. Read your description aloud. Does it answer "when should the LLM load this?" in one sentence? Does it have a "Do NOT use for" clause?
4. Read SKILL_HE.md aloud (or have a native Hebrew speaker read it). Does it read like Hebrew, or like translated English?
5. Pick one number, percentage, or NIS amount in your body. Open the primary source for it. Confirm it matches.
6. Pick the chapter with the most decision logic. Find the worked example. Re-derive it on paper to confirm the math.
7. List the files in references/ and scripts/. For each, grep SKILL.md to confirm it is referenced.
8. If you are publishing to a catalog with rendered preview UI, open that catalog's dev environment (or staging) and confirm everything looks right, including any supported-agent icons or platform logos.
9. Bump the version (in your frontmatter, in metadata.json, or in a git tag, wherever you track it).
10. If your distribution channel runs a validator script, run it locally one last time before pushing.

If all 10 pass, share. If any fail, fix locally first.

The "would the chatbot's default answer be better?" test

The single most important question to ask before sharing: would a user be BETTER off without your skill, getting the LLM's default answer?

Some skills fail this test silently. The skill gets installed; it routes correctly; the LLM dutifully loads the body; and the response is WORSE than what Claude would have said without the skill at all, because the skill author hardcoded outdated information or oversimplified the rule.

This happens when the skill's body is older than the underlying source. A skill that quotes prior-year tax brackets, last-year's average wage, or a fee schedule from before a recent regulator change is worse than no skill at all. The LLM's default answer, lacking the skill, would at least pull from its general knowledge and acknowledge uncertainty; the stale skill confidently delivers a wrong number. Skills must be kept current; the update-skill admin flow exists for exactly this reason.

If you cannot commit to keeping your skill current as the underlying domain changes, do not share it widely. Pick a stable topic (algorithms, structural rules, evergreen patterns) instead of a time-sensitive one (rates, prices, current product offerings). Or keep the skill personal and update it whenever you notice the world has moved on.

When to ship a skill vs an MCP server

A final framing: if your "skill" is really "tell the LLM how to call this API and parse this response," do not write a skill. Write an MCP server. MCP servers handle live state better, are easier to keep current, and pair naturally with skills that handle decision-making.

A clean division:

• Skill: how to interpret the response from an MCP server. What to do with the data. The decision rules.
• MCP server: how to fetch the data. The API contract. The current state.

When both are needed, ship the MCP separately and have the skill recommend installing it.

Where to find example skills to learn from

The fastest way to internalize good SKILL.md patterns is to read a handful of skills that other developers have published. Some public catalogs let you browse skills by install count, which is a rough proxy for "this skill is well-designed enough that people actually use it."

If you have access to the skills-il catalog (https://agentskills.co.il/skills?sort=installs), three starter exemplars by complexity:

• Smallest: israeli-phone-formatter (a tight, focused formatter)
• Small with scripts/: israeli-id-validator (adds a deterministic check-digit algorithm)
• Medium with references/: hebrew-seo-geo-toolkit (bilingual + multi-section + real references/ usage)

Read three skills from start to finish before you write yours. The pattern emerges quickly. Then write yours and ship it: install it locally, share it with one person, see what they say, iterate.