| name | research-lib |
| description | Research a library and create comprehensive documentation in .agents/docs/libraries/. |
| disable-model-invocation | true |
Research Library
Research $ARGUMENTS and create documentation in .agents/docs/libraries/.
Scope: this skill produces documentation only. It never edits source code
and never edits a dependency manifest or lockfile — if the research implies a
version bump, report it as an action item instead of making it.
1. Resolve the Document Path
Derive the path once, from the script, and reuse the value everywhere below.
$ARGUMENTS is raw user wording (FastAPI, ruamel.yaml, @scope/pkg); the
script normalizes it the same way lib_inventory.py normalizes a declared
dependency, so the doc filename and the dependency name always match.
python3 .agents/skills/_shared/workspace.py --skill research-lib \
--title "$ARGUMENTS" --create
Emits {ok, skill, slug, paths: {lib_doc}, dirs, created, artifacts, verify}.
Exit 0 on success, 1 on a bad argument. Use paths.lib_doc verbatim from here
on — never re-derive it by hand, and never substitute $ARGUMENTS.md.
2. Resolve the Version This Project Uses
The declared and locked versions are facts with one correct answer, so read
them instead of asking the web:
python3 .agents/skills/update-lib-docs/lib_inventory.py --library "$ARGUMENTS"
The dependencies array carries {name, declared_spec, declared_in, locked_version, locked_in, ecosystem}. > **Version Checked**: records
locked_version when a lockfile pins one, otherwise the version satisfying
declared_spec. If dependencies is empty the library is not (yet) a
dependency of this project — record the version you are documenting against and
say so in ## Constraints & Notes.
Exit codes: 0 ok, 1 bad argument, 2 a manifest could not be parsed
(manifest_errors), 3 a library doc could not be read (read_error). On a
non-zero exit, stop and report — do not fill the version in from a web search.
Newer upstream releases are research findings, not the project's version: note
them under ## Constraints & Notes as an upgrade consideration. The blockquote
is the only place a version number lives.
Research Items
Primary Tool: General-Purpose Subagent (Opus)
Use general-purpose-opus with WebSearch/WebFetch for comprehensive library
research. Pass the resolved path and version into the prompt:
Agent tool:
subagent_type: "general-purpose-opus"
prompt: |
Research: {library}. Find official documentation, key features,
constraints, best practices, known issues, and usage patterns.
Use WebSearch and WebFetch to gather information.
The version this project uses is {locked_version or declared_spec};
document against that version, and note newer releases separately.
Save results to {paths.lib_doc} using the template in
.agents/skills/research-lib/SKILL.md.
List every URL you consulted under ## References.
Return concise summary.
Fallback: WebSearch/WebFetch
If the subagent is unavailable, verify via manual web search:
- Official documentation
- GitHub README
- PyPI / npm page
- Latest release notes
Record every source you used in ## References; a research note whose sources
are only in the conversation cannot be audited later.
Content to Document
-
Basic Information
- Official name, license
- Official URL
- Installation command
-
Core Features
- Main features
- Basic usage (code examples)
-
Constraints & Notes
- Known limitations
- Conflicts with other libraries
- Performance characteristics
- Async/sync considerations
-
Usage Patterns in This Project
- Recommended usage
- Patterns to avoid
-
Troubleshooting
- Common errors and solutions
Output Location
paths.lib_doc from step 1 — the only derivation of this path.
Documentation Template
# {Library Name}
> **Last Updated**: {YYYY-MM-DD}
> **Version Checked**: {declared or locked version in this project}
## Overview
- **License**: {license}
- **Official URL**: {url}
- **Installation**: `{install command}`
## Core Features
{Description of main features}
## Basic Usage
```python
{Code example}
Constraints & Notes
- {Limitation 1}
- {Limitation 2}
Recommended Patterns
Do
{Good pattern}
Don't
{Anti-pattern}
Troubleshooting
{Error message}
Cause: {cause}
Solution: {solution}
References
The `> **Last Updated**` / `> **Version Checked**` blockquote is mandatory, not
decoration: `lib_inventory.py` parses exactly those two lines, and a doc without
them is invisible to `update-lib-docs` — never stale, never undocumented, never
maintained.
## Validate the Document
Both checks are gates. Do not report completion until both exit 0.
```bash
python3 .agents/skills/_shared/validate_doc.py --contract lib-doc \
--file <paths.lib_doc>
python3 .agents/skills/_shared/workspace.py --skill research-lib \
--slug <slug> --verify
validate_doc.py exit codes:
- 1 — the file does not exist or could not be read. The delegated subagent
did not write it (or wrote it elsewhere); the payload has no
sections_missing. Re-delegate with paths.lib_doc; do not hand-edit a
different path.
- 2 — the file exists but violates the contract.
sections_missing lists
absent ## sections (Overview, Core Features, Constraints & Notes,
References) and metadata_missing lists absent metadata lines
(Last Updated, Version Checked). Fill those in and re-run.
workspace.py --verify exit 2 with verify.empty containing lib_doc means
the file exists but is a stub (under 20 non-whitespace characters) — a summary
was returned without real content.
