feat: add Python agent briefings

README.md

@@ -84,14 +84,15 @@ environment:
 ```python
 import agent_plugins as ap
 
-plugin = ap.locate("agent-plugins")
-consumer_skill = plugin.skill("agent-plugins")
-packaging_skill = plugin.skill("package-agent-plugin")
-
-print(consumer_skill.source)
-print(packaging_skill.source)
+print(ap.read("agent-plugins"))
+print(ap.read("agent-plugins", skill="package-agent-plugin"))
 ```
 
+`read()` returns a briefing for the same-name skill by default. Pass `skill=`
+for another workflow. The CLI reads all packaged skills unless `--skill` is
+provided. `uvx` uses an isolated tool environment, so read through the target
+interpreter when working with an existing installation.
+
 Pass your library's distribution name to `locate()` to inspect its plugin. Use [`Plugin.from_project()`](https://peter-gy.github.io/agent-plugins/guide/inspect-project) to inspect the selected source files before building.
 
 ## Documentation

development_docs/architecture.md

@@ -67,7 +67,7 @@ other source → supplied BuildPlan           │          │          │
 
 ## Dependency direction
 
-The public `agent_plugins` package re-exports build planning, wheel attachment, discovery, filesystem, schema-value, and diagnostic types. `agent_plugins.build` separately exports the low-level `BuildBackend`.
+The public `agent_plugins` package re-exports build planning, wheel attachment, discovery, briefing rendering, filesystem, schema-value, and diagnostic types. `agent_plugins.build` separately exports the low-level `BuildBackend`.
 
 Artifact operations depend on plan validation and archive writers. Archive writers depend on plan values and the marker codec. Runtime discovery depends on the marker codec and file inventory. Project inspection composes build planning with the same inventory model.
 
@@ -76,6 +76,13 @@ Versioned schema loaders produce normalized values. Stdio resolution consumes th
 The CLI parses input, calls domain functions, and writes their rendered output.
 Core modules do not depend on terminal state.
 
+`read()` selects one skill, defaulting to the distribution argument exactly.
+The CLI's `read` command selects every skill unless `--skill` is supplied.
+Both use `_read.py` for the same metadata, interpreter identity, environment
+guidance, documentation links, and complete skill source. Reading a briefing
+uses distribution metadata and selected files without importing the target
+package or activating a host integration.
+
 ## Public object model
 
 `Plugin` and `Skill` are slotted filesystem handles. Plugin equality and hashing

development_docs/testing-and-release.md

@@ -52,6 +52,7 @@ The distribution verifier:
 | Build-plan selection and CLI JSON | `tests/test_plan.py` |
 | Public wheel attachment, preservation, validation, signatures, and `RECORD` | `tests/test_wheel.py` |
 | CLI read and attachment output, warnings, and exit statuses | `tests/test_cli.py` |
+| Python briefings, skill selection, CLI parity, and module help | `tests/test_read.py` |
 | Backend parity, sdist rebuilds, editable markers, and sdist modes | `tests/test_build_backends.py` |
 | Installed distribution discovery and marker failures | `tests/test_discovery.py` |
 | Project-selected plugin inventory, paths, display, named skills | `tests/test_plugin.py` |

docs/guide/inspect-installed.md

@@ -17,11 +17,31 @@ Read a package's complete primary agent instructions in one command:
 uvx --with my-project agent-plugins read my-project
 ```
 
-uv installs `my-project` and `agent-plugins` in one temporary environment. The
-command prints the complete version-matched guidance carried by `my-project`.
+uv installs `my-project` and `agent-plugins` in an isolated tool environment.
+The command reads that installation. Its cached paths may remain readable
+locally, but the project or notebook can have a different installation or
+filesystem.
 
-Use `locate()` when the Python library is already installed in the environment
-where the agent will work:
+## Read in the execution environment
+
+When the package is already installed, read its briefing in the Python
+environment where the agent will work:
+
+```python
+import agent_plugins as ap
+
+print(ap.read("agent-plugins"))
+print(ap.read("agent-plugins", skill="package-agent-plugin"))
+```
+
+`read()` returns one skill with distribution identity, interpreter, resource
+guidance, and the plugin inventory. It defaults to the skill whose directory
+name matches the distribution argument exactly. Pass `skill=` for another
+name. The CLI includes all skills unless `--skill` is supplied.
+
+Read again when switching environments or installations. Reuse loaded
+instructions for the same installation and follow their runtime readiness
+checks. To inspect files programmatically, use `locate()`.
 
 ## Locate one distribution
 

docs/reference/cli.md

@@ -33,14 +33,16 @@ agent-plugins read DISTRIBUTION [--skill NAME]
 `DISTRIBUTION` is an installed Python distribution name. Human output is a
 Markdown briefing containing:
 
-- Python distribution and plugin manifest metadata
+- Python distribution and plugin manifest metadata, interpreter path, and
+  declared `Documentation` and `Documentation Index` URLs
 - the bounded selected plugin file tree and installed root
 - client extension names and manifest validation issues
 - MCP server names and transport types, with configured commands, arguments,
   environment values, URLs, and headers excluded
 - the complete `SKILL.md` source for every packaged Agent Skill by default
 
-The generated introduction explains relative resource paths. Skill source
+The generated introduction explains environment ownership and relative resource
+paths, including the disposable tool environment used by `uvx`. Skill source
 remains complete. The inventory uses the standard tree bounds of four levels
 and 100 files, and reports omitted depth or file counts. Inspect the printed
 installed root when a skill routes to a resource outside that view.
@@ -60,6 +62,13 @@ separate inputs. uv installs the requirement into the temporary command
 environment. `read` selects that installed distribution through Python
 metadata.
 
+To inspect an existing project or notebook installation, run
+`python -m agent_plugins read my-package` with that environment's interpreter.
+Its paths and package version may differ from the isolated tool environment.
+Use [`ap.read()`](./python-api#read-a-briefing) inside a Python execution host.
+The Python API defaults to the same-name skill, while the CLI defaults to all
+skills.
+
 ## `agent-plugins plan`
 
 ```text

docs/reference/python-api.md

@@ -15,15 +15,15 @@ The installed `agent-plugins` distribution includes separate consumer and
 packaging skills:
 
 ```python
-plugin = ap.locate("agent-plugins")
-print(plugin.skill("agent-plugins").source)
-print(plugin.skill("package-agent-plugin").source)
+print(ap.read("agent-plugins"))
+print(ap.read("agent-plugins", skill="package-agent-plugin"))
 ```
 
 The distribution supports Python 3.10 through 3.14 and ships a `py.typed` marker.
 
 | Task | Entry point |
 | --- | --- |
+| Read a skill with its installed package context | [`read()`](#read-a-briefing) |
 | Preview selected package files | [`build_plan()`](#build-planning) |
 | Add a plugin to an existing wheel | [`attach_wheel()`](#wheel-attachment) |
 | Find plugins in this environment | [`locate()` and `installed()`](#installed-discovery) |
@@ -33,6 +33,37 @@ The distribution supports Python 3.10 through 3.14 and ships a `py.typed` marker
 | Inspect tool configuration and prepare a launch | [`MCPConfig`](#mcpconfig) |
 | Wrap a Python build backend | [`BuildBackend`](#buildbackend) |
 
+## Read a briefing
+
+### `read(distribution_name, *, skill=None)`
+
+```python
+def read(distribution_name: str, *, skill: str | None = None) -> str: ...
+```
+
+Returns a Markdown briefing from the current interpreter's installation. The
+briefing includes distribution and plugin metadata, the interpreter and resource
+root, environment guidance, a bounded inventory, MCP summaries, and the complete
+selected `SKILL.md` source. It also includes `Documentation` and `Documentation
+Index` URLs declared in the distribution's `Project-URL` metadata.
+
+- `distribution_name` is the installed Python distribution name.
+- `skill` is the structural skill directory name. Omitted or `None` uses
+  `distribution_name` exactly, including its spelling. An unavailable name raises
+  an error listing the available skills.
+
+The function returns text without printing, importing the target package, or
+activating its components. Raises `AgentPluginError` for an absent or unusable
+installation or unavailable skill. Invalid plugin documents raise
+`ValidationError`.
+
+The [CLI `read`](./cli#agent-plugins-read) uses the same renderer but includes all
+skills by default. Use `--skill NAME` for the equivalent single-skill output.
+
+To expose a core skill through `help(my_package.agent)`, set the optional agent
+module's `__doc__` to `ap.read("my-package")`. Read the bundled
+`package-agent-plugin` skill for the complete authoring pattern.
+
 ## Build planning
 
 ### `build_plan(project=".")`

pyproject.toml

@@ -23,6 +23,7 @@ classifiers = [
 
 [project.urls]
 Documentation = "https://peter-gy.github.io/agent-plugins/"
+"Documentation Index" = "https://peter-gy.github.io/agent-plugins/llms.txt"
 Issues = "https://github.com/peter-gy/agent-plugins/issues"
 Source = "https://github.com/peter-gy/agent-plugins"
 

scripts/verify-dist.sh

@@ -59,6 +59,7 @@ expected_files = {
     "skills/agent-plugins/agents/openai.yaml",
     "skills/package-agent-plugin/SKILL.md",
     "skills/package-agent-plugin/agents/openai.yaml",
+    "skills/package-agent-plugin/references/briefings.md",
     "skills/package-agent-plugin/references/build-variants.md",
     "skills/package-agent-plugin/references/verify-artifacts.md",
 }
@@ -122,6 +123,8 @@ selected = subprocess.run(
 assert skill.source in selected.stdout
 assert package_skill.source not in selected.stdout
 assert selected.stderr == ""
+assert ap.read("agent-plugins") == selected.stdout
+assert package_skill.source in ap.read("agent-plugins", skill="package-agent-plugin")
 PY
 }