Build a skill

A Localskills.ai skill is a folder. Six files, one of which is the actual instructions for the AI agent. There's no SDK, no hosted runtime. If you can write Markdown, you can publish a skill.

Folder layout

your-skill/
  skill.json        # manifest — required, validated
  README.md         # human-facing docs — required
  SKILL.md          # the prompt the agent runs — required
  LICENSE           # OSI-approved licence — required
  CHANGELOG.md      # version history — required
  examples/         # at least 3 example input/output pairs (strongly recommended)
  tests/            # required for skills that execute code
  assets/           # icons, screenshots — optional

Manifest schema (skill.json)

The manifest is the source of truth for routing, search, and permissions display. Every field is validated on submission. See the full schema reference.

{
  "name": "woolworths-refund-helper",
  "displayName": "Woolworths Refund Helper",
  "version": "1.0.0",
  "description": "Auto-process refund requests for poor quality Woolworths NZ deliveries.",
  "creator": {
    "username": "paulgnz",
    "displayName": "Paul Grey",
    "url": "https://secondbrain.nz"
  },
  "license": "MIT",
  "regions": ["nz"],
  "categories": ["retail"],
  "tags": ["woolworths", "refund", "grocery"],
  "compatibility": { "claude-code": ">=1.0.0" },
  "permissions": {
    "fileSystem": [],
    "network": ["www.woolworths.co.nz"],
    "shell": false
  },
  "pricing": { "model": "free", "price": 0 },
  "safetyLevel": "low"
}

Regions

Use lowercase ISO 3166-1 alpha-2 codes — nz, au, us, de, jp. For sub-region scope, use ISO 3166-2 codes — nz-akl, us-ca, au-nsw. Use ["global"] for non-regional skills.

Permissions

Permissions are the single most important thing about your skill. Be precise. Declare:

• network — exact hosts your skill contacts. Wildcards discouraged.
• fileSystem — scopes like read:downloads, write:outputs. Be specific.
• shell — false if not needed (preferred), otherwise an array of commands.

Over-declaring is rejected. Skills that ask for more than they need get bounced to revisions.

Submission

1. Fork localskills-ai/skills on GitHub.
2. Add your skill folder under /<region>/<your-slug>/.
3. Run npm run validate locally — must pass before PR.
4. Open a pull request with a short summary, who it's for, and a worked example.
5. Automated review runs immediately. Human review follows. Typical turnaround:
   • low safety, AI score 8+ → 24 hours
   • medium → 72 hours
   • high → 7 days, includes sandbox test

Validation pipeline (run locally)

# From the skills/ repo root
node scripts/validate.mjs path/to/your-skill

# or, to validate everything:
node scripts/validate.mjs --all

The validator runs schema validation, file-presence checks, license sanity, prompt-injection scan, and a regex pass for obvious malicious patterns. If it fails locally, it fails in CI.

What gets you rejected fastest

• Undisclosed third-party network calls
• Hardcoded API keys or credentials
• SKILL.md that tells the agent to ignore the user
• Permissions wider than the skill needs
• Misleading description vs implementation
• Scraping services with anti-scraping policies in their ToS

Read the full moderation policy before submitting.