How do I install the Atproto Annotations skill?

Run npx skillmds@latest add just-cameron/atproto-annotations in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Atproto Annotations safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Atproto Annotations?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Atproto Annotations free to use?

Yes. Installing skills from SkillMD is free. This skill is licensed under MIT.

Who published Atproto Annotations?

just-cameron (@just-cameron) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Atproto Annotations by just-cameron

Name: Atproto Annotations
Author: just-cameron

Atproto Annotations

Write and read W3C Web Annotations on ATProtocol using the at.margin.annotation lexicon. Use when annotating URLs, writing reading notes on web pages, or building a public research trail. Supports single writes, batch writes via applyWrites, and reading annotations from any ATProtocol user. Triggers on annotate, annotation, margin, reading notes, or web annotation.

just-cameron 5cd48d2 3 files · 15.7 KB Updated Sep 17, 2026

File contents

ATProtocol Annotations

Write and read W3C Web Annotations using the at.margin.annotation lexicon on ATProtocol. Annotations are public, portable, and tied to your ATProtocol identity.

Prerequisites

ATProtocol account (Bluesky) with an app password
Set env var: export BLUESKY_CO_APP_PASSWORD=your-app-password
Critical: source .env does NOT export. Use export $(grep BLUESKY_CO_APP_PASSWORD ~/lettabot/.env) before running.

Quick Operations

Write a single annotation

python scripts/annotate.py write "https://example.com/article" "My observation about this article"

Write with a text quote (anchored to specific passage)

python scripts/annotate.py write "https://example.com/article" "This is significant because..." --quote "exact text from the page"

Write with a motivation (default: commenting)

python scripts/annotate.py write "https://example.com/article" "Key passage" --motivation highlighting

Batch annotate (recommended for multiple annotations on one URL)

Prepare a JSONL file with one annotation per line:

{"text": "First observation about this page"}
{"text": "Second observation", "quote": "anchored to this text"}
{"text": "A highlight", "motivation": "highlighting"}

Then run:

python scripts/annotate.py batch "https://example.com/article" annotations.jsonl

Or pipe from stdin:

echo '{"text": "Quick note"}' | python scripts/annotate.py batch "https://example.com/article" -

Why batch: Single annotations make 3 HTTP requests each (auth + title fetch + create). Batch makes 3 total regardless of count (1 auth + 1 title + 1 applyWrites). For 10 annotations: 3 requests vs 30.

List your annotations

python scripts/annotate.py list --limit 20

Read another user's annotations

python scripts/annotate.py read "handle.bsky.social" --limit 20
python scripts/annotate.py read "did:plc:abc123" --limit 20

Cross-PDS resolution is automatic. Works with handles on any PDS (bsky.social, custom PDS, etc).

Annotation Workflow

When annotating a document or webpage:

Fetch and read the full content first
Identify key observations, patterns, critiques
Write annotations as a JSONL file (one per line)
Batch-write all annotations in one call

Each annotation should be a standalone observation. Use quotes to anchor annotations to specific passages when relevant.

Motivations

W3C Web Annotation motivations supported:

commenting (default) - general observations
highlighting - marking important passages
describing - describing what something is
classifying - categorizing content
questioning - raising questions about content

Record Format

Annotations are stored as at.margin.annotation records in your ATProtocol PDS. Each record contains:

target.source - the annotated URL
target.sourceHash - SHA256 of the URL
target.title - page title (auto-fetched)
target.selector - optional TextQuoteSelector for anchoring
body.value - annotation text
motivation - W3C motivation type

Configuration

Edit scripts/annotate.py constants to change account:

PDS - PDS endpoint (default: bsky.social)
HANDLE - your ATProtocol handle
PASSWORD - reads from BLUESKY_CO_APP_PASSWORD env var

---name: atproto-annotationsdescription: Write and read W3C Web Annotations on ATProtocol using the at.margin.annotation lexicon. Use when annotating URLs, writing reading notes on web pages, or building a public research trail. Supports single writes, batch writes via applyWrites, and reading annotations from any ATProtocol user. Triggers on annotate, annotation, margin, reading notes, or web annotation.license: MIT---# ATProtocol AnnotationsWrite and read W3C Web Annotations using the `at.margin.annotation` lexicon on ATProtocol. Annotations are public, portable, and tied to your ATProtocol identity.## Prerequisites- ATProtocol account (Bluesky) with an app password- Set env var: `export BLUESKY_CO_APP_PASSWORD=your-app-password`- **Critical**: `source .env` does NOT export. Use `export $(grep BLUESKY_CO_APP_PASSWORD ~/lettabot/.env)` before running.## Quick Operations### Write a single annotation```bashpython scripts/annotate.py write "https://example.com/article" "My observation about this article"```### Write with a text quote (anchored to specific passage)```bashpython scripts/annotate.py write "https://example.com/article" "This is significant because..." --quote "exact text from the page"```### Write with a motivation (default: commenting)```bashpython scripts/annotate.py write "https://example.com/article" "Key passage" --motivation highlighting```### Batch annotate (recommended for multiple annotations on one URL)Prepare a JSONL file with one annotation per line:```json{"text": "First observation about this page"}{"text": "Second observation", "quote": "anchored to this text"}{"text": "A highlight", "motivation": "highlighting"}```Then run:```bashpython scripts/annotate.py batch "https://example.com/article" annotations.jsonl```Or pipe from stdin:```bashecho '{"text": "Quick note"}' | python scripts/annotate.py batch "https://example.com/article" -```**Why batch**: Single annotations make 3 HTTP requests each (auth + title fetch + create). Batch makes 3 total regardless of count (1 auth + 1 title + 1 applyWrites). For 10 annotations: 3 requests vs 30.### List your annotations```bashpython scripts/annotate.py list --limit 20```### Read another user's annotations```bashpython scripts/annotate.py read "handle.bsky.social" --limit 20python scripts/annotate.py read "did:plc:abc123" --limit 20```Cross-PDS resolution is automatic. Works with handles on any PDS (bsky.social, custom PDS, etc).## Annotation WorkflowWhen annotating a document or webpage:1. Fetch and read the full content first2. Identify key observations, patterns, critiques3. Write annotations as a JSONL file (one per line)4. Batch-write all annotations in one callEach annotation should be a standalone observation. Use quotes to anchor annotations to specific passages when relevant.## MotivationsW3C Web Annotation motivations supported:- `commenting` (default) - general observations- `highlighting` - marking important passages- `describing` - describing what something is- `classifying` - categorizing content- `questioning` - raising questions about content## Record FormatAnnotations are stored as `at.margin.annotation` records in your ATProtocol PDS. Each record contains:- `target.source` - the annotated URL- `target.sourceHash` - SHA256 of the URL- `target.title` - page title (auto-fetched)- `target.selector` - optional TextQuoteSelector for anchoring- `body.value` - annotation text- `motivation` - W3C motivation type## ConfigurationEdit `scripts/annotate.py` constants to change account:- `PDS` - PDS endpoint (default: bsky.social)- `HANDLE` - your ATProtocol handle- `PASSWORD` - reads from `BLUESKY_CO_APP_PASSWORD` env var

Frequently asked questions