agent-readable 0.1.0__tar.gz → 0.1.2__tar.gz

{agent_readable-0.1.0 → agent_readable-0.1.2}/.github/workflows/test.yml

@@ -7,6 +7,23 @@ on:
   workflow_dispatch:
 
 jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install dev deps
+        run: uv sync --group dev
+
+      - name: Ruff check
+        run: uv run ruff check
+
+      - name: Ruff format check
+        run: uv run ruff format --check
+
   test:
     runs-on: ubuntu-latest
     strategy:

agent_readable-0.1.2/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.2] - 2026-05-30
+
+### Added
+
+- `py.typed` marker so inline type annotations are visible to downstream type
+  checkers (PEP 561).
+- A module's `__all__` is now honored as the authoritative public API when
+  present, including symbols re-exported from other modules.
+- `agent_help()` now emits a `UserWarning` when a class defines both a custom
+  `__agent_help__()` and `__agent_notes__()`, since the notes are silently
+  dropped in that case.
+- Agent Skill at `skills/agent-readable/SKILL.md` following the
+  [Agent Skills open standard](https://agentskills.io). Installable via
+  `npx skills add zydo/agent-readable --skill agent-readable` and portable
+  across Claude Code, Codex CLI (OpenAI), Gemini CLI (Google), GitHub Copilot,
+  Cursor, JetBrains Junie, Goose, OpenCode, and 40+ other adopters. The skill
+  teaches the agent to call `agent_help()` before writing Python against a
+  library and to author new APIs with `__agent_notes__()`. Supersedes
+  `AGENT-PROMPT.md` as the recommended way to wire up coding agents.
+
+### Fixed
+
+- Method signatures with a positional-only `self` no longer render a dangling
+  `/` (e.g. `backup(/, target)` now renders as `backup(target)`).
+
+### Documentation
+
+- README and examples reframed around curation, not compactness. The "Why it
+  matters" section now leads with two failure modes — what-exists (curated
+  Public API list curbs hallucinated methods and stale signatures) and
+  how-to-use (lifecycle rules via `__agent_notes__()`) — instead of a
+  comparative empirical claim about which is more common. Removed the
+  "217 vs 56 lines" framing in favor of structure-and-rules language.
+- Tagline sharpened to lead with the hallucination-stopping outcome rather
+  than the protocol mechanics.
+
+### Removed
+
+- `AGENT-PROMPT.md` (superseded by the agent skill at
+  `skills/agent-readable/SKILL.md`).
+
+## [0.1.1] - 2026-05-11
+
+### Added
+
+- `agent_help()` support for functions and methods.
+
+### Documentation
+
+- Demo GIF comparing `agent_help()` and `help()`, plus additional README
+  examples.
+
+## [0.1.0] - 2026-05-10
+
+### Added
+
+- Initial release: the `agent_help()` function, the `AgentReadable` protocol,
+  `AgentReadableMixin`, `__agent_notes__` accumulation across the MRO, module
+  support, and the `python -m agent_readable` CLI.
+
+[Unreleased]: https://github.com/zydo/agent-readable/compare/v0.1.2...HEAD
+[0.1.2]: https://github.com/zydo/agent-readable/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/zydo/agent-readable/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/zydo/agent-readable/releases/tag/v0.1.0

{agent_readable-0.1.0 → agent_readable-0.1.2}/PKG-INFO

@@ -1,15 +1,16 @@
 Metadata-Version: 2.4
 Name: agent-readable
-Version: 0.1.0
-Summary: A lightweight protocol for exposing agent-oriented documentation from Python classes and modules
+Version: 0.1.2
+Summary: A lightweight Python protocol for agent-oriented documentation
 Project-URL: Repository, https://github.com/zydo/agent-readable
+Project-URL: Issues, https://github.com/zydo/agent-readable/issues
+Project-URL: Changelog, https://github.com/zydo/agent-readable/blob/main/CHANGELOG.md
 Author: zydo and agent-readable contributors
 License-Expression: MIT
 License-File: LICENSE
 Keywords: agent,agent-help,ai,ai-agent,coding-agent,context-engineering,docstring,documentation,llm,mixin,prompt-engineering,protocol,vibe-coding
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -26,22 +27,22 @@ Description-Content-Type: text/markdown
 
 # agent-readable
 
-A lightweight Python protocol for exposing agent-oriented documentation from classes and modules.
+Stop coding agents from hallucinating your library's API. Ship the usage rules — lifecycle order, pre-conditions, anti-patterns — right next to your code.
+
+<!-- markdownlint-disable MD033 -->
+<p align="center">
+  <strong><code>logging.Logger</code> compared with <code>agent_help()</code> and <code>help()</code></strong><br>
+  <img src="docs/agent_help_vs_help.gif" alt="agent_help vs help">
+</p>
+<!-- markdownlint-enable MD033 -->
 
 ## Problem
 
 AI coding agents recognize established libraries from their training data, but they hallucinate when APIs change, when libraries are new, or when correct usage depends on rules that aren't visible from the API surface — pre-conditions, lifecycle order, anti-patterns, *"use `call()` for non-streaming, `stream()` for streaming."*
 
-Today there's nowhere to put those rules where an agent will reliably find them. Docstrings document the API surface, not behavioral rules. `AGENTS.md` and `llms.txt` work at project granularity, drift fast, and don't travel with refactors. `help()` is verbose and only describes interfaces.
-
-`agent-readable` adds two dunders — `__agent_help__` (full custom output) and `__agent_notes__` (additive guidance that accumulates across inheritance) — that live next to the code. Library authors annotate once; any agent that calls `agent_help(cls)` gets the rules.
-
-```text
-help(logging.Logger)        217 lines — every inherited method, dunder, and MRO detail.
-agent_help(logging.Logger)   56 lines — structured sections + any author notes.
-```
+Today there's nowhere to put those rules where an agent will reliably find them. Docstrings document the API surface, not behavioral rules. `AGENTS.md` and `llms.txt` work at project granularity, drift fast, and don't travel with refactors. `help()` only describes interfaces — and mixes inherited dunders and MRO detail in with the methods you actually want to use.
 
-The compactness is a side effect; the structure is the point.
+`agent-readable` adds two dunders — `__agent_help__` (full custom output) and `__agent_notes__` (additive guidance that accumulates across inheritance) — that live next to the code. Library authors annotate once; any agent that calls `agent_help(cls)` gets a curated public-API list with current signatures, the class's behavioral rules attached, and no inherited-dunder or MRO noise to wade through.
 
 ## Installation
 
@@ -124,12 +125,15 @@ Reads a value from a hardware sensor.
 
 ## Why it matters
 
-`help()` documents the **API surface** — what each method does. But agents fail less often on *what methods exist* than on *how to use them*: lifecycle order, pre-conditions, anti-patterns, "this method is for X, that one for Y." Those rules don't fit in docstrings (which describe single methods) and don't belong in a project-level `AGENTS.md` (which describes whole repos). They're class-level, and they need to travel with refactors.
+`agent_help()` covers two failure modes agents hit on real APIs:
 
-`agent_help()` gives them a home next to the code:
+1. **What exists.** The `## Public API` section is a curated list of current signatures pulled from runtime introspection — no hallucinated methods, no stale signatures from training data, no private members leaking in. If the agent reads this list first, it stops inventing methods that don't exist and stops calling real ones with the wrong arguments.
+2. **How to use it correctly.** Lifecycle order, pre-conditions, anti-patterns, *"this method is for X, that one for Y."* These don't fit in any single method's docstring and don't belong in a project-level `AGENTS.md` (which describes whole repos). They're class-level, and they need to travel with refactors. `__agent_notes__()` gives them a home next to the code.
+
+A concrete contrast:
 
 ```
-# help(sqlite3.Connection) — 200+ lines of terminal output:
+# help(sqlite3.Connection) — every inherited dunder, in source order:
 Help on class Connection in module sqlite3:
 
 class Connection(builtins.object)
@@ -143,10 +147,11 @@ class Connection(builtins.object)
  |  ...
  |  backup(self, target, /, *, pages=-1, progress=None, ...)
  |  blobopen(self, table, column, rowid, /, *, readonly=False, ...)
- |  ... (continues for 200+ more lines)
+ |  ... (no curation, no behavioral rules, no signal that backup() needs an
+ |        open target connection before being called)
 ```
 
-`agent_help(sqlite3.Connection)` produces a scannable summary instead — see Example 1 below. Notes from `__agent_notes__()` accumulate across inheritance. Class docs travel with the code in commits, reviews, and refactors. Drift gets caught in code review, not weeks later in a sidecar file.
+`agent_help(sqlite3.Connection)` produces a curated public-API list with current signatures and any class-level rules attached — see Example 1 below. Notes from `__agent_notes__()` accumulate across inheritance. Class docs travel with the code in commits, reviews, and refactors. Drift gets caught in code review, not weeks later in a sidecar file.
 
 The examples below demonstrate four ways to use `agent_help()`.
 
@@ -183,14 +188,14 @@ An agent-friendly wrapper around sqlite3.Connection.
 
 ## Public API
 
-- `backup(/, target, *, pages=-1, progress=None, name='main', sleep=0.25)` method: Makes a backup of the database.
+- `backup(target, *, pages=-1, progress=None, name='main', sleep=0.25)` method: Makes a backup of the database.
 - ...
-- `close(/)` method: Close the database connection.
-- `commit(/)` method: Commit any pending transaction to the database.
+- `close()` method: Close the database connection.
+- `commit()` method: Commit any pending transaction to the database.
 - ...
 - `execute(...)` method: Executes an SQL statement.
 - ...
-- `rollback(/)` method: Roll back to the start of any pending transaction.
+- `rollback()` method: Roll back to the start of any pending transaction.
 - ...
 
 ## Agent usage rules
@@ -359,7 +364,7 @@ print(agent_help(RateLimiter))
 
 ## Example 4: Any class — no setup required
 
-Even without the mixin or duck-typing, `agent_help()` still generates compact, structured Markdown from introspection. If the class (or any class in its MRO) defines `__agent_notes__()`, those notes are auto-appended too — no mixin required. The output is still more agent-friendly than `help()`.
+Even without the mixin or duck-typing, `agent_help()` still generates structured Markdown from introspection — a curated public-API list with current signatures, free of inherited dunders and MRO clutter. If the class (or any class in its MRO) defines `__agent_notes__()`, those notes are auto-appended too — no mixin required.
 Full example: [`examples/any_class.py`](examples/any_class.py).
 
 ```python
@@ -369,7 +374,7 @@ from agent_readable import agent_help
 print(agent_help(logging.Logger))
 ```
 
-`help(logging.Logger)` produces **217 lines** of output. `agent_help(logging.Logger)` produces a compact, scannable summary:
+Compare what `agent_help(logging.Logger)` returns to what `help(logging.Logger)` does — the former lists only the public methods you'd actually call, with their current signatures and docstring summaries:
 
 ````
 # Logger
@@ -404,9 +409,9 @@ Instances of the Logger class represent a single logging channel. A
 
 No mixin, no duck-typing — just pass any class to `agent_help()`.
 
-## Example 5: Modules
+## Example 5: Modules, functions, and methods
 
-`agent_help()` also works on modules — it generates a summary with the module docstring, public functions, and classes. Full example: [`examples/module_support.py`](examples/module_support.py).
+`agent_help()` also works on modules — it generates a summary with the module docstring, public functions, and classes. Full example: [`examples/modules_and_functions.py`](examples/modules_and_functions.py).
 
 ```python
 import sys
@@ -422,14 +427,16 @@ Output:
 
 ## Purpose
 
-Example: Using agent_help() on modules.
+Example: Using agent_help() on modules, functions, and methods.
 
-Demonstrates both shapes of module support:
+Demonstrates non-class targets:
   1. A custom module (this file itself).
   2. A stdlib module (pathlib).
+  3. A function (connect, defined below).
+  4. A method (Query.execute, defined below).
 
-Run this file to see both outputs:
-    python examples/module_support.py
+Run this file to see all outputs:
+    python examples/modules_and_functions.py
 
 ## Public API
 
@@ -445,7 +452,7 @@ Run this file to see both outputs:
 - If usage is ambiguous, prefer the simplest documented usage pattern.
 ````
 
-You can also pass any stdlib or third-party module — same `module_support.py` shows it.
+You can also pass any stdlib or third-party module — same `modules_and_functions.py` shows it.
 
 ```python
 import pathlib
@@ -469,20 +476,13 @@ operating systems.
 
 ## Public API
 
-- `DirEntryInfo` class: Implementation of pathlib.types.PathInfo that provides status
 - `Path` class: PurePath subclass that can make system calls.
-- `PathInfo` class: Implementation of pathlib.types.PathInfo that provides status
 - `PosixPath` class: Path subclass for non-Windows systems.
 - `PurePath` class: Base class for manipulating paths without I/O.
 - `PurePosixPath` class: PurePath subclass for non-Windows systems.
 - `PureWindowsPath` class: PurePath subclass for Windows systems.
 - `UnsupportedOperation` class: An exception that is raised when an unsupported operation is attempted.
 - `WindowsPath` class: Path subclass for Windows systems.
-- `copy_info(info, target, follow_symlinks=True)` function: Copy metadata from the given PathInfo to the given local path.
-- `copyfileobj(source_f, target_f)` function: Copy data from file-like object source_f to file-like object target_f.
-- `ensure_different_files(source, target)` function: Raise OSError(EINVAL) if both paths refer to the same file.
-- `ensure_distinct_paths(source, target)` function: Raise OSError(EINVAL) if the other path is within this path.
-- `magic_open(path, mode='r', buffering=-1, encoding=None, errors=None, newline=None)` function: Open the file pointed to by this path and return a file object, as
 
 ## Agent usage rules
 
@@ -492,7 +492,16 @@ operating systems.
 - If usage is ambiguous, prefer the simplest documented usage pattern.
 ````
 
-Modules support less customization than classes — there is no mixin inheritance or `__agent_notes__()`. You can override the auto-generated output entirely by setting a module-level `__agent_help__` attribute (callable or string), but this is discouraged since it replaces the auto-generated summary — signatures, purpose, and public API listing are all lost. Prefer clear docstrings on the module and its functions/classes instead.
+Modules support less customization than classes — there is no mixin inheritance or `__agent_notes__()`. You can override the auto-generated output entirely by setting a module-level `__agent_help__` attribute (callable or string), but this is discouraged since it replaces the auto-generated summary — signatures, purpose, and public API listing are all lost. Prefer clear docstrings on the module and its functions/classes instead. If the module defines `__all__`, that list is honored as the authoritative public API — including symbols re-exported from other modules.
+
+You can also pass a function or method directly — `agent_help()` renders the signature, full docstring, and usage rules. The output is close to `help()` for a single callable; the bigger wins are still on classes and modules.
+
+```python
+import pathlib
+from agent_readable import agent_help
+
+print(agent_help(pathlib.Path.read_text))
+```
 
 ```python
 import sys
@@ -515,20 +524,21 @@ python -m agent_readable agent_readable:AgentReadableMixin
 
 # Any module
 python -m agent_readable pathlib
+
+# A function or method
+python -m agent_readable json:dumps
+python -m agent_readable pathlib:Path.read_text
 ```
 
-Outputs agent-oriented documentation for the given class or module to stdout.
+Outputs agent-oriented documentation for the given class, module, function, or method to stdout.
 
 ## FAQ
 
 ### How does my agent know to call `agent_help()` instead of `help()`?
 
-Today, you tell it. Either:
-
-- Paste [`AGENT-PROMPT.md`](AGENT-PROMPT.md) into your conversation, or
-- Add it permanently to your repo's `AGENTS.md` / `CLAUDE.md` / `.cursor/rules` / equivalent instruction file.
+Install the agent **skill** that ships in this repo at [`skills/agent-readable/`](skills/agent-readable/). It follows the [Agent Skills open standard](https://agentskills.io) — adopted by Claude Code, Codex CLI (OpenAI), Gemini CLI (Google), GitHub Copilot, Cursor, JetBrains Junie, Goose, OpenCode, and 40+ other tools — so dropping the folder into your agent's skills directory (`~/.claude/skills/`, `~/.codex/skills/`, your editor's equivalent) is enough for the agent to discover it. The skill teaches the agent to install `agent-readable`, call `agent_help(target)` before writing code against a class, module, function, or method, and add `__agent_notes__()` (or improve docstrings) when authoring new public APIs.
 
-"You tell it" is the hard part of any new agent protocol. An MCP server (so MCP-aware clients auto-discover the tool) is on the roadmap.
+The folder lives next to the source code for now; a hub-published version (so you can install it through your harness's marketplace) is the next step on the roadmap.
 
 ### How is this different from `AGENTS.md` / `llms.txt` / Cursor rules?
 
@@ -556,7 +566,7 @@ Yes — `agent_help()` falls back to introspection (Example 4). You get a struct
 
 ## Keeping agent docs up to date
 
-Agent docs can go stale when classes change — new methods, changed behavior, removed APIs. Copy [`AGENT-PROMPT.md`](AGENT-PROMPT.md) into your coding agent's conversation, or permanently add it to your repo's `AGENTS.md`, `CLAUDE.md`, `.cursor/rules`, `.trae/rules`, `.github/copilot-instructions.md`, or equivalent instruction file. It tells your coding agent to run `agent_help()` before modifying a class, prefer docstrings over `__agent_notes__()`, and verify that docs stay accurate after changes.
+Agent docs can go stale when classes change — new methods, changed behavior, removed APIs. Install the skill at [`skills/agent-readable/`](skills/agent-readable/) into your agent (see the FAQ above for the install). It teaches your agent to run `agent_help()` before modifying a class, prefer docstrings over `__agent_notes__()`, and verify that the output stays accurate after changes.
 
 ## The `__agent_help__` protocol
 
@@ -574,13 +584,13 @@ Classes that define a `@classmethod` named `__agent_help__` returning a `str` ar
 
 The two dunders intentionally encode different composition rules:
 
-| Aspect          | `__agent_help__()`                              | `__agent_notes__()`                                                         |
-|-----------------|-------------------------------------------------|-----------------------------------------------------------------------------|
-| Semantics       | **Replacement** — returned string IS the output | **Additive** — appended to auto-generated docs                              |
-| Composition     | Single class wins (the one closest in MRO)      | Accumulated across the MRO; leaf class wins on conflict (header marks this) |
-| When to use     | Total control over the rendered text            | "Auto-doc + my extra do/don't rules"                                        |
-| Skipped when    | (always called if defined)                      | Skipped when a duck-typed `__agent_help__` is present (it owns the output)  |
-| Mixin required? | No — duck-typed classmethod is enough           | No — defining `__agent_notes__` on any class is enough                      |
+| Aspect          | `__agent_help__()`                              | `__agent_notes__()`                                                                           |
+| --------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| Semantics       | **Replacement** — returned string IS the output | **Additive** — appended to auto-generated docs                                                |
+| Composition     | Single class wins (the one closest in MRO)      | Accumulated across the MRO; leaf class wins on conflict (header marks this)                   |
+| When to use     | Total control over the rendered text            | "Auto-doc + my extra do/don't rules"                                                          |
+| Skipped when    | (always called if defined)                      | Skipped (with a `UserWarning`) when a custom `__agent_help__` is present (it owns the output) |
+| Mixin required? | No — duck-typed classmethod is enough           | No — defining `__agent_notes__` on any class is enough                                        |
 
 ## Class docstring hints
 
@@ -612,10 +622,11 @@ If a class inherits from `AgentReadableMixin`, coding agents should call `agent_
 
 ### `agent_help(obj)`
 
-Returns a string of agent-oriented documentation for a class, instance, or module.
+Returns a string of agent-oriented documentation for a class, instance, module, function, or method.
 
-- For classes and instances: if `__agent_help__()` is defined (via mixin or duck-typing), it is called and its return value is used verbatim — duck-typed implementations are responsible for their own formatting and notes are NOT auto-appended. Otherwise, auto-generated docs are produced from introspection, with `__agent_notes__()` from every class in the MRO appended automatically. If `__agent_help__()` raises, falls back to the auto-generated path (which does include notes).
-- For modules: if the module defines a `__agent_help__` attribute (callable or string), it is used. Otherwise, auto-generated docs are produced from the module docstring and its public functions and classes.
+- For classes and instances: if `__agent_help__()` is defined (via mixin or duck-typing), it is called and its return value is used verbatim — duck-typed implementations are responsible for their own formatting and notes are NOT auto-appended. If such a class also defines `__agent_notes__()`, a `UserWarning` is emitted because those notes are silently dropped (fold them into `__agent_help__()`, or drop the custom `__agent_help__()` to use the auto-doc path). Otherwise, auto-generated docs are produced from introspection, with `__agent_notes__()` from every class in the MRO appended automatically. If `__agent_help__()` raises, falls back to the auto-generated path (which does include notes).
+- For modules: if the module defines a `__agent_help__` attribute (callable or string), it is used. Otherwise, auto-generated docs are produced from the module docstring and its public functions and classes. When the module defines `__all__`, that list is the authoritative public API (so re-exported symbols are included); otherwise public members are discovered by introspection, skipping private names and anything defined outside the module.
+- For functions and methods (anything `inspect.isroutine` accepts): if the routine defines an `__agent_help__` attribute (callable or string), it is used. Otherwise, auto-generated docs render the signature, full docstring, and usage rules. A bound method's signature drops `self` and a classmethod's drops `cls`. If a callable `__agent_help__` raises, falls back to the auto-generated path.
 
 ## License
 

{agent_readable-0.1.0 → agent_readable-0.1.2}/README.md

@@ -1,21 +1,21 @@
 # agent-readable
 
-A lightweight Python protocol for exposing agent-oriented documentation from classes and modules.
+Stop coding agents from hallucinating your library's API. Ship the usage rules — lifecycle order, pre-conditions, anti-patterns — right next to your code.
+
+<!-- markdownlint-disable MD033 -->
+<p align="center">
+  <strong><code>logging.Logger</code> compared with <code>agent_help()</code> and <code>help()</code></strong><br>
+  <img src="docs/agent_help_vs_help.gif" alt="agent_help vs help">
+</p>
+<!-- markdownlint-enable MD033 -->
 
 ## Problem
 
 AI coding agents recognize established libraries from their training data, but they hallucinate when APIs change, when libraries are new, or when correct usage depends on rules that aren't visible from the API surface — pre-conditions, lifecycle order, anti-patterns, *"use `call()` for non-streaming, `stream()` for streaming."*
 
-Today there's nowhere to put those rules where an agent will reliably find them. Docstrings document the API surface, not behavioral rules. `AGENTS.md` and `llms.txt` work at project granularity, drift fast, and don't travel with refactors. `help()` is verbose and only describes interfaces.
-
-`agent-readable` adds two dunders — `__agent_help__` (full custom output) and `__agent_notes__` (additive guidance that accumulates across inheritance) — that live next to the code. Library authors annotate once; any agent that calls `agent_help(cls)` gets the rules.
-
-```text
-help(logging.Logger)        217 lines — every inherited method, dunder, and MRO detail.
-agent_help(logging.Logger)   56 lines — structured sections + any author notes.
-```
+Today there's nowhere to put those rules where an agent will reliably find them. Docstrings document the API surface, not behavioral rules. `AGENTS.md` and `llms.txt` work at project granularity, drift fast, and don't travel with refactors. `help()` only describes interfaces — and mixes inherited dunders and MRO detail in with the methods you actually want to use.
 
-The compactness is a side effect; the structure is the point.
+`agent-readable` adds two dunders — `__agent_help__` (full custom output) and `__agent_notes__` (additive guidance that accumulates across inheritance) — that live next to the code. Library authors annotate once; any agent that calls `agent_help(cls)` gets a curated public-API list with current signatures, the class's behavioral rules attached, and no inherited-dunder or MRO noise to wade through.
 
 ## Installation
 
@@ -98,12 +98,15 @@ Reads a value from a hardware sensor.
 
 ## Why it matters
 
-`help()` documents the **API surface** — what each method does. But agents fail less often on *what methods exist* than on *how to use them*: lifecycle order, pre-conditions, anti-patterns, "this method is for X, that one for Y." Those rules don't fit in docstrings (which describe single methods) and don't belong in a project-level `AGENTS.md` (which describes whole repos). They're class-level, and they need to travel with refactors.
+`agent_help()` covers two failure modes agents hit on real APIs:
 
-`agent_help()` gives them a home next to the code:
+1. **What exists.** The `## Public API` section is a curated list of current signatures pulled from runtime introspection — no hallucinated methods, no stale signatures from training data, no private members leaking in. If the agent reads this list first, it stops inventing methods that don't exist and stops calling real ones with the wrong arguments.
+2. **How to use it correctly.** Lifecycle order, pre-conditions, anti-patterns, *"this method is for X, that one for Y."* These don't fit in any single method's docstring and don't belong in a project-level `AGENTS.md` (which describes whole repos). They're class-level, and they need to travel with refactors. `__agent_notes__()` gives them a home next to the code.
+
+A concrete contrast:
 
 ```
-# help(sqlite3.Connection) — 200+ lines of terminal output:
+# help(sqlite3.Connection) — every inherited dunder, in source order:
 Help on class Connection in module sqlite3:
 
 class Connection(builtins.object)
@@ -117,10 +120,11 @@ class Connection(builtins.object)
  |  ...
  |  backup(self, target, /, *, pages=-1, progress=None, ...)
  |  blobopen(self, table, column, rowid, /, *, readonly=False, ...)
- |  ... (continues for 200+ more lines)
+ |  ... (no curation, no behavioral rules, no signal that backup() needs an
+ |        open target connection before being called)
 ```
 
-`agent_help(sqlite3.Connection)` produces a scannable summary instead — see Example 1 below. Notes from `__agent_notes__()` accumulate across inheritance. Class docs travel with the code in commits, reviews, and refactors. Drift gets caught in code review, not weeks later in a sidecar file.
+`agent_help(sqlite3.Connection)` produces a curated public-API list with current signatures and any class-level rules attached — see Example 1 below. Notes from `__agent_notes__()` accumulate across inheritance. Class docs travel with the code in commits, reviews, and refactors. Drift gets caught in code review, not weeks later in a sidecar file.
 
 The examples below demonstrate four ways to use `agent_help()`.
 
@@ -157,14 +161,14 @@ An agent-friendly wrapper around sqlite3.Connection.
 
 ## Public API
 
-- `backup(/, target, *, pages=-1, progress=None, name='main', sleep=0.25)` method: Makes a backup of the database.
+- `backup(target, *, pages=-1, progress=None, name='main', sleep=0.25)` method: Makes a backup of the database.
 - ...
-- `close(/)` method: Close the database connection.
-- `commit(/)` method: Commit any pending transaction to the database.
+- `close()` method: Close the database connection.
+- `commit()` method: Commit any pending transaction to the database.
 - ...
 - `execute(...)` method: Executes an SQL statement.
 - ...
-- `rollback(/)` method: Roll back to the start of any pending transaction.
+- `rollback()` method: Roll back to the start of any pending transaction.
 - ...
 
 ## Agent usage rules
@@ -333,7 +337,7 @@ print(agent_help(RateLimiter))
 
 ## Example 4: Any class — no setup required
 
-Even without the mixin or duck-typing, `agent_help()` still generates compact, structured Markdown from introspection. If the class (or any class in its MRO) defines `__agent_notes__()`, those notes are auto-appended too — no mixin required. The output is still more agent-friendly than `help()`.
+Even without the mixin or duck-typing, `agent_help()` still generates structured Markdown from introspection — a curated public-API list with current signatures, free of inherited dunders and MRO clutter. If the class (or any class in its MRO) defines `__agent_notes__()`, those notes are auto-appended too — no mixin required.
 Full example: [`examples/any_class.py`](examples/any_class.py).
 
 ```python
@@ -343,7 +347,7 @@ from agent_readable import agent_help
 print(agent_help(logging.Logger))
 ```
 
-`help(logging.Logger)` produces **217 lines** of output. `agent_help(logging.Logger)` produces a compact, scannable summary:
+Compare what `agent_help(logging.Logger)` returns to what `help(logging.Logger)` does — the former lists only the public methods you'd actually call, with their current signatures and docstring summaries:
 
 ````
 # Logger
@@ -378,9 +382,9 @@ Instances of the Logger class represent a single logging channel. A
 
 No mixin, no duck-typing — just pass any class to `agent_help()`.
 
-## Example 5: Modules
+## Example 5: Modules, functions, and methods
 
-`agent_help()` also works on modules — it generates a summary with the module docstring, public functions, and classes. Full example: [`examples/module_support.py`](examples/module_support.py).
+`agent_help()` also works on modules — it generates a summary with the module docstring, public functions, and classes. Full example: [`examples/modules_and_functions.py`](examples/modules_and_functions.py).
 
 ```python
 import sys
@@ -396,14 +400,16 @@ Output:
 
 ## Purpose
 
-Example: Using agent_help() on modules.
+Example: Using agent_help() on modules, functions, and methods.
 
-Demonstrates both shapes of module support:
+Demonstrates non-class targets:
   1. A custom module (this file itself).
   2. A stdlib module (pathlib).
+  3. A function (connect, defined below).
+  4. A method (Query.execute, defined below).
 
-Run this file to see both outputs:
-    python examples/module_support.py
+Run this file to see all outputs:
+    python examples/modules_and_functions.py
 
 ## Public API
 
@@ -419,7 +425,7 @@ Run this file to see both outputs:
 - If usage is ambiguous, prefer the simplest documented usage pattern.
 ````
 
-You can also pass any stdlib or third-party module — same `module_support.py` shows it.
+You can also pass any stdlib or third-party module — same `modules_and_functions.py` shows it.
 
 ```python
 import pathlib
@@ -443,20 +449,13 @@ operating systems.
 
 ## Public API
 
-- `DirEntryInfo` class: Implementation of pathlib.types.PathInfo that provides status
 - `Path` class: PurePath subclass that can make system calls.
-- `PathInfo` class: Implementation of pathlib.types.PathInfo that provides status
 - `PosixPath` class: Path subclass for non-Windows systems.
 - `PurePath` class: Base class for manipulating paths without I/O.
 - `PurePosixPath` class: PurePath subclass for non-Windows systems.
 - `PureWindowsPath` class: PurePath subclass for Windows systems.
 - `UnsupportedOperation` class: An exception that is raised when an unsupported operation is attempted.
 - `WindowsPath` class: Path subclass for Windows systems.
-- `copy_info(info, target, follow_symlinks=True)` function: Copy metadata from the given PathInfo to the given local path.
-- `copyfileobj(source_f, target_f)` function: Copy data from file-like object source_f to file-like object target_f.
-- `ensure_different_files(source, target)` function: Raise OSError(EINVAL) if both paths refer to the same file.
-- `ensure_distinct_paths(source, target)` function: Raise OSError(EINVAL) if the other path is within this path.
-- `magic_open(path, mode='r', buffering=-1, encoding=None, errors=None, newline=None)` function: Open the file pointed to by this path and return a file object, as
 
 ## Agent usage rules
 
@@ -466,7 +465,16 @@ operating systems.
 - If usage is ambiguous, prefer the simplest documented usage pattern.
 ````
 
-Modules support less customization than classes — there is no mixin inheritance or `__agent_notes__()`. You can override the auto-generated output entirely by setting a module-level `__agent_help__` attribute (callable or string), but this is discouraged since it replaces the auto-generated summary — signatures, purpose, and public API listing are all lost. Prefer clear docstrings on the module and its functions/classes instead.
+Modules support less customization than classes — there is no mixin inheritance or `__agent_notes__()`. You can override the auto-generated output entirely by setting a module-level `__agent_help__` attribute (callable or string), but this is discouraged since it replaces the auto-generated summary — signatures, purpose, and public API listing are all lost. Prefer clear docstrings on the module and its functions/classes instead. If the module defines `__all__`, that list is honored as the authoritative public API — including symbols re-exported from other modules.
+
+You can also pass a function or method directly — `agent_help()` renders the signature, full docstring, and usage rules. The output is close to `help()` for a single callable; the bigger wins are still on classes and modules.
+
+```python
+import pathlib
+from agent_readable import agent_help
+
+print(agent_help(pathlib.Path.read_text))
+```
 
 ```python
 import sys
@@ -489,20 +497,21 @@ python -m agent_readable agent_readable:AgentReadableMixin
 
 # Any module
 python -m agent_readable pathlib
+
+# A function or method
+python -m agent_readable json:dumps
+python -m agent_readable pathlib:Path.read_text
 ```
 
-Outputs agent-oriented documentation for the given class or module to stdout.
+Outputs agent-oriented documentation for the given class, module, function, or method to stdout.
 
 ## FAQ
 
 ### How does my agent know to call `agent_help()` instead of `help()`?
 
-Today, you tell it. Either:
-
-- Paste [`AGENT-PROMPT.md`](AGENT-PROMPT.md) into your conversation, or
-- Add it permanently to your repo's `AGENTS.md` / `CLAUDE.md` / `.cursor/rules` / equivalent instruction file.
+Install the agent **skill** that ships in this repo at [`skills/agent-readable/`](skills/agent-readable/). It follows the [Agent Skills open standard](https://agentskills.io) — adopted by Claude Code, Codex CLI (OpenAI), Gemini CLI (Google), GitHub Copilot, Cursor, JetBrains Junie, Goose, OpenCode, and 40+ other tools — so dropping the folder into your agent's skills directory (`~/.claude/skills/`, `~/.codex/skills/`, your editor's equivalent) is enough for the agent to discover it. The skill teaches the agent to install `agent-readable`, call `agent_help(target)` before writing code against a class, module, function, or method, and add `__agent_notes__()` (or improve docstrings) when authoring new public APIs.
 
-"You tell it" is the hard part of any new agent protocol. An MCP server (so MCP-aware clients auto-discover the tool) is on the roadmap.
+The folder lives next to the source code for now; a hub-published version (so you can install it through your harness's marketplace) is the next step on the roadmap.
 
 ### How is this different from `AGENTS.md` / `llms.txt` / Cursor rules?
 
@@ -530,7 +539,7 @@ Yes — `agent_help()` falls back to introspection (Example 4). You get a struct
 
 ## Keeping agent docs up to date
 
-Agent docs can go stale when classes change — new methods, changed behavior, removed APIs. Copy [`AGENT-PROMPT.md`](AGENT-PROMPT.md) into your coding agent's conversation, or permanently add it to your repo's `AGENTS.md`, `CLAUDE.md`, `.cursor/rules`, `.trae/rules`, `.github/copilot-instructions.md`, or equivalent instruction file. It tells your coding agent to run `agent_help()` before modifying a class, prefer docstrings over `__agent_notes__()`, and verify that docs stay accurate after changes.
+Agent docs can go stale when classes change — new methods, changed behavior, removed APIs. Install the skill at [`skills/agent-readable/`](skills/agent-readable/) into your agent (see the FAQ above for the install). It teaches your agent to run `agent_help()` before modifying a class, prefer docstrings over `__agent_notes__()`, and verify that the output stays accurate after changes.
 
 ## The `__agent_help__` protocol
 
@@ -548,13 +557,13 @@ Classes that define a `@classmethod` named `__agent_help__` returning a `str` ar
 
 The two dunders intentionally encode different composition rules:
 
-| Aspect          | `__agent_help__()`                              | `__agent_notes__()`                                                         |
-|-----------------|-------------------------------------------------|-----------------------------------------------------------------------------|
-| Semantics       | **Replacement** — returned string IS the output | **Additive** — appended to auto-generated docs                              |
-| Composition     | Single class wins (the one closest in MRO)      | Accumulated across the MRO; leaf class wins on conflict (header marks this) |
-| When to use     | Total control over the rendered text            | "Auto-doc + my extra do/don't rules"                                        |
-| Skipped when    | (always called if defined)                      | Skipped when a duck-typed `__agent_help__` is present (it owns the output)  |
-| Mixin required? | No — duck-typed classmethod is enough           | No — defining `__agent_notes__` on any class is enough                      |
+| Aspect          | `__agent_help__()`                              | `__agent_notes__()`                                                                           |
+| --------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| Semantics       | **Replacement** — returned string IS the output | **Additive** — appended to auto-generated docs                                                |
+| Composition     | Single class wins (the one closest in MRO)      | Accumulated across the MRO; leaf class wins on conflict (header marks this)                   |
+| When to use     | Total control over the rendered text            | "Auto-doc + my extra do/don't rules"                                                          |
+| Skipped when    | (always called if defined)                      | Skipped (with a `UserWarning`) when a custom `__agent_help__` is present (it owns the output) |
+| Mixin required? | No — duck-typed classmethod is enough           | No — defining `__agent_notes__` on any class is enough                                        |
 
 ## Class docstring hints
 
@@ -586,10 +595,11 @@ If a class inherits from `AgentReadableMixin`, coding agents should call `agent_
 
 ### `agent_help(obj)`
 
-Returns a string of agent-oriented documentation for a class, instance, or module.
+Returns a string of agent-oriented documentation for a class, instance, module, function, or method.
 
-- For classes and instances: if `__agent_help__()` is defined (via mixin or duck-typing), it is called and its return value is used verbatim — duck-typed implementations are responsible for their own formatting and notes are NOT auto-appended. Otherwise, auto-generated docs are produced from introspection, with `__agent_notes__()` from every class in the MRO appended automatically. If `__agent_help__()` raises, falls back to the auto-generated path (which does include notes).
-- For modules: if the module defines a `__agent_help__` attribute (callable or string), it is used. Otherwise, auto-generated docs are produced from the module docstring and its public functions and classes.
+- For classes and instances: if `__agent_help__()` is defined (via mixin or duck-typing), it is called and its return value is used verbatim — duck-typed implementations are responsible for their own formatting and notes are NOT auto-appended. If such a class also defines `__agent_notes__()`, a `UserWarning` is emitted because those notes are silently dropped (fold them into `__agent_help__()`, or drop the custom `__agent_help__()` to use the auto-doc path). Otherwise, auto-generated docs are produced from introspection, with `__agent_notes__()` from every class in the MRO appended automatically. If `__agent_help__()` raises, falls back to the auto-generated path (which does include notes).
+- For modules: if the module defines a `__agent_help__` attribute (callable or string), it is used. Otherwise, auto-generated docs are produced from the module docstring and its public functions and classes. When the module defines `__all__`, that list is the authoritative public API (so re-exported symbols are included); otherwise public members are discovered by introspection, skipping private names and anything defined outside the module.
+- For functions and methods (anything `inspect.isroutine` accepts): if the routine defines an `__agent_help__` attribute (callable or string), it is used. Otherwise, auto-generated docs render the signature, full docstring, and usage rules. A bound method's signature drops `self` and a classmethod's drops `cls`. If a callable `__agent_help__` raises, falls back to the auto-generated path.
 
 ## License