Writing Your First Agent Skill

What you'll learn

• ✓Understand what a skill really is to the LLM at routing time, and when to pick a skill vs MCP / system prompt / CLI
• ✓Write a SKILL.md with a description the LLM routes correctly (Use when / Do NOT use for patterns)
• ✓Distinguish metadata.json from YAML frontmatter and understand why skills-il uses a separate file
• ✓Decide between references/ and scripts/ for any supporting content
• ✓Ship a skill end-to-end through the pipeline: scaffold, push, sync, trust score, publication
• ✓Run the 10-minute pre-publish checklist and pass the 10 most common rejection reasons

Who this is for

Developers who know git, Markdown, and JSON, and want to write a Claude agent skill for the skills-il catalog. No prior Claude Skills experience required.

1. 1.

   What is a skill, really?

   A skill is the simplest way to teach an AI assistant to handle a specific task: a single Markdown file with YAML frontmatter at the top, optionally accompanied by reference files and executable scripts. The agent reads the file on demand when the description matches the user's request. That is the entire model. Everything else (catalog, sync pipeline, trust score, install counts) is infrastructure around that one file.

   ~4 min
2. 2.

   Anatomy of a great SKILL.md

   A great SKILL.md does three things at once: it tells the LLM when to load itself (the description), it teaches the LLM how to perform the task (the body), and it gives the LLM enough examples to handle edge cases without escalating to the user. If any of these three are missing, the skill either does not get loaded (description failure), does the wrong thing (body failure), or asks the user too many clarifying questions (examples failure).

   ~4 min
3. 3.

   Extending the spec (metadata.json + bilingual content)

   The skill format (the spec developed by Anthropic, accepted by Claude Code, Cursor, Windsurf, and Claude Desktop) is intentionally minimal: `SKILL.md` with three frontmatter fields, plus the optional `references/` and `scripts/` subfolders. That is enough for a personal skill or a skill you share by zipping a folder and sending it to a colleague. But if you want to put your skill in a catalog, support multiple languages, or expose extra metadata to consumers, you need to extend the spec.

   ~4 min
4. 4.

   references/ vs scripts/ (when to use which)

   A skill folder can include two optional subfolders: `references/` and `scripts/`. They serve different purposes and choosing the wrong one is a frequent rejection reason. The rule is simple: `references/` for static content the LLM reads, `scripts/` for executable code the LLM runs. The hard part is recognizing which side of the line your content falls on.

   ~4 min
5. 5.

   Sharing your skill

   You have written SKILL.md, optionally added references/ and scripts/, and the skill works. Now the practical question: how do you actually use it, share it with others, or publish it to a catalog? This chapter covers four scenarios in order of effort.

   ~3 min
6. 6.

   The 10-minute pre-share checklist

   This chapter is short on purpose. It is the checklist you run BEFORE sharing your skill with anyone (a colleague, a public catalog, or your future self after a long break). Ten minutes spent here saves multiple back-and-forth rounds with reviewers and prevents the most common authoring mistakes.

   ~5 min

Skills to install to act on what you've learned

Skills-IL Skill Creator

Verified·93

Author: skills-il

v1.3.0PopularTrending

Interactive workflow for creating new skills for the skills-il organization -- guides through category selection, use case definition, folder scaffolding, YAML frontmatter generation with bilingual metadata, instruction writing, Hebrew companion creation, and validation. Use when user asks to "create a new skill", "scaffold a skill for skills-il", "write a SKILL.md", "contribute a skill", "new skill template", or "liztor skill chadash". Do NOT use for editing existing skills or creating skills for non-skills-il platforms.

Ask the Skill

0.01372,271

2

Claude CodeCursorGitHub Copilot+5

Israeli Id Validator

Verified·100

Author: skills-il

v1.0.1Popular

Validate and format Israeli identification numbers including Teudat Zehut (personal ID), company numbers, amuta (non-profit) numbers, and partnership numbers. Use when user asks to validate Israeli ID, "teudat zehut", "mispar zehut", company number validation, or needs to implement Israeli ID validation in code. Includes check digit algorithm and test ID generation. Do NOT use for non-Israeli identification systems.

Ask the Skill

0.01231,323

1

Claude CodeCursorGitHub Copilot+6

Hebrew SEO & GEO Toolkit

Trusted·80

Author: skills-il

v2.0.2PopularTrending

Optimize websites for Hebrew SEO and GEO (Generative Engine Optimization) on Google.co.il and AI search engines (ChatGPT, Perplexity, Gemini, Copilot, Claude). Use when user asks about Hebrew keyword research, Israeli SEO, .co.il domain optimization, Hebrew schema.org markup, AI search visibility, GEO optimization, EEAT, or asks about "kidum atarim", "milot mafteach", "SEO", "GEO", or Israeli search ranking. Includes Hebrew morphological analysis, Princeton GEO methods, platform-specific AI optimization, EEAT principles, JSON-LD structured data, and Israeli business schema (Shabbat hours, kosher certification). Do NOT use for paid advertising campaigns or social media marketing.

Ask the Skill

0.02201,250

2

Claude CodeCursorGitHub Copilot+5

Israeli Phone Formatter

Verified·100

Author: skills-il

v1.0.1PopularTrending

Validate, format, and convert Israeli phone numbers between local and international (+972) formats. Use when user asks to validate Israeli phone number, format phone for SMS, convert to +972, check phone prefix, or implement Israeli phone input validation in code. Handles mobile (050-058), landline (02-09), VoIP (072-077), toll-free (1-800), and star-service numbers. Do NOT use for non-Israeli phone systems or general telecom questions.

Ask the Skill

0.0991,227

0

Claude CodeCursorGitHub Copilot+6

What's new

• 1.0.0
  Initial release. Six chapters covering how to write a first agent skill: the mental model (skill vs MCP / system prompt / CLI), SKILL.md anatomy, the skills-il extension (metadata.json + SKILL_HE.md), references/ vs scripts/, the publication flow, and a 10-minute pre-publish checklist. Catalog exemplars referenced: israeli-id-validator, israeli-phone-formatter, hebrew-seo-geo-toolkit.(24-05-2026)