Agent Skills

SocialKit Agent Skills are a drop-in instruction pack for coding agents. They help Claude Code, Cursor, and Codex build competitor trackers, research creators, analyze comments, and turn public videos into transcripts and metadata.

The social-media-scraping skill routes the task to a focused skill with endpoint guidance, supported inputs, and collection limits. Installation makes these instructions available; selection and successful task completion still depend on the client and request.

The skills live at github.com/SocialKit-API/skills.

Skills or MCP?

Both surfaces sit on the same SocialKit REST API and use the same access key.

• Agent Skills fit coding agents that read skill files (Claude Code, Cursor, Codex). They call api.socialkit.dev directly. No MCP server is required.
• MCP Server fits tool-calling clients (Claude Desktop, MCP Inspector, custom agents) that discover typed tools over Streamable HTTP.

If your agent supports skills, start here. If it speaks MCP, use the MCP server. You can run both.

Choose your integration

Skills call REST directly; they do not require an MCP server. Use MCP when you want your client to discover typed tools.

Install

Install all eight skills for all supported agents in your project:

npx skills add SocialKit-API/skills --all

The --all flag selects every skill and agent without a picker. To install for one client, choose a tab:

npx skills add SocialKit-API/skills --skill '*' --agent claude-code -y

npx skills add SocialKit-API/skills --skill '*' --agent codex -y

npx skills add SocialKit-API/skills --skill '*' --agent cursor -y

To inspect the source before installing:

git clone https://github.com/SocialKit-API/skills.git

Authentication

Get your project key from Access keys in the dashboard. In a private terminal, replace the placeholder and export it before launching the agent:

export SOCIALKIT_API_KEY="YOUR_PROJECT_ACCESS_KEY"

For Claude Code or Codex CLI, launch claude or codex from that terminal so it inherits the variable. For Codex IDE or Cursor, completely quit the editor and launch it from that configured terminal (code . or cursor ., with its shell command installed). Confirm the agent’s execution environment has the variable without printing it. An already-running editor may not inherit a new shell environment.

A .env file is an alternative only when your code or shell explicitly loads it; skills do not automatically load .env. Keep environment files out of Git, keep keys out of prompts, and never put a key in browser code. REST uses the x-access-key header.

Test installation

Start a fresh agent session and paste:

Use the installed SocialKit skills to verify my environment key with the free
/test endpoint. Do not print the key. Then describe how you would fetch metadata
for one public video; wait before making a paid data request.

A successful /test response verifies the key without spending data credits. If the skill is missing, check the selected client and project directory, then restart its session. If authentication fails, check the environment and current project key before retrying.

What’s included

Installing with --all gives you eight skills:

Each skill is a SKILL.md file the agent reads on demand, plus an agents/openai.yaml descriptor.

Example prompts

Runnable competitor research

Build an Instagram + YouTube Competitor Tracker with the runnable repository example, including setup, credit limits, sample output, and Claude Code/Codex build prompts. The versioned Competitor Research Starter v0.1.0 remains available. It collects recent YouTube videos and Instagram Reels from up to three public profiles and writes Markdown and JSON reports. Requests, retries, credits and run time are bounded; unavailable metrics remain unknown, and partial failures stay visible. It does not require an LLM.

Get the versioned starter and setup instructions.

For scheduled collection, the n8n Competitor Monitor v0.1.0 adds a persistent PostgreSQL delivery ledger and Slack digests. Read its database and credential setup before importing. Get the workflow and setup instructions.

Install the skills in your project terminal and configure your access key before trying these examples.

Video URL to transcript and metadata

The JavaScript and Python example writes structured JSON with source links, metadata, transcript status, and a credit ledger. Start with its offline fixture; enable live calls explicitly after setting a key. Empty, unavailable, failed, and budget-limited transcripts remain distinct.

Claude Code: research a creator

Research the latest 10 Instagram Reels from @nasa. Identify their strongest
topics and opening hooks, with view counts and source links.

OpenAI Codex: build a competitor dashboard

Build a competitor-monitoring dashboard for public social data. Compare recent videos
from three YouTube channels by topic and views, with links to each video.

Cursor: build a customer-feedback report

Add a customer-feedback report to this app. Group comments
from selected Instagram posts into complaints, questions, and praise,
with supporting quotes.

SocialKit returns the data; your agent writes the application code or performs the analysis. The AI agents guide has more task examples and a platform capability table. Search is available for YouTube, TikTok, and Instagram Reels. Comment retrieval is available for YouTube, TikTok, Instagram, and Facebook; a comment count in X or LinkedIn post metadata does not include the comments themselves.

How it works under the hood

Every skill maps onto the REST API documented in this reference. For example, video-transcripts calls POST /youtube/transcript, POST /tiktok/transcript, and the other transcript endpoints depending on the URL.

The agent runs ordinary HTTP code; there is no required MCP server. Keep installed skills current when endpoint contracts change. Most successful calls cost 1 credit, while AI and video endpoints follow the same per-request or per-started-minute tiers as REST. Failed calls are free, and your normal rate limits apply.

Credits and rate limiting

Skills consume credits identically to the REST API and MCP. Set explicit request and modeled-credit budgets before a collection run; a plan allowance is not a hard workflow spending cap, especially when purchased credits are available. YouTube/TikTok transcripts cost 1 credit; duration-priced transcripts use the applicable project pricing policy. Unknown duration means the cost cannot be predicted reliably. Successful repeats can spend credits. See Authentication for key management and the API Reference for the simple per-endpoint tiers.

Collection boundaries

Use public content only. SocialKit does not post content, bypass private accounts, or scrape arbitrary websites. Platform capabilities differ: Reddit post/subreddit details and X Articles are REST operations; Reddit has no MCP tools. LinkedIn company posts are supported, but there is no dedicated LinkedIn comment endpoint.

Pagination is endpoint-specific. Follow returned cursors only where documented; YouTube video/comment retrieval and Instagram Reels search do not provide cursor traversal through these operations. Mark capped or partial collections instead of claiming completeness. Keep missing metrics unknown rather than replacing them with zero. Preserve structured code, errorCode, and retryable information, and use bounded retries only for eligible transient errors.

Claude plugin option

The repository also includes a Claude marketplace. After the release is merged, install it from Claude Code:

/plugin marketplace add SocialKit-API/skills
/plugin install socialkit-skills@socialkit

Use either the skills installer or the plugin to avoid duplicate copies. This repository package is separate from an official marketplace listing. OpenAI/Codex packaging and project-consent OAuth are being prepared separately; the key-based skills and MCP paths above remain available.