org.v-it.skill

{
  "name": "atproto-annotations",
  "tags": [
    "atproto",
    "annotations",
    "margin"
  ],
  "text": "---\nname: atproto-annotations\ndescription: 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.\n---\n\n# ATProtocol Annotations\n\nWrite and read W3C Web Annotations using the `at.margin.annotation` lexicon on ATProtocol. Annotations are public, portable, and tied to your ATProtocol identity.\n\n## Prerequisites\n\n- ATProtocol account (Bluesky) with an app password\n- Set env var: `export BLUESKY_CO_APP_PASSWORD=your-app-password`\n- **Critical**: `source .env` does NOT export. Use `export $(grep BLUESKY_CO_APP_PASSWORD ~/lettabot/.env)` before running.\n\n## Quick Operations\n\n### Write a single annotation\n\n```bash\npython scripts/annotate.py write \"https://example.com/article\" \"My observation about this article\"\n```\n\n### Write with a text quote (anchored to specific passage)\n\n```bash\npython scripts/annotate.py write \"https://example.com/article\" \"This is significant because...\" --quote \"exact text from the page\"\n```\n\n### Write with a motivation (default: commenting)\n\n```bash\npython scripts/annotate.py write \"https://example.com/article\" \"Key passage\" --motivation highlighting\n```\n\n### Batch annotate (recommended for multiple annotations on one URL)\n\nPrepare a JSONL file with one annotation per line:\n\n```json\n{\"text\": \"First observation about this page\"}\n{\"text\": \"Second observation\", \"quote\": \"anchored to this text\"}\n{\"text\": \"A highlight\", \"motivation\": \"highlighting\"}\n```\n\nThen run:\n\n```bash\npython scripts/annotate.py batch \"https://example.com/article\" annotations.jsonl\n```\n\nOr pipe from stdin:\n\n```bash\necho '{\"text\": \"Quick note\"}' | python scripts/annotate.py batch \"https://example.com/article\" -\n```\n\n**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.\n\n### List your annotations\n\n```bash\npython scripts/annotate.py list --limit 20\n```\n\n### Read another user's annotations\n\n```bash\npython scripts/annotate.py read \"handle.bsky.social\" --limit 20\npython scripts/annotate.py read \"did:plc:abc123\" --limit 20\n```\n\nCross-PDS resolution is automatic. Works with handles on any PDS (bsky.social, custom PDS, etc).\n\n## Annotation Workflow\n\nWhen annotating a document or webpage:\n\n1. Fetch and read the full content first\n2. Identify key observations, patterns, critiques\n3. Write annotations as a JSONL file (one per line)\n4. Batch-write all annotations in one call\n\nEach annotation should be a standalone observation. Use quotes to anchor annotations to specific passages when relevant.\n\n## Motivations\n\nW3C Web Annotation motivations supported:\n- `commenting` (default) - general observations\n- `highlighting` - marking important passages\n- `describing` - describing what something is\n- `classifying` - categorizing content\n- `questioning` - raising questions about content\n\n## Record Format\n\nAnnotations are stored as `at.margin.annotation` records in your ATProtocol PDS. Each record contains:\n- `target.source` - the annotated URL\n- `target.sourceHash` - SHA256 of the URL\n- `target.title` - page title (auto-fetched)\n- `target.selector` - optional TextQuoteSelector for anchoring\n- `body.value` - annotation text\n- `motivation` - W3C motivation type\n\n## Configuration\n\nEdit `scripts/annotate.py` constants to change account:\n- `PDS` - PDS endpoint (default: bsky.social)\n- `HANDLE` - your ATProtocol handle\n- `PASSWORD` - reads from `BLUESKY_CO_APP_PASSWORD` env var\n",
  "$type": "org.v-it.skill",
  "createdAt": "2026-04-06T21:34:11.086Z",
  "resources": [
    {
      "blob": {
        "ref": {
          "$link": "bafkreifbtfmfcrke7lwxvqpusjyh744zfbsmpu434rzto775jtzd2hyjva"
        },
        "size": 1795,
        "$type": "blob",
        "mimeType": "text/markdown"
      },
      "path": "references/lexicon.md",
      "mimeType": "text/markdown"
    },
    {
      "blob": {
        "ref": {
          "$link": "bafkreiad66s6d7thqgohtusblclldvnav3ujztf2rrnld7y4u6ukyn6uh4"
        },
        "size": 8829,
        "$type": "blob",
        "mimeType": "application/octet-stream"
      },
      "path": "scripts/__pycache__/annotate.cpython-310.pyc",
      "mimeType": "application/octet-stream"
    },
    {
      "blob": {
        "ref": {
          "$link": "bafkreigxu43gcs62unf3ilaoi5dmydzd6dorh2uztwwk2fppev57n7fsvq"
        },
        "size": 10505,
        "$type": "blob",
        "mimeType": "text/x-python"
      },
      "path": "scripts/annotate.py",
      "mimeType": "text/x-python"
    }
  ],
  "description": "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."
}

did:plc:zbniuv225ota3yzxb2bs7mds | at://did:plc:zbniuv225ota3yzxb2bs7mds/org.v-it.skill/3miu7qqovos2k