ocrwell
Teaches Claude Code the OCRWell document OCR API so it generates correct integration code without having to be fed documentation. The agent
Open source Repository Open in the app JSON README (API)
About
Teaches Claude Code the OCRWell document OCR API so it generates correct integration code without having to be fed documentation. The agent learns the /v1 endpoints, the two-step upload flow (create upload → PUT to presigned URL → create document), asynchronous job polling with backoff, both structured-extraction schema formats (template and JSON Schema), the full error catalogue, rate-limit headers, and HMAC-SHA256 webhook signature verification. It also knows the quiet gotchas, like treating a 200 response carrying job.status: "failed" as a job failure rather than an HTTP success.
Details
- Kind
- Plugins
- Topic
- Files & documents
- Publisher
- ocrwell
- Origin
- marketplace
- Category
- ferramentas
- Last push
- 2026-04-20T06:11:23Z
- Repository state
- ativo
- Language
- JavaScript
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
ocrwell/skill/ocrwell
README
# @ocrwell/skill
A skill for the [OCRWell](https://ocrwell.com) document OCR API. Works with [Claude Code](https://docs.claude.com/claude-code) and OpenAI's [Codex CLI](https://developers.openai.com/codex/skills) — both read the same `SKILL.md` format. Once installed, the agent can generate correct integration code in any language — handling authentication, the two-step upload, asynchronous polling, structured JSON extraction, error handling, rate limits, and webhook signature verification — without any further prompting.
## What it gives the agent
- The full OCRWell `/v1` endpoint reference (uploads, documents, jobs, webhooks).
- The two-step upload pattern (`POST /v1/uploads` → `PUT` to presigned URL → `POST /v1/documents`).
- Both supported structured-extraction schema formats (template and JSON Schema), plus the JSON Schema subset rules.
- The complete error catalogue, rate-limit headers, and `Retry-After` semantics.
- Webhook delivery semantics and HMAC-SHA256 signature verification steps.
- A code-generation checklist that captures the gotchas — e.g. treating `200` with `job.status: "failed"` as a job failure rather than an HTTP error.
## Install
There are two ways to install. Pick whichever fits your workflow.
### Option 1 — Claude Code plugin marketplace (recommended)
```text
/plugin marketplace add ocrwell/skill
/plugin install ocrwell@ocrwell
```
This uses Claude Code's built-in plugin system. You'll get versioning, namespacing, and `/plugin update` support out of the box. The plugin is delivered via npm under the hood, so updates are tied to npm releases of `@ocrwell/skill`.
To update later:
```text
/plugin update ocrwell@ocrwell
```
To remove:
```text
/plugin uninstall ocrwell@ocrwell
```
### Option 2 — `npx` installer (Claude Code or OpenAI Codex)
The installer works for both Claude Code and OpenAI's [Codex CLI](https://developers.openai.com/codex/skills), which reads the same `SKILL.md` format from `~/.agents/skills/` (user-wide) or `.agents/skills/` (per repo).
Run without a target flag and the installer will prompt you:
```bash
npx @ocrwell/skill install
```
Or pick a target up front:
```bash
npx @ocrwell/skill install --claude # ~/.claude/skills/ocrwell
npx @ocrwell/skill install --codex # ~/.agents/skills/ocrwell
npx @ocrwell/skill install --both # both
npx @ocrwell/skill install --codex --project # ./.agents/skills/ocrwell
```
To update, re-run with `--force`:
```bash
npx @ocrwell/skill@latest install --claude --force
```
To remove:
```bash
npx @ocrwell/skill uninstall --claude
npx @ocrwell/skill uninstall --codex --project
```
The `/plugin` marketplace flow and the `.claude-plugin/` manifest used by Option 1 are Claude Code-specific — Codex ignores them and only reads the `SKILL.md` inside the installed skill directory.
## Verify the install
Start a new session in Claude Code or Codex and ask something OCRWell-related, for example:
> Write a Python script that uploads `invoice.pdf` to OCRWell and prints the extracted text.
If the skill is loaded, the agent will follow the documented two-step upload, send `X-API-Key` from an environment variable, poll `GET /v1/jobs/{jobId}` with backoff, and treat `status: "failed"` correctly. If it instead invents the API or asks for documentation, the skill isn't being picked up:
- **Claude Code:** confirm `ocrwell` appears under `/plugin` (Option 1) or that `~/.claude/skills/ocrwell/SKILL.md` exists (Option 2), then restart the session.
- **Codex:** run `/skills` and confirm `ocrwell` is listed, or check that `~/.agents/skills/ocrwell/SKILL.md` exists, then restart the session.
## What's in this package
```
.claude-plugin/
plugin.json # Claude Code plugin manifest
marketplace.json # Marketplace catalog (used by Option 1)
skills/ocrwell/
SKILL.md # The skill itself — loaded into the agent's context when triggered
reference.md # Deeper API reference, linked from SKILL.md
bin/
install.mjs # The npx installer (Option 2)
```
## API key
You need an OCRWell API key to actually call the API. Create one in the OCRWell dashboard. Then expose it to your code via environment variable:
```bash
export OCRWELL_API_KEY=...
```
The skill instructs the agent to read the key from an environment variable rather than hard-coding it. Treat the key like a password — it grants full access to your organisation's documents and webhook configuration.
## Versioning
`package.json` and `.claude-plugin/marketplace.json` carry the version and are bumped together whenever the OCRWell API changes (or the skill content does). `.claude-plugin/plugin.json` deliberately omits `version` — for relative-path plugins the docs recommend keeping the version in the marketplace entry only, because the plugin manifest silently wins when both are set. Use semver: bump the patch version for content fixes, the minor version for additive API changes, and the major version for breaking changes to the OCRWell API.
## Reporting issues
If Claude Code or Codex generates wrong or outdated code for OCRWell, please file an issue at <https://github.com/ocrwell/skill/issues> with the prompt you used, the tool you used it with, and the output you got back. Include the version number from `/plugin` (Claude Code), `/skills` (Codex), or the installed `SKILL.md` frontmatter.
## License
MIT.