ARPAHLS · rosspeili · Aug 9, 2026 · Aug 9, 2026 · Aug 9, 2026 · Aug 9, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,11 @@ Contributors add user-facing entries under `[Unreleased]` in the same PR. Mainta
 
 ## [Unreleased]
 
+### Added
+
+- **Loader:** `SkillLoader.load_skill(..., execute_module=False)` inspect-only load (manifest, instructions, card, requirement pre-flight) without executing `skill.py`; clearer `ImportError` when `skill.py` import fails after pre-flight (#235).
+- **CLI:** `skillware doctor` checks manifest deps and `skill.py` import readiness per skill (`DEPS` / `LOAD` table); optional skill ID, `--category`, and `--skills-root` (#235).
+
 ### Changed
 
 - **Loader:** `SkillLoader.load_skill()` validates manifest `requirements` version specifiers (for example `web3>=6.0.0`) against installed package versions before loading `skill.py`; unpinned entries still require importability only (#14).

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -32,7 +32,7 @@ Pick the path that matches your issue. Only the **skill** row requires the full
 | **Skill upgrade** | Existing bundle under `skills/` | `skill upgrade`, `enhancement` | Skill Upgrade issue | Bundle test + catalog/docs as needed |
 | **Documentation** | `docs/`, `README.md`, `CONTRIBUTING.md` | `documentation` | Documentation Fix issue | Links valid; tone consistent |
 | **Core framework** | `skillware/core/`, framework `tests/` | `core framework`, `enhancement` | Framework Feature issue | `pytest tests/`; update usage docs if API changes |
-| **CLI** | `skillware/cli.py`, `docs/usage/cli.md` | `cli` | CLI issue | `pytest tests/test_cli.py` when relevant |
+| **CLI** | `skillware/cli.py`, `docs/usage/cli.md` | `cli` | CLI issue | `pytest tests/test_cli.py` when relevant (`list`, `doctor`, `test`, `paths`, `examples`, menu) |
 | **Examples** | `examples/*.py`, agent loops, examples index | `examples` | Examples issue | Script runs; `pytest tests/test_registry_docs.py` when index changes |
 | **Packaging** | `pyproject.toml`, `MANIFEST.in`, wheel | `packaging` | Packaging issue | `scripts/wheel_smoke_test.py` after wheel build (see [TESTING.md](docs/TESTING.md#packaging-smoke-test)) |
 | **Bug fix** | Paths named in issue | `bug` | Bug Report | Reproduction or failing test |
@@ -54,7 +54,7 @@ Check [existing issues](https://github.com/ARPAHLS/skillware/issues) before star
 | New capability in the registry | [New Skill Proposal](https://github.com/ARPAHLS/skillware/issues/new/choose) |
 | Upgrade an existing skill | [Skill Upgrade](https://github.com/ARPAHLS/skillware/issues/new/choose) |
 | Loader, adapters, `base_skill` | [Framework Feature](https://github.com/ARPAHLS/skillware/issues/new/choose) |
-| CLI (`list`, `test`, `examples`, menu) | [CLI](https://github.com/ARPAHLS/skillware/issues/new/choose) |
+| CLI (`list`, `test`, `doctor`, `examples`, menu) | [CLI](https://github.com/ARPAHLS/skillware/issues/new/choose) |
 | Runnable examples / agent loops | [Examples](https://github.com/ARPAHLS/skillware/issues/new/choose) |
 | PyPI wheel / install packaging | [Packaging](https://github.com/ARPAHLS/skillware/issues/new/choose) |
 | Docs only | [Documentation Fix](https://github.com/ARPAHLS/skillware/issues/new/choose) |

diff --git a/docs/TESTING.md b/docs/TESTING.md
@@ -223,9 +223,10 @@ Pytest is configured to collect from `tests/` and `skills/` only (`examples/` is
 Before pushing your code, run the following commands:
 
 1. `skillware list` (verify install and path resolution)
-2. `python -m black --check .` (verify formatting; use `python -m black .` to fix)
-3. `python -m flake8 .` (check quality)
-4. `python -m pytest skills/` or `skillware test` (bundle tests — same scope as CI)
-5. `python -m pytest tests/` (framework + maintainer tests — same scope as CI)
-6. `python scripts/sync_extras.py --check` (when `manifest.yaml` or `pyproject.toml` extras change)
-7. `python -m pytest skills/<category>/<skill_name>/test_skill.py` or `skillware test <category>/<skill_name>` for a single skill
+2. `skillware doctor` (optional — check manifest deps and skill.py import readiness)
+3. `python -m black --check .` (verify formatting; use `python -m black .` to fix)
+4. `python -m flake8 .` (check quality)
+5. `python -m pytest skills/` or `skillware test` (bundle tests — same scope as CI)
+6. `python -m pytest tests/` (framework + maintainer tests — same scope as CI)
+7. `python scripts/sync_extras.py --check` (when `manifest.yaml` or `pyproject.toml` extras change)
+8. `python -m pytest skills/<category>/<skill_name>/test_skill.py` or `skillware test <category>/<skill_name>` for a single skill
diff --git a/docs/usage/README.md b/docs/usage/README.md
@@ -16,7 +16,7 @@ By default, `SkillLoader.load_skill()` validates manifest `requirements` before
 
 > **Security:** Loading a skill executes its `skill.py` in your process — there is no sandbox, and the first matching id in the search order wins (a local skill can shadow a bundled one). Only load skills you trust, and see the [skill trust model](../security/skill-trust-model.md) before loading external skills.
 
-To list locally available skills, inspect path resolution, or run bundle tests from the terminal, see the [CLI reference](cli.md) (`skillware list`, `skillware paths`, `skillware test`).
+To list locally available skills, inspect path resolution, check load readiness, or run bundle tests from the terminal, see the [CLI reference](cli.md) (`skillware list`, `skillware paths`, `skillware doctor`, `skillware test`).
 
 | Provider | Adapter | Guide | Agent API key (typical) |
 | :--- | :--- | :--- | :--- |
@@ -26,7 +26,7 @@ To list locally available skills, inspect path resolution, or run bundle tests f
 | OpenAI-compatible hosts | `to_openai_tool()` | [openai_compatible.md](openai_compatible.md) | Host-specific key |
 | DeepSeek | `to_deepseek_tool()` | [deepseek.md](deepseek.md) | `DEEPSEEK_API_KEY` |
 | Ollama (prompt mode) | `to_ollama_prompt()` | [ollama.md](ollama.md) | (local; no cloud key) |
-| CLI | `skillware list`, `skillware paths`, `skillware test`, `skillware examples` | [cli.md](cli.md) | pytest in `[dev]` for `test` |
+| CLI | `skillware list`, `skillware paths`, `skillware doctor`, `skillware test`, `skillware examples` | [cli.md](cli.md) | pytest in `[dev]` for `test` |
 | Install extras | Category, skill, SDK, and meta `pip install` targets | [install_extras.md](install_extras.md) | See guide for `[all]`, `[agents]`, per-skill extras |
 
 Skill-specific **Usage Examples** (sample prompts and execute payloads) live on each [skill catalog page](../skills/README.md).

diff --git a/docs/usage/cli.md b/docs/usage/cli.md
@@ -35,6 +35,7 @@ After installation, the `skillware` command is available directly:
 
     skillware
     skillware list
+    skillware doctor
     skillware test
     skillware examples
     skillware --version
@@ -56,6 +57,7 @@ as Python is installed):
     python -m skillware
     python -m skillware list
     python -m skillware test finance/wallet_screening
+    python -m skillware doctor optimization/prompt_rewriter
     python -m skillware list --category compliance
     python -m skillware --help
 
@@ -105,7 +107,8 @@ Available commands:
 | `2` / `examples` | Browse runnable example scripts (index from `examples/README.md`, or from GitHub when no local copy exists) | Available |
 | `3` / `test` | Run bundle tests (`test_skill.py`) for one or all skills | Available |
 | `4` / `paths` | Show skill root resolution order, tiers, and shadowing | Available |
-| `5` / `help` | Print rich-formatted help with commands, flags, and examples | Available |
+| `5` / `doctor` | Check manifest deps and skill.py import readiness | Available |
+| `6` / `help` | Print rich-formatted help with commands, flags, and examples | Available |
 
 ## Commands
 
@@ -207,6 +210,30 @@ Show where Skillware looks for skills — same order as `SkillLoader.load_skill(
 
 Read-only in v0.4.x; persist project/external paths via config is tracked in #246. Interactive menu: **`4` / `paths`**.
 
+### skillware doctor
+
+Check whether skills can load in the current environment — manifest **requirements** pre-flight (**DEPS**) and `skill.py` import (**LOAD**) — without running `execute()`. Uses the same skill roots as `skillware list`.
+
+    skillware doctor
+    skillware doctor finance/wallet_screening
+    skillware doctor --category compliance
+    skillware doctor --skills-root /path/to/my/skills
+
+#### Arguments and flags
+
+| Input | Description |
+| :--- | :--- |
+| *(no args)* | Diagnose all registry skills visible to `list` |
+| `<category>/<skill_name>` | Diagnose one skill |
+| `--category <name>` | Diagnose all skills in a category |
+| `--skills-root <path>` | Override the skills directory for discovery and load |
+
+**DEPS** validates manifest `requirements` (same rules as `SkillLoader.load_skill()`). **LOAD** imports `skill.py` and discovers the `BaseSkill` subclass; it is skipped (shown as `—`) when **DEPS** fails. The **DETAIL** column shows the first line of any error.
+
+Exit code is non-zero when any skill fails **DEPS** or **LOAD**. For full bundle behavior, use `skillware test`.
+
+Interactive menu: **`5` / `doctor`**.
+
 ## Path resolution
 
 `skillware list` searches for skills in the same order as `SkillLoader`:

diff --git a/docs/usage/install_extras.md b/docs/usage/install_extras.md
@@ -158,6 +158,8 @@ On failure it raises `ImportError` with:
 
 The loader does not install or upgrade packages — use pip extras or install the requirement strings yourself.
 
+Use `SkillLoader.load_skill(..., execute_module=False)` for inspect-only loads (manifest, instructions, card, and optional requirement pre-flight) without executing `skill.py`. The CLI `skillware doctor` command uses this mode for the **DEPS** column before attempting a full import for **LOAD**.
+
 Packaging smoke tests use `check_requirements=False` so a base wheel install can verify bundles without optional extras ([TESTING.md](../TESTING.md#packaging-smoke-test)).
 
 ## Contributors

diff --git a/docs/vision.md b/docs/vision.md
@@ -45,7 +45,7 @@ Multi-layer screening runs locally in one `execute()` call. No generated scraper
 Skillware is designed so agents and their operators can discover, vet, and integrate capabilities without reinventing the wheel.
 
 - **Manifests** declare inputs, outputs, dependencies, and constitution in `manifest.yaml`.
-- **`skillware list`**, **`skillware examples`** / **`skillware list --examples`**, and **`skillware test`** (CLI) surface the local registry, browse the runnable example index, and run bundle tests.
+- **`skillware list`**, **`skillware doctor`**, **`skillware examples`** / **`skillware list --examples`**, and **`skillware test`** (CLI) surface the local registry, check load readiness, browse the runnable example index, and run bundle tests.
 - **[Examples index](../examples/README.md)** maps runnable provider scripts to skills.
 - **[Usage guides](usage/README.md)** show the same load / tool-call / execute loop for Gemini, Claude, OpenAI, DeepSeek, and Ollama.
 - **[Agent contribution workflow](contributing/ai_native_workflow.md)** documents how supervised agents propose scoped changes and open PRs.
@@ -106,7 +106,7 @@ Honest snapshot for **v0** (current v0.4.x line):
 
 - **Registry**: Skills under `skills/` with docs in [docs/skills/](skills/README.md).
 - **Loader**: Dynamic import, auto-discovered `bundle["class"]`, dependency checks, and adapters for major LLM tool formats.
-- **CLI**: `skillware list`, `skillware test`, and an interactive menu, included with `pip install skillware`. Use `skillware list --examples` and `skillware examples` to browse the runnable script index from the terminal.
+- **CLI**: `skillware list`, `skillware doctor`, `skillware test`, and an interactive menu, included with `pip install skillware`. Use `skillware list --examples` and `skillware examples` to browse the runnable script index from the terminal.
 - **Active work**: Wallet screening enhancements ([RFC #115](https://github.com/ARPAHLS/skillware/issues/115)), contributor docs, and good first issues across docs and framework.
 
 Browse [open good first issues](https://github.com/ARPAHLS/skillware/issues?q=is%3Aopen+label%3A%22good+first+issue%22) if you want a low-risk entry point.