Skills-IL Skill Creator

This skill walks you through creating a production-quality skill for the skills-il organization. It follows Anthropic's Complete Guide to Building Skills and enforces all skills-il conventions.

Every skill you create will include: SKILL.md with validated frontmatter, bilingual metadata (Hebrew + English), step-by-step instructions with tables and code examples, a Hebrew companion file (SKILL_HE.md), and pass all validation checks.

Step 1: Choose Category Repository

Ask the user which category repo this skill belongs to:

If the skill doesn't fit any category, discuss with the user whether it belongs in an existing category or warrants a new repo.

Step 2: Define Use Cases

CRITICAL: Before writing any code, identify 2-3 concrete use cases.

For each use case, capture:

• Trigger: What the user would say (in English AND Hebrew transliteration)
• Steps: What multi-step workflow this requires
• Tools: Which tools are needed (built-in or MCP)
• Result: What success looks like

Example format:

Use Case: Validate Israeli e-invoice
Trigger: User says "validate hashbonit electronit" or "check SHAAM allocation"
Steps:
1. Parse invoice fields
2. Validate allocation number format
3. Check against SHAAM rules
Result: Invoice validated with pass/fail report

Ask the user to describe their skill idea, then help them extract 2-3 use cases from it. Include Hebrew transliterations for all domain terms (e.g., "payroll" = "tlush maskoret", "invoice" = "hashbonit").

Step 3: Scaffold the Folder

Run the scaffolding script to create the skill folder structure:

python scripts/scaffold-skill.py --name <skill-name> --category <category-repo>

The script creates:

<skill-name>/
├── SKILL.md          # Template with frontmatter skeleton
├── SKILL_HE.md       # Hebrew companion stub
├── scripts/          # For helper scripts
└── references/       # For reference documentation

Verify the output:

• Folder name is kebab-case
• No spaces, underscores, or capitals
• Name does not contain "claude" or "anthropic"
• No README.md inside the folder

Step 4: Write the YAML Frontmatter

Generate the frontmatter following this exact structure:

---
name: <skill-name>
description: >-
  [What it does -- one sentence]. Use when user asks to [triggers in English],
  "[Hebrew transliteration 1]", "[Hebrew transliteration 2]", or [more triggers].
  [Key capabilities]. Do NOT use for [anti-triggers] (use [alternative-skill] instead).
license: MIT
allowed-tools: '<tools if needed>'
compatibility: >-
  [Network/system requirements]. Works with Claude Code, Claude.ai, Cursor.
metadata:
  author: skills-il
  version: 1.0.0
  category: <category-repo>
  tags:
    - <tag1>
    - <tag2>
    - israel
  display_name:
    he: "<Hebrew display name>"
    en: <English Display Name>
  display_description:
    he: "<Hebrew description>"
    en: >-
      <English description -- mirrors the main description field>
---

Description rules (CRITICAL):

• Must follow pattern: [What it does] + [When to use it] + [Key capabilities] + [Do NOT use for X]
• Under 1024 characters total
• No XML angle brackets (< >) anywhere in frontmatter
• Include trigger phrases users would actually say
• Include Hebrew transliterations in quotes (e.g., "tlush maskoret")
• End with Do NOT use for boundary + cross-reference to related skills

Allowed-tools patterns:

• No tools needed: omit the field
• Python scripts: 'Bash(python:*)'
• Python + web: 'Bash(python:*) WebFetch'
• Multiple CLI tools: 'Bash(python:*) Bash(curl:*) WebFetch'
• pip installs: 'Bash(python:*) Bash(pip:*)'

Step 5: Write the Instructions Body

Write the SKILL.md body using this structure:

# <Skill Display Name>

Step 1:

<Clear explanation with tables, code examples>

Step N:

...

Example 1:

User says: "" Actions:

1. ... Result: ...

Scripts

• scripts/<name>.py -- <What it does, how to run>. Run: python scripts/<name>.py --help

References

• references/<name>.md -- . Consult when .

Error: ""

Cause: Solution:

**Best practices from the Complete Guide:**
- Be specific and actionable: "Run `python scripts/validate.py --input {filename}`" not "Validate the data"
- Use tables for decision matrices, field mappings, comparison data
- Include inline code for algorithms and API calls
- Keep SKILL.md under 5,000 words -- move detailed docs to `references/`
- Reference bundled resources with "Consult when..." guidance
- Include 2-4 examples covering common and edge cases
- Include 2-4 troubleshooting entries for likely errors
- Embed Hebrew terminology inline: "installments (tashlumim)"

**Progressive disclosure:**
- SKILL.md = core instructions (what the agent needs most of the time)
- `references/` = detailed specs, full API docs, edge cases (loaded on demand)
- `scripts/` = executable helpers (run when needed)

### Step 6: Create the Hebrew Companion (SKILL_HE.md)

Create SKILL_HE.md with the same structure but in Hebrew:
- Translate the body instructions to Hebrew
- Keep code blocks, field names, and API references in English
- Use Hebrew-native terminology (not transliterations)
- Maintain the same step numbering and section structure

The Hebrew file uses the same frontmatter as SKILL.md (frontmatter stays in English).

### Step 7: Validate and Prepare for PR

Run the validation script:

```bash
./scripts/validate-skill.sh <skill-name>/SKILL.md

The script checks 9 rules:

After validation passes, review against the quality checklist:

• Description includes WHAT and WHEN
• Instructions are specific and actionable
• Examples cover 2+ real scenarios
• Troubleshooting covers likely errors
• Hebrew companion exists and is consistent
• References are linked with "Consult when..." guidance
• No security issues (secrets, injection vectors)

Example 1: Create a Government Services Skill

User says: "I want to create a skill for querying Israeli court decisions"

Actions:

1. Category: government-services
2. Use cases: search by case number, search by judge name, search by topic (Hebrew legal terms)
3. Scaffold: python scripts/scaffold-skill.py --name israeli-court-decisions --category government-services
4. Frontmatter: name=israeli-court-decisions, triggers include "psakei din", "beit mishpat", "nevo"
5. Instructions: Steps for search types, result parsing, citation format
6. Hebrew: SKILL_HE.md with native legal terminology
7. Validate: ./scripts/validate-skill.sh israeli-court-decisions/SKILL.md

Result: Complete skill ready for PR to government-services repo.

Example 2: Create a Developer Tool Skill

User says: "I need a skill that helps format Israeli addresses"

Actions:

1. Category: developer-tools (or government-services for address lookup APIs)
2. Use cases: format for postal mail, validate mikud, normalize city names
3. Scaffold: python scripts/scaffold-skill.py --name israeli-address-formatter --category developer-tools
4. Frontmatter: triggers include "format ktovet", "mikud", "address normalization"
5. Instructions: Format rules, mikud lookup, bilingual city names
6. Hebrew: SKILL_HE.md
7. Validate: passes all checks

Result: Address formatting skill with validation and postal format support.

Example 3: Create a Skill with MCP Integration

User says: "I want to create a skill that uses the israeli-bank-mcp server"

Actions:

1. Category: tax-and-finance
2. Use cases: categorize transactions, detect recurring charges, monthly summary
3. Scaffold: python scripts/scaffold-skill.py --name israeli-bank-analyzer --category tax-and-finance
4. Frontmatter: add mcp-server: israeli-bank-mcp to metadata, triggers include "nituch tenuot bank"
5. Instructions: MCP tool calls for fetching transactions, categorization logic, summary generation
6. Hebrew: SKILL_HE.md with banking terminology
7. Validate: passes all checks

Result: MCP-enhanced skill that adds workflow intelligence on top of bank data access.

Scripts

• scripts/scaffold-skill.py -- Creates the complete folder structure for a new skills-il skill: SKILL.md template with frontmatter skeleton, SKILL_HE.md stub, scripts/ and references/ directories. Validates name format and prevents overwrites. Run: python scripts/scaffold-skill.py --help

References

• references/skill-spec.md -- Complete skills-il SKILL.md specification including all frontmatter fields (required and optional), description-writing formula with good/bad examples, the 5 skill patterns from Anthropic's guide, quality checklist, and validation rules. Consult when writing frontmatter or instructions and you need detailed guidance beyond the steps above.

Error: "Validation fails on description"

Cause: Description missing trigger phrase or over 1024 characters Solution: Ensure description includes one of: "Use when", "Use for", "Use if", "When user", "When the user". Check length is under 1024 chars. Remove any <> angle brackets.

Error: "Name doesn't match folder"

Cause: SKILL.md name field differs from the folder name Solution: The name field must exactly match the folder name. Both must be kebab-case. Run: ls -la to check folder name, compare with name: in frontmatter.

Error: "Body exceeds 5,000 words"

Cause: Too much detail in SKILL.md Solution: Move detailed documentation to references/ files. Keep SKILL.md focused on core instructions. Link to references with "Consult references/filename.md for..." guidance.

Error: "Scaffold script fails"

Cause: Folder already exists or invalid name format Solution: Check if the skill folder already exists. Ensure name is kebab-case only (lowercase letters, numbers, hyphens). No spaces, underscores, or capitals.