quran

name	quran
description	Query the Holy Quran — fetch verses, chapters, juz, and translations. Use when the user asks about Quran verses, surahs, chapters, juz, Arabic text, or translations (English, Urdu, Hindi).
allowed-tools	["Bash","Read"]

Quran Skill

Interface to the Holy Quran via the local quran npm module (Node.js + SQLite).

What It Does

• Fetch Arabic text and translations (en, ur, hi)
• Query by chapter (surah), verse (ayah), juz, or search text
• Supports single verses, verse ranges, arrays of verses, and full chapters

Install

If this skill is not yet linked, run from the repo root:

ln -s "$(pwd)/.claude/skills/quran" ~/.claude/skills/quran

Or install via the helper:

gh install skill  # symlinks .claude/skills/quran → ~/.claude/skills/quran

API Reference

var quran = require('../../..');

The module root is three levels above this skill directory (../../..).

quran.get(chapter, [verse], callback)

Fetch Arabic text only. Callback receives (err, verses) where verses is an array of Arabic strings.

// Single verse
quran.get(2, 1, (err, v) => console.log(v[0]));
// → "الٓمٓ"

// Full chapter
quran.get(1, (err, verses) => console.log(verses.join('\n')));

quran.select(filters, [options], callback)

Advanced query. Callback receives (err, verses) where each verse is an object: { chapter, verse, ar, [lang...] }.

// Verses 2–4 of chapter 1 with English translation
quran.select({ chapter: 1 }, { offset: 1, limit: 3, language: 'en' }, (err, verses) => {
  verses.forEach(v => console.log(`${v.verse}: ${v.ar} — ${v.en}`));
});

// Specific verses by array
quran.select({ chapter: 1, verse: [2, 4, 6] }, (err, verses) => {
  console.log(verses);
});

Filters: { chapter, verse } — verse can be a number or array of numbers.

Options:

• offset — skip N verses
• limit — return N verses
• language — translation code ('en', 'ur', 'hi') or array of codes
• debug — print generated SQL

quran.chapter([chapterNum], callback)

Get chapter metadata. Without chapterNum, returns all 114 chapters.

quran.chapter(1, (err, info) => console.log(info));
// → [{ id: 1, name: 'Al-Faatiha', ... }]

quran.juz([juzNum], callback)

Get juz (para) boundaries. juzNum must be 1–30.

quran.juz(1, (err, juz) => console.log(juz));
// → [{ id: 1, chapter: 1, verse: 1, ... }]

quran.search(lang, text, callback)

Search translations for text (LIKE match).

quran.search('en', 'mercy', (err, results) => console.log(results));
// → [{ chapter: 1, verse: 1, en: 'In the name of Allah...' }, ...]

Supported Languages

The SQLite database ships with:

• ar — Arabic (Uthmani script, default)
• en — English (Sahih International)
• ur — Urdu
• hi — Hindi

To check available translation tables at runtime:

quran.safe(() => console.log(quran.langs));

Usage Patterns

Task	Method
Read a single verse	quran.get(chapter, verse, cb)
Read a full chapter	quran.get(chapter, cb)
Read with translation	quran.select({chapter}, {language: 'en'}, cb)
Read a range	quran.select({chapter}, {offset: 0, limit: 5}, cb)
Search a word	quran.search('en', 'word', cb)
Chapter info	quran.chapter(num, cb)
Juz boundaries	quran.juz(num, cb)

Running in Claude

All examples below run from the skill directory (.claude/skills/quran). The module is resolved via ../../.. (repo root).

node -e "var q=require('../../..'); q.get(1,1,(e,v)=>console.log(v[0]))"

Or write temporary scripts to /tmp and run them.

Examples

User: "What is the first verse of Surah Al-Baqarah?"

node -e "var q=require('../../..'); q.get(2,1,(e,v)=>console.log(v[0]))"

User: "Show me the English translation of Surah Fatiha"

node -e "var q=require('../../..'); q.select({chapter:1},{language:'en'},(e,v)=>v.forEach(x=>console.log(x.verse+'. '+x.en)))"

User: "Search for verses about mercy"

node -e "var q=require('../../..'); q.search('en','mercy',(e,r)=>r.slice(0,5).forEach(v=>console.log(v.chapter+':'+v.verse+' '+v.en)))"