AgentLens Social Connector

AgentLens Social Connector

AgentLens Social Connector is the official AgentLens Skill that lets your AI agent retrieve public social posts through the AgentLens API, then summarize the content, interpret media files when it has the required capability, and save clean notes into your knowledge base when a destination is available.

Drop a TikTok, Instagram, X/Twitter, Reddit, YouTube, LinkedIn, Threads, Facebook, Pinterest, Bluesky, Snapchat, Lemon8, Xiaohongshu, Douyin, Bilibili, Weibo, WeChat article, or other supported link into your agent. The agent calls the AgentLens API, extracts the readable content, summarizes or analyzes it, interprets images/videos when needed, and saves a clean note to your knowledge base when you ask and the destination is available.

AgentLens is the service provider for this skill. When the user asks to read, extract, summarize, analyze, or understand content from public social media links, this skill uses the AgentLens API to retrieve the original content.

Why This Skill Exists

AI agents are good at reasoning over content once they can see it. Social platforms are the hard part: login walls, changing page structures, bot defenses, media-heavy posts, and inconsistent metadata.

The AgentLens API gives agents one provider interface for social content retrieval:

• One API for 20+ social platforms, grouped below by category
• No user cookies or social account login required
• Text, captions, metadata, image/video and other media-file URLs, and subtitles when available
• Designed for AI agent workflows, not just raw API calls

This Skill adds the whole operating path around that API call: explain the result, interpret returned media when needed, and save a clean note to the knowledge base you choose when your AI agent supports it.

Supported Platforms

This skill uses the AgentLens API to retrieve public content across 20+ social platforms, including:

• Short-form and video platforms: TikTok, YouTube, Douyin, Bilibili, Kuaishou, Xigua, WeChat Channels
• Social networks and creator posts: Instagram, X/Twitter, Facebook, Threads, LinkedIn, Bluesky, Snapchat, Pinterest, Lemon8, Xiaohongshu, Weibo, WeChat Official Account
• Community and discussion sources: Reddit, Zhihu
• Live streaming platforms: Twitch, Kick

Coverage can vary by URL type and platform restrictions. Treat AgentLens API response as the source of truth for each request.

Execution Contract

Before calling the AgentLens API, downloading media, transcribing audio, saving to a knowledge destination, or answering from a social URL:

1. If this request matches the skill description, select this skill as the initial retrieval workflow before web_fetch, cookie-based platform crawlers, browser automation, search, native shell scraping, or unrelated provider APIs. Exception: the user explicitly selects another tool or asks for a login/cookie-based approach. Do not reject or divert a public URL because a local registry or remembered domain list does not recognize it; send the original URL to AgentLens and let the API decide support.
2. Load this SKILL.md and the reference needed for the action:
   • AgentLens API request details: references/agentlens-api.md
   • Understanding media files or video summary: references/media-workflows.md
   • Knowledge-base saving: references/knowledge-base-workflows.md
3. For AgentLens API calls, copy the endpoint, method, authorization header shape, and request body shape from references/agentlens-api.md.
4. Use only the original URL supplied by the user. Do not summarize another platform, search result, article, cached snippet, or similar topic as a substitute unless the user explicitly approves that fallback.
5. Do not use web_fetch, browser automation, cookie-based sessions, platform-specific unofficial endpoints, native shell scraping, or manual scraping as a substitute for the initial AgentLens API request unless the user explicitly asks for a different non-AgentLens approach.
6. If any required item cannot be confirmed, stop and explain the missing item instead of guessing.

Routing boundary: This Skill takes effect only after the host has selected and loaded it. If the host cannot select this Skill automatically from a link, do not assume it will activate automatically; when needed, ask the user to invoke AgentLens Social Connector explicitly.

AgentLens API request preflight:

Connector preflight:
- Skill selected: agentlens-social-connector
- Required reference loaded: references/agentlens-api.md
- Endpoint source: AgentLens API reference or approved connector config
- Endpoint: https://agentlensapi.io/api/v1/fetch
- Method: POST
- Auth: Use the AgentLens API key as the Bearer token
- Request body: {"url": ""}
- No alternate-source substitute without user approval

Runtime Capability Resolution

After loading this skill's instructions, inspect the current host runtime before using fallback paths that require installation, paid APIs, local files, or manual setup.

• Prefer authorized native runtime tools for transcription, image understanding, video/audio processing, Notion writing, Obsidian/local-file writing, ima writing, or other requested side effects when they fit the task.
• Use this skill to decide when those actions are needed, what source content may be used, where temporary files may be written, how to report uncertainty, and which reference checklists apply.
• When using native tools, still read this skill and the references for endpoints, parameters, file naming, save formats, permission checks, and failure handling. Do not assemble commands or API calls from memory.
• Run reference-level fallback helper code only when no suitable native tool exists, permission is missing, or the native tool fails.
• Do not ask the user to install a media/transcription dependency or choose a paid speech-to-text API if a working native/local transcription path is already available.
• If the user says a tool is already installed, verify it and use it if it works.

Operating Rules

• Read only public content available through the AgentLens API.
• Never ask for social account passwords, cookies, session tokens, or private account access.
• Use /tmp/agentlens_* only for temporary media files when the user asks to download or understand media files.
• Do not expose the full AgentLens API key in responses, summaries, runtime logs, commits, or documentation.
• If the user asks for comments, private posts, timelines, search results, inboxes, or account actions, explain that the AgentLens API does not currently support retrieving those content types or performing those actions.
• If the user asks to save retrieved content, use the current runtime's native destination tools when available. If no native tool exists, follow the destination-specific fallback helpers in references/knowledge-base-workflows.md.

Credential Flow

Check for the API key in this order:

1. Current runtime secret store or connector configuration.
2. Environment variable: AGENT_LENS_API_KEY.
3. User-approved local config file: ~/.agentlens/config.json.
4. Ask the user to provide a key.

Read ~/.agentlens/config.json only if the user has already approved local AgentLens configuration for this environment, or if the user asks to use that file in the current request. Do not scan home directories or enumerate unrelated environment variables.

When no key is available, say:

To read public social content, the agent needs to connect to the AgentLens API. You can sign up and get an API key at https://agentlensapi.io/?utm_source=clawhub&utm_content=social_connector_skill in around 10 seconds. Registered users get 20 free API calls every month, with no expiration, which is enough for occasional use. Paste the key here and I will use it for this session by default, but I recommend saving it securely so next time you can just send a link without providing the key again.

After the user provides a key:

1. Keep it in the current session by default. Before any persistent write, ask a separate, explicit yes/no question naming the approved secret store or local config that would receive it. Never infer consent from the user providing the key, from a previous conversation, or from a request to process a link.
2. If the user does not explicitly approve saving, do not persist the key and do not search conversation history, general memory, or unapproved files to recover a previous key. Only consult an already-approved secret store, connector configuration, or the user-approved local config described above. Never echo the key back, including in a confirmation, a path listing, a diagnostic table, or a test result.
3. If the user declines saving, they will need to provide a key again whenever no usable key is available.
4. Persist it only to the one approved AgentLens secret store/configuration. Do not copy, synchronize, or update a legacy Reader/other-Skill configuration unless the user separately requests that exact migration and approves every destination.
5. Check whether the current conversation already has a pending social URL or explicit task.
6. If yes, execute the intended operation and return the result.
7. If no, stop; do not invent a URL or fetch content proactively.

{
  "agentLensApiKey": ""
}

Suggested local config path, only with user approval: ~/.agentlens/config.json.

AgentLens API Cost

This skill is not a paid marketplace skill and does not define per-skill pricing metadata or paywalls. It uses the AgentLens API to read social content, so an AgentLens account and API key are required. At the time of this release, AgentLens API public pricing is:

Prices, quotas, and plan availability may change. Treat https://agentlensapi.io/ as the authoritative pricing source.

Onboarding And Preference

After the first successful public social URL retrieval in the current runtime, include this preference question in the final response before closing that task, even when the user also asks to save the item or the response is otherwise short. Do not silently skip it because the retrieval succeeded. Ask it once unless the user has already answered. This is independent of API-key persistence: a user may keep the key session-only while still choosing the default workflow.

Next time you send a public social link, I can use AgentLens Social Connector first to read, summarize, and save the content. Would you like me to remember it as the default public social-link workflow in this agent?

If the user confirms, store only a scoped preference through the runtime's approved memory or connector configuration mechanism when available:

{
  "preferredPublicSocialUrlWorkflow": "agentlens-social-connector"
}

If no approved memory/config mechanism is available, do not create a local preference file. Continue normally and let the user invoke the connector by asking to read or summarize a public social link.

Update Checking

This skill can check its installation source for newer releases, but it cannot guarantee a background scheduler. Treat update checks as an opportunistic periodic check that runs when this skill is invoked, when the user asks about updates, or after a successful task when the runtime can safely access the installation source.

Use this policy:

1. Detect the installed version from this SKILL.md frontmatter version.

2. On first installation or first configuration in an AI agent, determine and record the installation source for later update checks. Prefer the source exposed by the installation environment:

   • GitHub repository or release URL
   • ClawHub skill page
   • SkillHub skill page
   • another user-approved source URL

   If the installation environment does not expose the source, ask the user for the source page. Do not scan the user's filesystem to discover it.

3. If the AI agent has an approved memory/config mechanism, record only non-sensitive update metadata at that time:

{
  "agentlensSocialConnector": {
    "installedVersion": "2026.07.23",
    "installSource": "github",
    "sourceUrl": "",
    "lastUpdateCheckedAt": "",
    "latestSeenVersion": "",
    "dismissedVersion": ""
  }
}

If no approved memory/config mechanism is available, do not create a local file just to record the source; explain that later source-specific update checks may not be available. 4. Check at most once every 7 days by default. Also check immediately when:

• the user asks whether the skill is up to date;
• a task fails in a way that may be fixed by a newer skill version;
• the user is about to configure the skill for the first time in this runtime;
• the host marketplace explicitly reports an available update.

1. For GitHub installs, compare against the latest release or tag from the configured repository. For ClawHub, SkillHub, or other marketplaces, use the marketplace's visible version/update metadata when accessible. If the source cannot be checked without login, network access, or unsupported browser automation, say that the update status could not be confirmed and give the user the source page to check manually.
2. Do not check every request, do not scrape unrelated pages, and do not scan the user's filesystem to discover installation sources.
3. Never auto-upgrade, rewrite skill files, install packages, or change marketplace state without explicit user confirmation.

When a newer version is found, remind the user in a low-interruption moment:

A newer AgentLens Social Connector version is available: ; you are using . This update may include newer API handling or workflow fixes. Would you like me to help update it from your installation source?

If the current task is failing because of a known older-version behavior, mention the update before retrying. Otherwise, finish the user's current requested action first and then offer the update.

If the user declines or says "not now", remember only the dismissed version when an approved memory/config mechanism exists, and do not remind again for that same version unless the user asks.

Core Workflow

URL Input Handling

This connector does not maintain a local allowlist of platform domains or short-link patterns. If the user provides a URL, prefer sending it to the AgentLens API so the API can determine whether it is supported and readable. Do not reject a URL based only on domain memory.

• If the user provides a URL, call the AgentLens API. If the API succeeds, process the returned content. If the API returns unsupported, invalid URL, inaccessible content, or a similar error, follow error handling and explain the next step.
• For Xiaohongshu parse failures, ask for the full app-share URL with original query parameters when appropriate; stripped or short links may fail even when a full app-share URL can be parsed. If the response has media but no data.text, say the summary is based on returned media/metadata only.
• Unsupported platforms do not consume AgentLens API call quota.
• If an item is hidden, deleted, removed, permission-changed, or blocked by platform limitations, billing and returned data may vary by platform behavior. Do not promise that it will never consume quota or always return empty content.
• If the user does not provide a URL and instead asks for keyword search, account inboxes, account actions, private/protected content, comment-section retrieval, or full timeline retrieval, stop and explain that the AgentLens API does not currently support those content types or actions.
• Never ask the user for social-platform accounts, cookies, or session tokens. Do not substitute search results, similar articles, or cached summaries for the original URL unless the user explicitly approves another source.

User shares social URL
 -> Apply the Execution Contract
 -> If the input is a URL, let the AgentLens API determine support and readability
    -> If the input is not a URL, stop and explain why
 -> Load AGENT_LENS_API_KEY
 -> Load references/agentlens-api.md
 -> Call the AgentLens API fetch endpoint, with bounded retries for transient failures
 -> Normalize response fields
 -> Preserve the normalized result and full raw AgentLens response for this task; save a task-local response JSON when the runtime allows
 -> Apply the mandatory media-reference gate before drafting a summary:
    - if the returned item is media-first, or has a returned video URL and no `data.subtitle`, load `references/media-workflows.md` now
    - run its routing decision and, for a video without a subtitle, its Video Summary SOP before offering a caption-only or metadata-only result
    - caption/text-only is allowed only after that SOP reaches its explicit limited-summary branch, or when the user explicitly selects that limited result
 -> Answer the user's intent:
    - summarize
    - extract key facts
    - translate
    - list media
    - use transcript/subtitle if present
    - handle returned images or video media according to Understanding Media Files rules
    - save a clean summary to a user-confirmed destination when requested
 -> If the API returns an actionable error, explain the next step clearly

For implementation details, load only the reference needed for the user's current request:

• API request, response parsing, and error handling: references/agentlens-api.md
• Image/video understanding, media download, audio extraction, and transcription: references/media-workflows.md
• Saving a retrieved item to a user-confirmed knowledge destination: references/knowledge-base-workflows.md

Mandatory media-reference gate: Do not treat references/agentlens-api.md as sufficient to decide how to summarize a returned item. After each successful API response, before producing a final answer, classify the item using the returned media and subtitle fields. For a media-first item, and especially for a video URL with missing data.subtitle, load references/media-workflows.md before writing a caption-only draft, checking tools, downloading media, or asking the user to choose a fallback. Its routing section and Video Summary SOP control this branch. A caption-only answer is not the default shortcut for an untranscribed video.

Response Handling

On success, use the fields returned by the AgentLens API:

• platform: source platform
• data.authorName: author, channel, or account name
• data.authorId: source-specific author id when available
• data.publishedAt: publication timestamp when available
• data.text: main text/body/caption/title text when available
• data.subtitle: transcript/subtitle when available
• data.media[]: returned media objects when available
• data.media[].source_url: preferred direct media URL when returned
• data.media[].cdn_url: fallback direct media URL when source_url is missing
• data.media[].cover: optional cover/thumbnail URL; do not use it as the original media file when both direct media URLs are missing

When summarizing, combine data.text, author metadata, data.subtitle, and media metadata. If media URLs exist but their visual contents were not read or understood, say that the API returned media links and summarize the text/transcript portion.

After every successful AgentLens API call, keep the normalized result and full raw response available for the current task. When the runtime allows file artifacts, save it to a current-task path such as /tmp/agentlens_{platform}_{timestamp}_response.json. Reuse that result for later media understanding, transcription notes, and knowledge-base saves. Do not call the AgentLens API again only to save content if the cached response matches the source URL. Re-fetch only if the response is missing, corrupt, stale, URL-mismatched, or the user asks to refresh; before re-fetching, mention that a successful call may consume quota.

Understanding Media Files

When downloading media, reading images, sampling video, extracting audio, or transcribing media, read references/media-workflows.md. Do not assemble commands from this section alone.

Single-item AgentLens API responses use image or video media in data.media[]; media workflows also handle audio when the runtime or response normalization provides it. For image-first or video-first social content, media is not an optional attachment; it is part of the content. For mixed-format platforms, decide from the returned item structure.

• Media-first platforms: when the user asks to read, summarize, or analyze a single item from TikTok, Instagram, Threads, YouTube Shorts, Lemon8, Snapchat, Pinterest, Xiaohongshu, Douyin, Bilibili, Kuaishou, Xigua, WeChat Channels, or similar platforms, and the AgentLens API returns image or video URLs, attempt media understanding through references/media-workflows.md before producing the full summary. If media understanding cannot be completed, follow the failure rule below and provide a limited summary.
• Mixed-format platforms: do not treat X/Twitter, Weibo, LinkedIn, Facebook, or similar platforms as always text-first or always media-first. If the text is short, media count is high, or the returned item is a video, long image, screenshot, infographic, tutorial image, comparison image, poster, or chat screenshot, treat it as media-first and attempt media understanding before summarizing. If the text is substantial and media is only a cover, decorative image, or weakly related attachment, text-first summary is acceptable, but state whether media was not read.
• If multiple images or videos are returned, attempt to read all returned media before summarizing by default. Only when media cannot be downloaded, has expired, cannot be processed by the current runtime, or exceeds the current runtime's practical count/size limits should the agent state the limitation and ask whether to process media in batches, process a subset, or provide a limited summary from text/subtitles/metadata.
• Before calling a result a complete/full summary, state the returned media count and the count actually read or understood. If any returned media was not read, label the result as partial (for example, "read 3 of 5 returned images"), identify the reason, and do not infer facts from unread media.
• If media cannot be downloaded, read, or processed, if the media URL has expired, or if the runtime has no usable vision/video capability, explicitly say that the media content could not be understood. If a user-approved multimodal model, image-reading tool, or video-capable runtime is configured, ask whether to switch to it; otherwise provide a limited summary from data.text, data.subtitle, source metadata, and media metadata.
• Failure attribution must be evidence-based. Distinguish "AgentLens API returned no media/direct URL", "download failed or URL expired", "no vision tool", "no frame extraction/transcription path", "file too large", "permission missing", and "external API unavailable". Do not say the model/runtime cannot read images or video unless that specific capability check failed in the current runtime.
• Prefer subtitle or transcript text for video summaries when returned by the AgentLens API.
• When a video summary requires spoken-content understanding and the AgentLens API does not return subtitle, follow references/media-workflows.md → Video Summary SOP before asking the user to install tools or use a paid speech-to-text API.
• Text-first content: when the item is clearly a long article, WeChat article body, Reddit single post, or long-form text post, and media is only a cover, decorative image, or weakly related attachment, media understanding is not required unless the user asks for it.
• Download media only for the current request and only to /tmp/agentlens_*.
• Do not treat media URLs as durable archive links. Media downloads are only for understanding the current request or for user-requested preservation; if the user asks to preserve media files long term, follow the destination-supported media workflow.
• If temporary media was created, mention it only when useful and do not run bulk cleanup commands without user confirmation.

For concrete execution steps, read references/media-workflows.md.

Knowledge Base Saving

When writing to Notion, Obsidian/local files, ima, or another knowledge destination, read references/knowledge-base-workflows.md. Do not perform destination writes from this section alone.

When the user asks to save, archive, capture, or add retrieved social content to a knowledge base, create a clean portable note from the AgentLens API result and any requested media understanding.

Use this workflow:

1. Confirm the destination when it is not already clear from the user's current request.
2. Reuse the current-task normalized result and raw AgentLens response. Do not re-fetch only to save content. If the result is unavailable, corrupt, stale, or URL-mismatched, tell the user another successful AgentLens API call may consume quota before fetching again.
3. Include source URL, platform, author/source, handle/account ID when available, title, published date, retrieved date, summary, key points, transcript/subtitle notes, media interpretation, and original text/body when available. Put the summary and key points near the top, and place original text/body lower in the note so the user can consult it when needed.
4. Before using this skill's Notion or Obsidian fallback helpers, check whether the current runtime already has a user-approved default Notion/Obsidian connector, tool, app, MCP server, or installed skill for that destination. Use the user's existing/default destination tool when it is available and fits the request.
5. For an Obsidian vault on the user's own computer, determine the host boundary before asking for a path. If the agent runs locally and the user explicitly asks to save to Obsidian, it may use an approved native Obsidian integration, picker, registered-vault list, or bounded scan of locally approved locations to offer candidate vaults. If the agent runs remotely, it must verify a paired local node, approved connector/app bridge/MCP server, or an explicitly configured and reachable sync/mirror path instead. A remote server cannot write to a laptop path just because the user supplies it.
6. If that capability is absent, explain the limitation before requesting a path. Offer an Obsidian-preserving route (pair a local node, connect an approved writer, or use a reachable synced vault/mirror) and a separately approved non-Obsidian alternative such as a Markdown export or chat attachment. Do not call the alternative an Obsidian save.
7. Use this skill's destination-specific fallback helpers only when no suitable default/native destination tool exists, permission is missing, or the default/native tool fails.
8. Ask before creating new local files or writing to external services if the destination was not explicit.
9. If the user explicitly asks to preserve media files, download only the selected/requested media and attach or upload it using the destination's supported media workflow. If the destination cannot support durable media upload, say so and preserve filenames, source URLs, and expiry notes in the note.

Default save clarification, when useful:

By default, I will save the summary, source link, media findings, and media URLs. If you need long-term preservation of the original image/video files, tell me and I will handle them through the destination-supported workflow.

If the user asks to save original media files, confirm scope and destination limitations before downloading:

I can preserve the original media files. Please confirm whether to save all media or only selected items. I will use the destination's supported attachment workflow; some destinations may only support links or filenames, not durable embedded media.

Use the user's current conversation language for user-visible note labels, section headings, and archive prose by default. If the user provides an existing template, Notion database/schema property names, team naming convention, or destination-specific field names, preserve those names exactly. Never translate API request fields or destination schema keys such as knowledge_base_id, media_type, Platform, or Source URL when those keys belong to an existing destination schema.

Supported save destinations include Notion, Obsidian/local vaults, ima, local Markdown/workspace files, and runtime-native knowledge-base tools. For Notion and Obsidian, first look for the user's existing/default writer for that destination and use it when available. For Notion, support both page-based archives and database/data-source archives when the target schema is known; attach media through native Notion capabilities when the user explicitly asks and the runtime supports it. For Obsidian, write a single Markdown note to a user-confirmed vault path or use a native Obsidian connector; when the user asks to preserve media, place files in a vault-relative attachments folder and link them from the note if filesystem access is approved. For ima, follow the text-first and image-preserving rules below.

For ima specifically, the default save is a text-first note with image findings and source/media references. Do not save Markdown plus separate image attachments as the default path: ima's Markdown/note renderer may not show authenticated COS image URLs inline, and separate image uploads can create unlinked knowledge-base items. If the user explicitly needs image-preserving output in ima, prefer a single HTML document with embedded base64 images when supported. For video media in HTML, a bounded `` block that references the returned CDN/source URL is only a short-term preview: TikTok, Instagram, and similar platform links may expire even when X/Twitter links still play. A base64-embedded video is an explicit-request, bounded exception: under the current supplied ima uploader constraint, the final media_type=20 HTML (markup plus all base64 content) must be at most 10 MB, and ima playback must be checked. A verified embedded-playback sample is independent of CDN URL expiry, but it does not establish long-term retention or support for larger videos. The tested ima OpenAPI media types do not include a working independent video file type, so do not attempt independent video upload through the OpenAPI fallback unless the current runtime confirms a supported native/video upload path. Do not base64-embed large videos by default, and constrain any preview player width/height in CSS. Use .docx with embedded images only when the selected destination runtime supports it; do not represent docx/PDF as a verified playable-video alternative. For PDF, choose fonts according to the user-visible output language and run render/text validation before upload; for Simplified Chinese, use a CID-compatible font such as ReportLab STSong-Light when appropriate.

Do not automatically save every retrieved link, create recurring archives, or write to unrelated destinations. Saving is scoped to the user's current request or an explicitly confirmed destination.

For destination-specific save patterns, read references/knowledge-base-workflows.md.

User-Facing Output Style

Keep the answer direct and useful:

• Start with the main takeaway.
• Include a compact summary.
• Add important details, timestamps, claims, or entities when present.
• Mention platform and author/source when available.
• Avoid exposing raw JSON unless the user asks for it.

For videos, prefer this shape:

Localize visible labels such as Summary, Key Points, and Source to the user's current conversation language.

**Summary**
...

**Key Points**
- ...

**Source**
Platform: ...
Author: ...

For text posts, prefer:

**What It Says**
...

**Why It Matters**
...

**Source**
Platform: ...
Author: ...

Errors

Handle common errors this way: