AI Agent Skills

Persian Tools ships a set of 28 Agent Skill cards — one per public utility — under /skills in the repository. When you load them into an AI coding assistant (Claude Code, Cursor, Copilot, etc.), the retriever pulls the relevant SKILL.md on demand so the agent answers with the real function names, types, edge cases, and pitfalls — not invented APIs.

If you’ve ever asked an AI agent for extractCardNumbers(...) and gotten back a confidently wrong signature for a function that’s actually named extractCardNumber (singular), this is the fix.

Why Skills?

Real signatures

Each SKILL.md is generated from the actual src/modules/<name>/ exports. No hallucinated parameters or non-existent helpers.

Edge cases documented

Empty input, mixed Persian/Arabic digits, ZWNJ handling, return-type unions — captured per skill so the agent doesn’t have to guess.

Composition recipes

Cross-references between skills (e.g. extractCardNumbers → verifyCardNumber → digits) so the agent assembles working pipelines.

Tree-shake friendly

Each skill names its single import (import { Bill } from "@persian-tools/persian-tools") so the agent produces tree-shakable code by default.

Install into your agent

bunx skills add @persian-tools/persian-tools

While the public skills registry CLI is being finalised, copy the skills/ folder into your project’s .claude/skills/ (or your agent’s equivalent) directly — the on-disk format is final.

What every SKILL.md contains

Each card follows the Claude Code Skills front-matter spec:

---
name: <kebab-case-name>
description: <when to load — used by the retriever>
license: MIT
metadata:
  author: Ali Torki
  homepage: https://github.com/persian-tools/persian-tools
  version: "1.0.0"
---

The body always includes:

Import signature — exact import { … } from "@persian-tools/persian-tools" plus the CommonJS equivalent.
Public exports — function/class signatures pulled directly from src/modules/<name>/.
Behaviour rules — input shapes, return-type unions, what triggers throws.
Edge cases — empty input, mixed-digit, Arabic-keyboard, ZWNJ-laden inputs.
Common pitfalls — drift between popular community docs and current code; “this function doesn’t exist” warnings.
Composition recipes — typical pipelines combining 2–3 utilities.
References — tests and related skills.

The 28 skills, grouped by domain

🔢 Numbers & digits

Skill	What it covers
`digits`	Persian (۰-۹) ↔ Arabic-Indic (٠-٩) ↔ English digit conversion + `autoConvertDigitsToEN`
`commas`	Thousands-separator add/remove (`addCommas`, `removeCommas`)
`numberToWords`	Number → Persian words, with ordinal mode
`wordsToNumber`	Persian words → number, fuzzy mode, digit-system output
`moneyWordsToNumber`	Money phrase → number with toman/rial detection, formal vs colloquial
`addOrdinalSuffix`	Append Persian ordinal suffix (`سه` → `سوم`)
`removeOrdinalSuffix`	Strip Persian ordinal suffix (`سوم` → `سه`)

📝 Text processing

Skill	What it covers
`isPersian`	Persian-script detection + `autoArabicToPersian`
`isArabic`	Arabic-script detection and Persian-vs-Arabic distinction
`toPersianChars`	Normalize Arabic-script chars (`ي`/`ك`) to Persian (`ی`/`ک`) with template preservation
`halfSpace`	Insert ZWNJ (نیم‌فاصله) between Persian prefixes/suffixes/compounds
`URLfix`	Decode percent-encoded Persian URLs (function is `urlFix`, note camelCase)
`slugify`	URL-safe slugs from Persian text (`slugify`, `createSlug`, `slugifyWithNumbers`, `slugifySimple`)
`textAnalyzer`	Full Persian text analysis — function is `analyzeText` (NOT `textAnalyzer`) + helpers

🏛️ Iranian identifier validation

Skill	What it covers
`nationalId`	National ID (کد ملی) verify + generate + city-prefix lookup
`getPlaceByIranNationalId`	City/province lookup from the leading 3 digits of a National ID
`legalId`	Legal ID (شناسه ملی, 11-digit company ID) validation
`phoneNumber`	Mobile number validate / normalize (`+98` ↔ `0`) / operator detail

💳 Banking

Skill	What it covers
`verifyCardNumber`	Iranian card-number validation (Luhn + BIN whitelist)
`getBankNameFromCardNumber`	Issuing bank from card BIN
`extractCardNumbers`	Pull card numbers from free-text — function is `extractCardNumber` (singular)
`sheba`	Sheba/IBAN validation + bank info — function is `isShebaValid` (not `verifySheba`)
`bill`	Utility-bill `Bill` class — parse bill ID + payment ID + barcode

🌍 Geography & vehicles

Skill	What it covers
`findCapitalByProvince`	Province name → capital city
`findProvinceFromCoordinate`	(longitude, latitude) → `{ fa, en }` province
`numberplate`	Iranian license plate parser (cars + motorcycles) — use `getNumberPlateInfo`

⏱️ Time

Skill	What it covers
`timeAgo`	Jalali date string → “X قبل/بعد” Persian phrase
`remainingTime`	Gregorian target → structured countdown + Persian `toString()`

How retrieval composes

The skills are intentionally narrow — one per utility — and cross-reference each other rather than duplicate domain knowledge:

isPersian, isArabic, toPersianChars, halfSpace, digits
   ↓
Used by every higher-level skill (validators, parsers, formatters)
   ↓
nationalId, sheba, phoneNumber, moneyWordsToNumber, …

A typical agent retrieval flow:

User says: “validate this card number from a chat message”
Retriever picks: extractCardNumbers (primary) + verifyCardNumber + digits (digit normalization)
Agent reads the three SKILL.md files and produces a correct pipeline — for example:

import {
	autoConvertDigitsToEN,
	extractCardNumber,
	verifyCardNumber,
	getBankNameFromCardNumber,
} from "@persian-tools/persian-tools";

const text = autoConvertDigitsToEN(userMessage);
const candidates = extractCardNumber(text, { checkValidation: true });
const valid = candidates
	.filter((c) => c.isValid)
	.map((c) => ({
		number: c.pure,
		bank: getBankNameFromCardNumber(c.pure),
	}));

Maintainer-side skills

The 28 skills above are user-facing — one per public utility. For contributor-facing skills that guide adding new modules, writing tests, keeping the bundle small, or cutting a release, see the .agents/ directory:

Skill	Purpose
`persian-module-author`	New-module checklist
`persian-text-expert`	Persian language domain reference
`iranian-validation-expert`	Checksum algorithm reference
`persian-test-author`	Vitest house style
`bundle-size-guardian`	Tree-shaking + `.skip.ts` convention
`persian-tools-release`	Release flow

Adding or editing a skill

Each skill lives in skills/<module-name>/SKILL.md with valid YAML front-matter.
The description field is what the retriever matches on — include literal triggers (function names, Persian terms, common synonyms).
The import signature must match the real src/modules/<name>/ exports. If the source changes, the skill should change with it.
Cross-reference other skills by name (see the X skill) — don’t duplicate their content.
Update the skills README table.

External references

Claude Code Skills spec

The official front-matter format and retrieval semantics

skills/ on GitHub

Browse all 28 SKILL.md files

Source code

The src/modules/ directory each skill documents

npm package

@persian-tools/persian-tools

​AI Agent Skills

​Why Skills?

Real signatures

Edge cases documented

Composition recipes

Tree-shake friendly

​Install into your agent

​What every SKILL.md contains

​The 28 skills, grouped by domain

​🔢 Numbers & digits

​📝 Text processing

​🏛️ Iranian identifier validation

​💳 Banking

​🌍 Geography & vehicles

​⏱️ Time

​How retrieval composes

​Maintainer-side skills

​Adding or editing a skill

​External references

Claude Code Skills spec

skills/ on GitHub

Source code

npm package

AI Agent Skills

Why Skills?

Install into your agent

What every SKILL.md contains

The 28 skills, grouped by domain

🔢 Numbers & digits

📝 Text processing

🏛️ Iranian identifier validation

💳 Banking

🌍 Geography & vehicles

⏱️ Time

How retrieval composes

Maintainer-side skills

Adding or editing a skill

External references