تبدیل کتاب فنی به مهارت برای عامل‌های هوش مصنوعی

تبدیل یک کتاب فنی به مهارت عامل (agent skill): دستاورد شما

برای تبدیل یک کتاب فنی به مهارت عامل، کافی است یک مبدل را به سمت یک فایل PDF، EPUB، خروجی DOCX یا پوشه‌ای از اسناد داخلی که در اختیار دارید، هدایت کنید. این ابزار یک دایرکتوری مهارت ایجاد می‌کند: یک فایل ورودی که شامل چارچوب‌های نام‌گذاری‌شده به همراه فهرست فصل‌هاست، و به ازای هر فصل یک فایل مجزا که عامل تنها زمانی که پرسش شما آن را ایجاب کند، آن را می‌خواند. کتاب هرگز وارد context window نمی‌شود، اما فهرست آن وارد می‌شود.

این کار دقیقاً نقطه مقابل نوشتن یک مهارت عامل از صفر است؛ جایی که شما رویه‌ای را که از قبل می‌دانید، کدنویسی می‌کنید. در اینجا دانش از قبل وجود دارد اما کسی به آن دسترسی ندارد: مانند یک فایل PDF فروشنده با 800 صفحه، یا کتابچه‌ای که از زمان خروج نویسنده‌اش دیگر باز نشده است. کار اصلی در اینجا فشرده‌سازی و نمایه‌سازی (indexing) است. اگر واژه مهارت برای شما جدید است، ابتدا ماهیت واقعی یک مهارت عامل را مطالعه کنید.

مبدل مورد استفاده در اینجا book-to-skill است؛ یک مهارت با مجوز MIT که روی دستگاه خودتان اجرا می‌شود. تگ فعلی در اوت 2026 برابر با v1.4.0 است. ساختاری که این ابزار تولید می‌کند از خود ابزار اهمیت بیشتری دارد و بخش پایانی پیش از FAQ نشان می‌دهد که چگونه می‌توان همین ساختار را به‌صورت دستی ایجاد کرد.

چرا بودجه توکن، کل طراحی را تعیین می‌کند

کتابی که در پنجره کانتکست (context window) قرار می‌گیرد، در هر مکالمه‌ای که به آن نیاز داشته باشد، هزینه کامل حجم خود را تحمیل می‌کند. اما یک مهارت (skill)، تنها یک‌بار هزینه فایل ورودی خود را می‌پردازد، به‌علاوه هر فصلی که پرسش واقعاً به آن ارجاع می‌دهد. اسناد پروژه برای هر فایلی که تولید می‌کند، یک بودجه مشخص در نظر گرفته‌اند.

[
  {
    "label": "SKILL.md entry file",
    "tokens": "4,000"
  },
  {
    "label": "One chapter file",
    "tokens": "1,000"
  },
  {
    "label": "glossary.md",
    "tokens": "1,500"
  },
  {
    "label": "patterns.md",
    "tokens": "2,000"
  },
  {
    "label": "cheatsheet.md",
    "tokens": "1,000"
  }
]

فایل ورودی، یعنی SKILL.md، محدود به 4,000 توکن است و شامل چارچوب‌های نام‌گذاری‌شده و فهرست فصل‌ها می‌باشد. هر فایل فصل حدود 1,000 توکن حجم دارد و تا زمانی که درخواستی برای آن ارسال نشود، روی دیسک باقی می‌ماند. فایل‌های پشتیبان نیز مشابه هستند: 1,500 توکن برای glossary.md، 2,000 برای patterns.md و 1,000 برای cheatsheet.md.

این بودجه‌بندی‌ها با نحوه مصرف واقعی کانتکست توسط Claude Code همخوانی دارد. فایل description یک مهارت در فهرست مهارت‌ها قرار می‌گیرد تا مدل از وجود آن مطلع شود. بدنه اصلی مهارت هنگام فراخوانی بارگذاری می‌شود و پس از بارگذاری، تا پایان نشست در کانتکست باقی می‌ماند؛ بنابراین هر خط در فایل ورودی، یک هزینه تکرارشونده است. فایل‌های پشتیبان تنها زمانی بارگذاری می‌شوند که عامل (agent) آن‌ها را بخواند، و همین موضوع باعث می‌شود فایل‌های مربوط به هر فصل کم‌هزینه باشند.

یک محدودیت سخت‌تر در پسِ عدد فایل ورودی وجود دارد. هنگامی که فشرده‌سازی خودکار (auto-compaction) یک مکالمه طولانی را خلاصه می‌کند، Claude Code آخرین فراخوانی هر مهارت را پس از خلاصه دوباره ضمیمه می‌کند و 5000 توکن اول هر کدام را در یک بودجه ترکیبی 25000 توکنی برای تمام مهارت‌های باز-ضمیمه‌شده حفظ می‌کند. فایل ورودی که در 5000 توکن جای بگیرد، پس از فشرده‌سازی به‌طور کامل باقی می‌ماند. اما یک فایل ورودی 20000 توکنی، تنها با یک‌چهارم ابتدایی خود بازمی‌گردد و هیچ‌چیز به شما نمی‌گوید که کدام سه-چهارم دیگر حذف شده است.

این همان افشای تدریجی (progressive disclosure) است: یک فهرست کوچک که همیشه ارزش هزینه خود را دارد، و بخش عمده مطالب پشت دری قرار دارد که عامل به‌صورت هدفمند آن را باز می‌کند. نحوه مدیریت پنجره کانتکست توسط Claude Code باقی این محاسبات را پوشش می‌دهد.

نصب مبدل روی VPS، با قفل‌کردن روی یک نسخه مشخص

این مهارت یک مخزن git است. آن را در دایرکتوری skills مربوط به agent مورد استفاده خود clone کنید. نام دایرکتوری به دستور slash تبدیل می‌شود، بنابراین مسیر clone سلیقه‌ای نیست.

git clone --depth 1 --branch v1.4.0 \
  https://github.com/virgiliojr94/book-to-skill.git \
  ~/.claude/skills/book-to-skill

--branch یک تگ را می‌پذیرد، بنابراین این دستور نسخه v1.4.0 و نه هیچ نسخه جدیدتری را دریافت می‌کند. آن را قفل کنید، زیرا مهارت مجموعه‌ای از دستورالعمل‌هاست که agent شما از آن‌ها پیروی می‌کند و تغییر بررسی‌نشده در این دستورالعمل‌ها، به معنای تغییر در چیزی است که روی سرور شما اجرا می‌شود. GitHub Copilot CLI به جای آن ~/.copilot/skills/ را می‌خواند و Amp از ~/.agents/skills/ استفاده می‌کند.

یک روش نصب تک‌خطی نیز وجود دارد، npx skills add virgiliojr94/book-to-skill، که آخرین نسخه موجود را دریافت می‌کند. از آن برای تست ابزار استفاده کنید. برای هر چیزی که مجدداً اجرا می‌کنید، از clone قفل‌شده استفاده کنید.

اکنون بررسی کنید که سرور چه extractorsهایی دارد:

cd ~/.claude/skills/book-to-skill
python3 scripts/extract.py --check

--check گزارش می‌دهد که کدام extractorsها نصب شده‌اند و دستور نصب را برای هر کدام که موجود نیست، چاپ می‌کند. این بسته به Python 3.9 یا جدیدتر نیاز دارد.

اگر /book-to-skill پس از clone کردن در تکمیل خودکار (autocomplete) ظاهر نشد، agent خود را restart کنید. Claude Code دایرکتوری‌های مهارتی را که هنگام شروع session وجود داشته‌اند نظارت می‌کند، بنابراین ~/.claude/skills/ که دو دقیقه پیش ایجاد کرده‌اید، هنوز تحت نظارت نیست.

واقعاً به کدام استخراج‌کننده‌ها نیاز دارید؟

هیچ‌چیز فراتر از Python الزامی نیست، زیرا هر فرمت یک جایگزین در کتابخانه استاندارد دارد. البته این جایگزین‌ها کارایی کمتری دارند و در یک سرور کوچک، نصب استخراج‌کننده‌های بلااستفاده فقط باعث هدررفت منابع می‌شود.

• pdftotext از بسته poppler-utils، فایل‌های PDF با متن زیاد را مدیریت می‌کند و سرعت آن تقریباً آنی است. آن را با sudo apt install poppler-utils نصب کنید.
• pypdf و pdfminer.six جایگزین‌های Python برای PDF هستند.
• docling برای PDFهای فنی که ارزش آن‌ها در جداول و لیست‌های کد است، استفاده می‌شود. این پروژه زمان پردازش آن را حدود 1.5 ثانیه برای هر صفحه اندازه‌گیری کرده است.
• ebooklib به همراه beautifulsoup4 فایل‌های EPUB را به‌درستی می‌خواند. بدون آن‌ها، ابزار به خواننده zipfile در کتابخانه استاندارد متوسل می‌شود.
• python-docx فایل‌های DOCX و striprtf فایل‌های RTF را می‌خواند.
• ابزار ebook-convert از Calibre برای فایل‌های MOBI و AZW الزامی است.
• ocrmypdf عملیات OCR (تشخیص نوری کاراکتر) را روی کتاب‌های اسکن‌شده‌ای که هیچ لایه متنی ندارند، انجام می‌دهد.

در Ubuntu 24.04، یک دستور ساده pip3 install pypdf با خطای زیر متوقف می‌شود:

error: externally-managed-environment

این به معنای خرابی pip نیست. Ubuntu و Debian پایتون سیستم را تحت مدیریت apt قرار می‌دهند، بنابراین pip از نوشتن در آن خودداری می‌کند. دو راه حل وجود دارد. sudo apt install poppler-utils یک فایل باینری نصب می‌کند و اصلاً نیازی به pip ندارد، و pdftotext به‌تنهایی اکثر PDFهای متنی را پوشش می‌دهد. برای استخراج‌کننده‌های Python، یک محیط مجازی (virtual environment) بسازید و عامل (agent) خود را از داخل آن اجرا کنید تا python3 که توسط مهارت فراخوانی می‌شود، همان مفسری باشد که بسته‌ها را در اختیار دارد.

python3 -m venv ~/.venvs/book-to-skill
source ~/.venvs/book-to-skill/bin/activate
pip install "$HOME/.claude/skills/book-to-skill[pdf,epub,docx]"
claude

این مخزن، موارد اضافی pdf، epub، docx، rtf، technical و all را اعلام می‌کند که در آن technical همان docling است. صفحه نصب پروژه همچنین pip install "book-to-skill[pdf,epub,docx]" را نشان می‌دهد، اما این نام تا اوت 2026 در PyPI منتشر نشده است، بنابراین طبق روش بالا از checkout خودتان نصب کنید.

نصب docling را تا زمانی که کتابی به آن نیاز پیدا نکرده است، به تعویق بیندازید. این بسته یک پشته یادگیری ماشین (machine learning stack) را فراخوانی می‌کند، بنابراین پیش از نصب، فضای دیسک آزاد در پلن‌های کوچک را بررسی کنید.

اجرای آن روی پوشه‌ای از اسناد، شامل حالت headless

این دستور یک فایل، یک پوشه، یک glob داخل کوتیشن یا چندین مسیر را به‌طور هم‌زمان می‌پذیرد و پس از آن نام یک skill اختیاری قرار می‌گیرد. هر چیزی که بتوانید در یک دایرکتوری قرار دهید کار می‌کند، از جمله مجموعه‌ای از RFCها (درخواست برای نظر، اسنادی که پروتکل‌های اینترنت را تعریف می‌کنند).

/book-to-skill ~/library/platform-docs/ platform-handbook
/book-to-skill "~/books/*.epub" my-library
/book-to-skill ~/papers/paper1.pdf ~/notes/export.txt unified-research

عبارت glob را داخل کوتیشن قرار دهید تا shell شما پیش از آنکه skill آن را ببیند، آن را گسترش (expand) ندهد. اشاره کردن دستور به یک دایرکتوری skill موجود، منابع جدید را به همان skill اضافه می‌کند و از ایجاد یک skill دوم جلوگیری می‌کند.

اجرای تعاملی از شما سؤالاتی می‌پرسد. آیا محتوا فنی است یا متنی سنگین؟ این موضوع تعیین‌کننده extractor است. آیا عمق مرجع می‌خواهید یا عمق مطالعه؟ این موضوع بودجه (budget) هر فصل را تعیین می‌کند. نام skill چه باشد و در کدام ریشه (root) از skillها قرار بگیرد؟ همچنین پیش از تولید محتوا، تخمینی از تعداد توکن و زمان ارائه می‌دهد و منتظر تأیید شما می‌ماند.

در اجرای headless کسی برای پاسخ به این سؤالات وجود ندارد. skillهای قابل فراخوانی توسط کاربر در claude -p کار می‌کنند: دستور slash را در رشته prompt قرار دهید تا Claude Code پیش از شروع اجرا آن را گسترش دهد. بنابراین به سؤالات در همان prompt پاسخ دهید.

claude -p "/book-to-skill ~/library/platform-docs/ platform-handbook
The sources are technical. Use reference depth. Write the skill to
~/.claude/skills/. Do not publish it to GitHub. Proceed without asking me." \
  --allowedTools "Bash,Read,Write,Edit"

--allowedTools ابزارهای مورد نیاز برای اجرا را از پیش تأیید می‌کند، زیرا یک درخواست مجوز بدون ترمینال متصل، اجرایی است که هرگز به پایان نمی‌رسد. افزودن --output-format json باعث می‌شود total_cost_usd در نتیجه ظاهر شود که یک تخمین سمت کلاینت است و نه صورت‌حساب شما.

استخراج (Extraction)، پیش از آنکه هر مدلی آن را بخواند، تمام منابع را در یک دایرکتوری کاری موقت تحت /tmp تجمیع می‌کند و آخرین مرحله اجرا، آن دایرکتوری را حذف می‌کند. منبعی که در استخراج شکست بخورد نادیده گرفته می‌شود تا عملیات دسته‌ای (batch) ادامه یابد؛ این یعنی یک اجرا ممکن است با وجود خواندن فایل‌های کمتر از آنچه ارائه داده‌اید، موفقیت‌آمیز گزارش شود. موجودی فایل‌ها در گزارش نهایی را با آنچه در پوشه است مقایسه کنید. فصل مفقود معمولاً به معنای منبع مفقود است.

اجرا را روی سروری انجام دهید که برای سپردن به یک agent راحت هستید. اجرای ایمن Claude Code روی یک VPS جنبه‌های مربوط به مجوزها را پوشش می‌دهد.

محل قرارگیری خروجی برای دسترسی عامل کدنویسی شما

مهارت تولیدشده در ریشهٔ مهارت‌ها قرار می‌گیرد. دو مورد از آن‌ها اهمیت دارند.

• ~/.claude/skills/<skill-name>/ شخصی است و در هر پروژه‌ای روی آن ماشین در دسترس است.
• .claude/skills/<skill-name>/ درون یک مخزن (repository) قرار دارد و همراه با آن جابه‌جا می‌شود.

درون هر یک از این دو، شما SKILL.md، یک دایرکتوری chapters/ با یک فایل برای هر فصل، و فایل‌های پشتیبان را دریافت می‌کنید. نام دایرکتوری همان دستور است، بنابراین ~/.claude/skills/platform-handbook/ به شما /platform-handbook می‌دهد و می‌توانید پس از آن یک موضوع یا یک پرسش ساده را مطرح کنید.

ریشه را بر اساس مجوز (licensing) انتخاب کنید، نه راحتی. مهارتی که از کتابی که خریده‌اید ساخته شده، متعلق به دایرکتوری شخصی شماست. مهارتی که از مستندات نوشته‌شده توسط تیم خودتان ساخته شده، متعلق به مخزن است، که این موضوع اشتراک‌گذاری یک مهارت بین چندین مخزن را به مسئلهٔ بعدی برای حل تبدیل می‌کند.

یک هزینه با افزودن هر مهارت افزایش می‌یابد. توضیحات هر مهارت در فهرست مهارت‌ها باقی می‌ماند تا مدل بتواند تصمیم بگیرد از آن استفاده کند؛ متن ترکیبی توضیحات در هر ورودی به 1,536 کاراکتر محدود می‌شود و کل فهرست نیز دارای یک سقف بودجه است. ده مهارت کتابی یعنی ده توضیح که برای آن فضا رقابت می‌کنند. برای مواردی که همیشه با نام فراخوانی می‌کنید، یک خط به frontmatter تولیدشده اضافه کنید:

---
name: platform-handbook
description: Frameworks and chapter index from the internal platform handbook.
disable-model-invocation: true
---

با disable-model-invocation: true، توضیحات به‌طور کامل از کانتکست خارج می‌شود و مهارت همچنان هنگام تایپ /platform-handbook به‌طور کامل بارگذاری می‌شود. شما قابلیت کشف خودکار را فدا می‌کنید و در عوض یک پنجرهٔ کانتکست خلوت‌تر خواهید داشت.

مجوزدهی: MIT شامل مبدل می‌شود، نه کتاب

در این مورد دقیق باشید، زیرا شکست در اینجا یک مسئله فنی نیست.

• مجوز MIT کد مبدل و تعریف مهارت آن را پوشش می‌دهد. این مجوز هیچ اشاره‌ای به سندی که به آن می‌دهید ندارد.
• اجرای مبدل روی کتابی که خریده‌اید، روی سخت‌افزاری که کنترل آن را در دست دارید، به معنای یادداشت‌برداری از نسخه شخصی خودتان است.
• انتشار خروجی به معنای توزیع است و مجوز MIT ابزار، هیچ حقی برای توزیع هرگونه اثر مشتق‌شده از کتاب دیگران به شما نمی‌دهد.
• خروجی یک اثر مشتق‌شده است. چارچوب‌ها و نکات کلیدی فصل‌ها همچنان توسط منبع شکل می‌گیرند و یک اثر مشتق‌شده همچنان تحت قوانین کپی‌رایت منبع اصلی قرار دارد.
• مهارتی که از مطالبی ساخته شده که اجازه بازنشر آن‌ها را ندارید، باید روی همان ماشینی باقی بماند که آن را ساخته است. نه در یک مخزن عمومی و نه در یک بازارچه تیمی مشترک.
• زمانی اقدام به انتشار کنید که منبع متعلق به خودتان باشد یا دارای مجوز آزاد باشد: مانند مستنداتی که تیم شما نوشته است یا استانداردی که شرایط آن اجازه بازنشر را می‌دهد.

این ابزار بر همین اساس ساخته شده است. هیچ محتوایی از کتاب را همراه خود عرضه نمی‌کند، استخراج به‌صورت محلی انجام می‌شود و مرحله انتشار آن، وضعیت مشاهده‌پذیری مخزن را به‌عنوان یک پرسش جداگانه می‌پرسد که فقط کلمات صریح public یا private را می‌پذیرد و هیچ‌کدام را به‌صورت پیش‌فرض استنباط نمی‌کند. آن اعلان را به‌عنوان تصمیم‌گیری در مورد مجوز در نظر بگیرید، زیرا دقیقاً همین است.

کتابچه‌های راهنمای داخلی مشکل دومی نیز دارند. آن‌ها بیش از آنچه تصور می‌شود حاوی اطلاعات حساس (credentials) هستند و یک مبدل، فایلی را که هیچ‌کس باز نمی‌کند به فایلی تبدیل می‌کند که عامل (agent) شما در صورت نیاز آن را می‌خواند. فایل‌های تولیدشده را پیش از commit کردن یک‌بار مطالعه کنید و به دور نگه داشتن اسرار از عامل‌های هوش مصنوعی مراجعه کنید.

هزینه هر تبدیل چقدر است؟

اعداد زیر، اندازه‌گیری‌های منتشرشده توسط خود پروژه هستند و نه ما.

[
  {
    "label": "Think Python 2",
    "cost_usd": 0.88
  },
  {
    "label": "Working Backwards",
    "cost_usd": 0.96
  },
  {
    "label": "Pro Git",
    "cost_usd": 1.23
  },
  {
    "label": "Moby-Dick",
    "cost_usd": 1.42
  }
]

در میان 4 کتابی که پروژه اندازه‌گیری کرده است، هزینه هر تبدیل بین 0.88 تا 1.42 دلار آمریکا متغیر بوده و برای کتاب Pro Git برابر با 1.23 است. این ارقام با استفاده از مدل Claude Sonnet 4.5 اندازه‌گیری شده‌اند، شمارش توکن‌ها از tiktoken و با استفاده از cl100k_base انجام شده و تا اوت 2026 در docs/performance.md پروژه منتشر شده‌اند. عدد نهایی شما بسته به مدل و قیمت‌های انتخابی‌تان تغییر می‌کند.

این پروژه همچنین مستند کرده است که برای پاسخ به یک پرسش واحد از طریق مهارت (skill)، بین 24 تا 51 برابر توکن کمتری نسبت به زمانی که کل کتاب در context قرار داده شود، مصرف می‌شود. این موضوع را به عنوان الگوی صرفه‌جویی در نظر بگیرید، نه یک وعده قطعی؛ چرا که به کتاب و پرسش بستگی دارد. نکته ساختاری در هر دو حالت صادق است: هزینه تبدیل یک‌بار پرداخت می‌شود، اما هزینه context dump در هر مکالمه‌ای که به کتاب نیاز داشته باشد، دوباره تکرار می‌شود.

چرا متن PDF را کپی نکنیم یا یک ایندکس RAG نسازیم؟

کپی کردن متن کار می‌کند و برای یک پرسش درباره یک سند، پاسخ درستی است. اما وقتی به همان کتاب در روز سه‌شنبه و دوباره در روز جمعه نیاز دارید، این روش دیگر پاسخ مناسبی نیست، زیرا هر بار هزینه کامل حجم آن را پرداخت می‌کنید.

بازیابی یا RAG (تولید تقویت‌شده با بازیابی)، در زمان پرسش جستجو می‌کند و بخش‌هایی که با کلمات شما مطابقت دارند را بازمی‌گرداند. این روش زمانی که به جمله دقیق نیاز دارید قدرتمند است. اما زمانی که مطلب مفید، چارچوبی است که در یک فصل پخش شده، ضعیف عمل می‌کند؛ زیرا هیچ بخش واحدی حاوی آن نیست. یک Skill این استخراج را یک‌بار در زمان تبدیل انجام می‌دهد و به جای ذخیره بخش‌های متنی، ساختار را ذخیره می‌کند.

محدودیت صادقانه: یک Skill تولیدشده، خلاصه‌ای با اتلاف اطلاعات است که توسط یک مدل نوشته شده. این یک ابزار کمک‌آموزشی است و منبع اصلی همچنان همان منبع باقی می‌ماند. زمانی که متن دقیق دارای بار حقوقی یا پروتکلی است، PDF را نگه دارید و از آن نقل‌قول کنید. مقایسه Skillها با سرورهای MCP و فایل‌های قوانین توضیح می‌دهد که هر رویکرد متعلق به کجاست.

حالت‌های شکست و پیام‌هایی که مشاهده خواهید کرد

یک فایل PDF اسکن‌شده هیچ خروجی‌ای تولید نمی‌کند. استخراج‌کننده، صفحات ابتدایی را برای یافتن لایه متنی بررسی می‌کند و به‌جای پردازش بیهوده 400 صفحه تصویر، با ارائه یک توضیح متوقف می‌شود. ابتدا ocrmypdf input.pdf output.pdf را اجرا کنید و سپس فایل خروجی را به آن بدهید.

دستور pip از نصب خودداری می‌کند. خطای error: externally-managed-environment در Ubuntu 24.04 به این دلیل است که apt از پایتونِ سیستم محافظت می‌کند. از محیط مجازی (virtual environment) که در بالا ذکر شد استفاده کنید، یا poppler-utils را نصب کرده و کلاً از pip صرف‌نظر کنید.

فصل‌ها به‌درستی تفکیک نمی‌شوند. تشخیص فصل به دنبال سرتیترهای صریحی مانند Chapter 7 و معادل‌های زبانی آن می‌گردد. کتابی که از عناوین ساده یا اعداد رومی استفاده می‌کند، باعث تفکیک نامناسب می‌شود؛ راه حل این است که به‌جای تکیه بر حدس سیستم، محل شروع فصل‌ها را به برنامه اعلام کنید.

دستور مورد نظر وجود ندارد. اگر /book-to-skill در تکمیل خودکار (autocomplete) دیده نمی‌شود، به این معناست که دایرکتوری skills پس از شروع نشست (session) شما ایجاد شده است. عامل (agent) را مجدداً راه‌اندازی کنید.

پردازش Docling بسیار طولانی است. با سرعت تقریبی 1.5 ثانیه برای هر صفحه، پردازش یک کتاب طولانی چندین دقیقه زمان CPU می‌گیرد و در یک سرور اشتراکی، این پردازش با سایر سرویس‌های شما رقابت می‌کند. هنگامی که برنامه درباره نوع محتوا سوال می‌کند، گزینه "text-heavy" را انتخاب کنید یا هنگام اجرای دستی scripts/extract.py، پرچم --mode text را ارسال کنید. --mode technical پاسخی است که Docling را انتخاب می‌کند.

یک منبع به‌آرامی ناپدید می‌شود. فایلی که قابل خواندن نباشد نادیده گرفته می‌شود تا پردازش دسته‌ای (batch) به پایان برسد. در نهایت، برنامه گزارش موفقیت می‌دهد اما تعداد منابع پردازش‌شده کمتر از تعداد منابعی است که به آن داده‌اید؛ تنها جایی که این موضوع مشخص می‌شود، فهرست فایل‌ها در گزارش نهایی است.

اعمال دستی همین الگو

این ابزار صرفاً یک تسهیل‌گر است. ساختار، بخش قابل‌انتقال است و یک ویرایشگر متن می‌تواند آن را برای هر منبع مرجعی که در اختیار دارید، ایجاد کند.

1. یک فایل ورودی (entry file) بنویسید و آن را نزدیک به توکن‌های 4,000 که مبدل هدف قرار می‌دهد، نگه دارید. مفاهیم نام‌گذاری‌شده را با فرمول‌بندی دقیق‌شان در آن قرار دهید، به‌علاوه فهرستی که تمام فایل‌های جزئیات و موضوعاتی که هر فایل در بر دارد را لیست کند.
2. مطالب را به فایل‌هایی با حجم تقریبی 1,000 توکن تقسیم کنید؛ هر فایل برای یک موضوع باشد و نام‌گذاری به‌گونه‌ای انجام شود که نام فایل به‌تنهایی محتوای آن را مشخص کند.
3. هر یک از آن فایل‌ها را در فایل ورودی توصیف کنید، در جمله‌ای که زمان مطالعه آن را مشخص می‌کند.

گام 3 همان مرحله‌ای است که افراد از آن صرف‌نظر می‌کنند، در حالی که همین گام باعث کارکرد این الگو می‌شود. عامل (agent) با خواندن فهرست تصمیم می‌گیرد چه فایلی را باز کند، بنابراین فایلی که در فهرست توصیف نشده باشد، فایلی است که عامل هرگز آن را باز نخواهد کرد. فهرست، محصول نهایی است و فایل‌های فصل‌ها صرفاً محل ذخیره‌سازی هستند.

فایل ورودی را در محدوده بودجه فشرده‌سازی نگه دارید تا کل ساختار در یک نشست طولانی حفظ شود. این قانون، چه فایل‌ها توسط مبدل نوشته شده باشند و چه توسط خود شما، صادق است.

FAQ

آیا می‌توانم مهارتی (skill) که از روی کتاب خریداری‌شده ساخته‌ام را منتشر کنم؟

خیر، مگر اینکه مجوز آن کتاب اجازه بازنشر را بدهد. مجوز MIT روی مبدل، تنها کد مبدل را پوشش می‌دهد، نه محتوایی که به آن می‌دهید؛ مهارت تولیدشده یک اثر مشتق‌شده از کتاب محسوب می‌شود. آن را در ~/.claude/skills/ روی سیستم شخصی خود نگه دارید. انتشار برای مستنداتی که خودتان نوشته‌اید یا منابعی با مجوز آزاد بلامانع است. این ابزار در مورد سطح دسترسی مخزن (repository visibility) به‌صورت جداگانه سؤال می‌پرسد و فقط مقادیر public یا private را می‌پذیرد، بنابراین این تصمیم کاملاً آگاهانه باقی می‌ماند.

آیا به docling نیاز دارم یا pdftotext کافی است؟

ابزار pdftotext از مجموعه poppler-utils برای متن‌های ساده کافی است و تقریباً بلافاصله اجرا می‌شود. زمانی از docling استفاده کنید که ارزش کتاب در جداول و لیست‌های کد آن نهفته باشد، زیرا استخراج‌کننده‌های متن ساده دقیقاً همین بخش‌ها را حذف می‌کنند. هزینه این کار، سرعت است: این پروژه docling را تقریباً 1.5 ثانیه برای هر صفحه اندازه‌گیری کرده است، بنابراین یک کتابچه 300 صفحه‌ای، چندین دقیقه از زمان CPU روی یک VPS را اشغال می‌کند.

چرا دستور pip با خطای externally-managed-environment روی VPS من شکست می‌خورد؟

نسخه‌های Ubuntu 24.04 و Debian فعلی، پایتون سیستم را به‌عنوان مدیریت‌شده توسط apt علامت‌گذاری کرده‌اند، بنابراین pip از نصب در آن خودداری کرده و خطای error: externally-managed-environment را نمایش می‌دهد. یک محیط مجازی با python3 -m venv ~/.venvs/book-to-skill بسازید، آن را فعال کنید، استخراج‌کننده‌ها را در آن نصب کنید و سپس عامل (agent) خود را از همان shell اجرا کنید. این مهارت دستور python3 را فراخوانی می‌کند، بنابراین از هر مفسری که در PATH شما باشد استفاده می‌کند که اکنون همان مفسر موجود در محیط مجازی است.

چرا مهارت تولیدشده من به‌عنوان یک slash command نمایش داده نمی‌شود؟

دو دلیل وجود دارد. نام دستور از نام دایرکتوری گرفته می‌شود، بنابراین مهارت باید در مسیر ~/.claude/skills/<name>/SKILL.md یا .claude/skills/<name>/SKILL.md قرار داشته باشد و نام SKILL.md دقیقاً به همین شکل نوشته شده باشد. اگر مسیر درست است، عامل را مجدداً راه‌اندازی کنید. Claude Code تغییرات داخل دایرکتوری‌های مهارتی که از قبل تحت نظارت دارد را شناسایی می‌کند، اما دایرکتوری مهارتی که پس از شروع نشست (session) ایجاد شده باشد، اصلاً تحت نظارت قرار نمی‌گیرد.