AGENTS.md - Skill Seekers

AGENTS.md - Skill Seekers

Concise reference for AI coding agents. Skill Seekers is a Python CLI tool (v3.3.0) that converts documentation sites, GitHub repos, PDFs, videos, notebooks, wikis, and more into AI-ready skills for 16+ LLM platforms and RAG pipelines.

Setup

# REQUIRED before running tests (src/ layout — tests hard-exit if package not installed)
pip install -e .
# With dev tools (pytest, ruff, mypy, coverage)
pip install -e ".[dev]"
# With all optional deps
pip install -e ".[all]"

Note: `tests/conftest.py` checks that `skill_seekers` is importable and calls `sys.exit(1)` if not. Always install in editable mode first.

Build / Test / Lint Commands

# Run ALL tests (never skip tests — all must pass before commits)
pytest tests/ -v

# Run a single test file
pytest tests/test_scraper_features.py -v

# Run a single test function
pytest tests/test_scraper_features.py::test_detect_language -v

# Run a single test class method
pytest tests/test_adaptors/test_claude_adaptor.py::TestClaudeAdaptor::test_package -v

# Skip slow/integration tests
pytest tests/ -v -m "not slow and not integration"

# With coverage
pytest tests/ --cov=src/skill_seekers --cov-report=term

# Lint (ruff)
ruff check src/ tests/
ruff check src/ tests/ --fix

# Format (ruff)
ruff format --check src/ tests/
ruff format src/ tests/

# Type check (mypy)
mypy src/skill_seekers --show-error-codes --pretty

**Pytest config** (from pyproject.toml): `addopts = "-v --tb=short --strict-markers"`, `asyncio_mode = "auto"`, `asyncio_default_fixture_loop_scope = "function"`. **Test markers:** `slow`, `integration`, `e2e`, `venv`, `bootstrap`, `benchmark`, `asyncio`. **Async tests:** use `@pytest.mark.asyncio`; asyncio_mode is `auto` so the decorator is often implicit. **Test count:** 123 test files (107 in `tests/`, 16 in `tests/test_adaptors/`).

Code Style

Formatting Rules (ruff — from pyproject.toml)

• Line length: 100 characters
• Target Python: 3.10+
• Enabled lint rules: E, W, F, I, B, C4, UP, ARG, SIM
• Ignored rules: E501 (line length handled by formatter), F541 (f-string style), ARG002 (unused method args for interface compliance), B007 (intentional unused loop vars), I001 (formatter handles imports), SIM114 (readability preference)

Imports

• Sort with isort (via ruff); skill_seekers is first-party
• Standard library → third-party → first-party, separated by blank lines
• Use from __future__ import annotations only if needed for forward refs
• Guard optional imports with try/except ImportError (see adaptors/__init__.py pattern):

  try:
      from .claude import ClaudeAdaptor
      from .minimax import MiniMaxAdaptor
  except ImportError:
      ClaudeAdaptor = None
      MiniMaxAdaptor = None

Naming Conventions

• Files: snake_case.py (e.g., source_detector.py, config_validator.py)
• Classes: PascalCase (e.g., SkillAdaptor, ClaudeAdaptor, SourceDetector)
• **Functions