KEEP IT HANDS-ON functional ~ tested 2026-09-20
// sandboxed in macOS (host) Β· aarch64 Β·install log Β· why not fully functional: Core doc-to-skill pipeline verified end to end offline (PDF create, package for Claude, quality gate, 40-tool MCP handshake plus list_configs call, byte-identical skills.sh install, full repo suite). AI enhancement not verified: LOCAL mode invokes the host's claude CLI which errored (exit 1, not authenticated here) and no API keys were available; live web, GitHub, and video scraping not exercised. Β·functional log

Skill Seekers

by Yusuf Karaaslan · https://github.com/yusufkaraaslan/Skill_Seekers · MIT · v3.9.1 (PyPI) / 3.10.0.dev0 (development branch) · updated 2026-09-20
Don't install your next skill blind. One email a week: what's worth installing.

The doc-to-skill converter giant finally reviewed: a 4,357-test engine with README drift on its own quick start.

⚙ ⚙ ⚙ ⚙ ⚙ 4 / 5
quality 4/5
documentation 4/5
setup 3/5
value 5/5
ecosystem fit 4/5
// bottom line

The engine is real and unusually well tested: it built a structured skill from a PDF offline in seconds, packaged it for Claude, answered a 40-tool MCP handshake, and passed 4,357 of its own tests on this host. But the README documents commands the pip release does not ship, the MCP HTTP instructions are wrong, and the core install weighs 371MB because langchain and llama-index are mandatory. Install it if you convert documentation for a living; expect to work around docs drift until 3.10.0 ships.

Get the skill digest The best and the broken from 100+ hands-on tests. One email a week.
pip (core)
$pip install skill-seekers

371MB venv; langchain and llama-index are core deps

pip (MCP server)
$pip install "skill-seekers[mcp]"

then: python -m skill_seekers.mcp.server_fastmcp

skills.sh
$npx skills add yusufkaraaslan/skill_seekers --skill skill-builder

407 registry installs

install if

  • RAG and knowledge-pipeline builders. One scrape feeding 22 export targets, with chunking that preserves code blocks, plus vector-db upsert paths, replaces a stack of glue scripts.
  • Teams with large internal doc sites. The quality gate, sync monitoring, incremental updates, and streaming ingestion for 10K-page sites are production concerns this handles so you do not have to.
  • Agent-skill authors who keep rebuilding the same SKILL.md scaffolding. The generated output (frontmatter, when-to-use, references, index) is a sound skeleton even before enhancement, and golden tests keep its shape stable.

What It Does

Skill Seekers is a Python tool and MCP server that converts knowledge sources into agent skills and RAG assets. Point skill-seekers create at a documentation URL, a GitHub repo shorthand, a local directory, or a file (PDF, DOCX, EPUB, PPTX, ipynb, OpenAPI, AsciiDoc, RSS, man page, Confluence, Notion, chat export; 18 source types claimed) and it scrapes, structures, and emits a SKILL.md plus references, which you then package for any of 22 targets (Claude, Gemini, OpenAI, Kimi, DeepSeek, LangChain, LlamaIndex, Chroma, FAISS, Weaviate, Qdrant, Pinecone, and more). It also ships a 40-tool MCP server, a Claude plugin, a GitHub Action, a web UI called Seeker HUD, and one routing SKILL.md (skill-builder) that tells an agent which MCP tool to pick per source type. The audience is skill authors, RAG pipeline builders, and teams with large internal documentation. At review time: 15,011 stars, 1,530 forks, MIT, 30 contributors, 30 releases, pushed the morning of review.

The Good

The test culture is the deepest in the doc-to-skill tier. The repo carries 191 test files, and the full suite passed 4,357 tests with 110 skips in 99 seconds on this host (sole failure: a nested-venv creation test that dies with SIGABRT on this Mac's Python build, an environment quirk, not product logic). That exceeds the README's "3,900+ tests" claim. Generation itself is pinned by 23 golden SKILL.md files covering pdf, html, jupyter, epub, pptx, man, rss, chat, and word inputs, so regressions in the generated output shape are caught, not just in the code.

The core claim works offline, end to end, without an API key. skill-seekers create on the repo's own synthetic PDF fixture produced an 88-line SKILL.md with frontmatter, when-to-use guidance, chapter overview, key concepts, quality-scored code examples (10.0/10 and 8.4/10), accurate statistics (3 pages, 2 code blocks, python detected), and a references/ directory with an index. package --target claude emitted a 1,612-byte zip with upload instructions, and quality scored the result 72.8/100 (B-) and wrote a report file. Total elapsed time for all three steps was under a minute on a laptop.

The MCP surface is exactly as advertised at the wire level. The stdio handshake returned 40 tools (matching the README badge), full capabilities, and a working list_configs call that listed the bundled presets from the repo checkout. The universal installer path also works: npx skills add yusufkaraaslan/skill_seekers --agent hermes-agent --skill skill-builder --copy --yes landed a SKILL.md byte-identical to the repo's copy in .hermes/skills/skill-builder.

Engineering hygiene above the norm for this star class. The CHANGELOG is 216KB of Keep-a-Changelog entries with issue and PR attribution for every change, including honest engineering notes (a vector-figure dedup fix explaining why intersection-over-smaller-area deleted architecture diagrams under embedded logos). Twelve README translations, 8 CI workflows including a Python 3.10-3.12 OS matrix and Playwright browser regressions for the HUD, 30 tagged releases in lockstep with PyPI, and a live community-configs repo and docs site (both returned 200).

The Bad

The README quick start documents a command the pip release does not have. skill-seekers detect https://docs.djangoproject.com/ --json fails on PyPI 3.9.1 with error: argument command: invalid choice: 'detect'. The detect command is in the Unreleased 3.10.0.dev0 section of the changelog (issue #457). Same story for quality --json (issue #458): error: unrecognized arguments: --json. Anyone following the quick start on the current release hits two failures in the first five minutes; the workaround is installing from git.

The documented MCP HTTP command is broken against the code. README says python -m skill_seekers.mcp.server_fastmcp --transport http --port 8765. There is no --transport argument: the error is unrecognized arguments: --transport http. The implemented flag is --http. The module's own docstring also still says "34 tools" while the file registers 40, and the MCP handshake reports serverInfo version 1.30.0, which is the mcp library's version, not the product's 3.9.1.

The core install is 371MB because langchain, llama-index, and anthropic are mandatory dependencies. The README table says core is "scraping, GitHub, PDF, packaging," but pip install skill-seekers pulls the full RAG stack (plus tiktoken, nltk, sqlalchemy, and openai transitively) in 63 seconds. Anyone who only wants PDF-to-skill pays for three frameworks they never call. Python 3.10+ is required, so macOS system Python 3.9 users need a newer interpreter first.

The skill you get depends on which door you walk in, and the weaker copy is the standard one. The repo ships two variants of the skill-builder SKILL.md. The Claude-plugin copy has a Prerequisites section (install [mcp], register the server) and a CLI-fallback section for when the MCP server is not connected. The skills/skill-seekers/ copy, which is what skills.sh serves and what every universal-installer user receives, has neither: agents that install via the registry get no fallback instructions. The frontmatter name (skill-builder) also mismatches the directory (skill-seekers).

create chains into an agent CLI with permissions skipped by default. After building the skill, the tool automatically launched LOCAL enhancement running claude --dangerously-skip-permissions headless with a 45-minute timeout. On this host it failed with exit code 1 (no authenticated session) and the tool reported it honestly, but the default path invokes another vendor's CLI with permission checks disabled unless you pass --enhance-level 0. Version strings meanwhile span five values: README badge 3.9.0, plugin.json 3.9.1, PyPI 3.9.1, pyproject 3.10.0.dev0, MCP serverInfo 1.30.0.

Smoke Test Results

Host-based run on macOS 26.5.2 aarch64, Python 3.11.14, clone of development at 8323b82 (55MB), PyPI package 3.9.1. No API keys used.

Run A: Fresh venv, PyPI release, no preinstalled deps

$ /Users/openclaw/.local/bin/python3.11 -m venv /tmp/ss-venv && /tmp/ss-venv/bin/pip install skill-seekers
βœ… PASS: installs in 63s, resolves 3.9.1 (venv weighs 371MB)
$ /tmp/ss-venv/bin/skill-seekers --version
βœ… PASS: skill-seekers 3.9.1
$ /tmp/ss-venv/bin/skill-seekers --help
βœ… PASS: 19 commands listed, matches README "all 19 commands"
$ /tmp/ss-venv/bin/skill-seekers doctor
βœ… PASS: 6 passed, 2 warnings, 0 errors (notes optional deps 1/10, no API keys)
$ /tmp/ss-venv/bin/skill-seekers detect https://docs.djangoproject.com/ --json
❌ FAIL: error: argument command: invalid choice: 'detect' (Unreleased 3.10.0 feature, #457)
$ /tmp/ss-venv/bin/skill-seekers quality /nonexistent --json
❌ FAIL: error: unrecognized arguments: --json (Unreleased, #458)

Pass rate: 4 of 6. Both failures are README-documented commands missing from the shipped release, not engine defects.

Full sandbox log β†’

Run B: Sandbox with deps preinstalled

$ /tmp/ss-venv/bin/pip install "skill-seekers[mcp]"
βœ… PASS: mcp 1.30.0 installed
$ python3.11 mcp-stdio-client.py /tmp/ss-venv/bin/python -m skill_seekers.mcp.server_fastmcp
βœ… PASS: handshake ok; tool count: 40 (serverInfo version 1.30.0 is the mcp lib, not 3.9.1)
$ python3.11 mcp-stdio-client.py ... --call list_configs (from repo checkout)
βœ… PASS: isError: False; bundled presets listed (astrovalley, blender, ...)
$ /tmp/ss-venv/bin/python -m skill_seekers.mcp.server_fastmcp --transport http --port 8765
❌ FAIL: error: unrecognized arguments: --transport http (real flag: --http)
$ /tmp/ss-venv/bin/skill-seekers workflows list | grep -c "^[a-z0-9-]"
βœ… PASS: 68 bundled workflow presets, exactly the claimed count

Pass rate: 4 of 5. The MCP server, its tool count, and its dispatch are genuine; the failure is the README's wrong transport flag.

Full sandbox log β†’

Run C: Functional verification (does it do what it claims?)

$ /tmp/ss-venv/bin/skill-seekers create .../tests/fixtures/synthetic/document.pdf --name synthdoc --non-interactive
βœ… PASS: SKILL.md (88 lines) + references/document.md (642B) + index.md (214B); stats match input
 (3 pages, 2 code blocks, python); auto-chained claude enhancement failed exit 1 and was
 reported honestly (--enhance-level 0 skips it)
$ /tmp/ss-venv/bin/skill-seekers package output/synthdoc/ --target claude
βœ… PASS: output/synthdoc.zip, 1,612 bytes
$ /tmp/ss-venv/bin/skill-seekers quality output/synthdoc/
βœ… PASS: Quality Score: 72.8/100 (Grade: B-), quality_report.json written
$ npx -y skills add yusufkaraaslan/skill_seekers --agent hermes-agent --skill skill-builder --copy --yes
βœ… PASS: lands in ./.hermes/skills/skill-builder, byte-identical to repo skills/skill-seekers/SKILL.md
$ cd /tmp/skill-seekers-review && PATH="/tmp/ss-venv/bin:$PATH" python -m pytest -q
βœ… PASS: 4357 passed, 1 failed (nested-venv SIGABRT, environmental), 110 skipped, 98.9s

Functional pass rate: 5 of 5.

Full functional log β†’

What the runs tell you

The engine, packaging, quality gate, MCP server, and installer path all work first try from the pip release, and the repo's own suite is green beyond its advertised count. Every failure found is documentation and metadata drift (quick-start and MCP commands ahead of or contrary to the shipped code), plus a heavyweight dependency floor. Note the suite evidence is from the development branch: run against the installed 3.9.1 package, 12 test modules fail collection because the tests already target unreleased internals, which is the same drift seen in the README, just inside the repo.

Setup Walkthrough

  1. Install Python 3.10+ (macOS system 3.9 is not enough; this test used 3.11.14) and run pip install skill-seekers. Expect 63 seconds and 371MB.
  2. Verify with skill-seekers doctor. It reports 14 core deps, which optional extras are missing, and whether API keys are set.
  3. Build a first skill offline: skill-seekers create some.pdf --name mydoc --non-interactive. Add --enhance-level 0 if you do not want it to launch a local agent CLI for enhancement afterward.
  4. Package: skill-seekers package output/mydoc/ --target claude produces output/mydoc.zip.
  5. For the MCP server: pip install "skill-seekers[mcp]", then run python -m skill_seekers.mcp.server_fastmcp (stdio) or add --http --port 8765. Ignore the README's --transport spelling; it does not exist.
  6. For agent-native use: npx skills add yusufkaraaslan/skill_seekers --skill skill-builder, but read the plugin copy of the SKILL.md in distribution/claude-plugin/ for the MCP prerequisites and CLI fallback the registry copy omits.

Post-install gotchas: the quick start's detect and quality --json need the development branch (pip install git+https://github.com/yusufkaraaslan/Skill_Seekers.git); the default clone lands on the development branch, not main; and the GitHub Action's command input still lists pre-unification subcommands (scrape, github, pdf) that the CLI has removed, though the default create value works.

Alternatives

  1. virgiliojr94/book-to-skill: reviewed 4.5/5; converts books and PDFs into skills with a lighter footprint. Prefer it when your sources are files and you want minimal deps.
  2. microsoft/skill-recorder: reviewed 4.5/5; records a live work session and reconstructs a skill from intent and steps. Prefer it when the knowledge lives in how you work, not in documents.
  3. FrancyJGLisboa/agent-skill-creator: reviewed 4.5/5; a meta-skill for authoring skills across 17 platforms. Prefer it when you are designing a skill by hand and want structure, not conversion.
// review provenance
reviewed by
GearScope
tested
2026-09-20 · macOS (Apple Silicon)
last verified
2026-09-20
depth
HANDS-ON
sponsorship
none, ever
// share this review
// feedback
was this review helpful?

Don't install your next skill blind.

Every week: the shortlist of skills worth installing β€” and the ones to skip β€” from 100+ hands-on tests. No spam, no affiliate links.