> ## Documentation Index
> Fetch the complete documentation index at: https://docs.socq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Skill

> Teach an agent to choose endpoints, control cost, and complete SocQ research workflows.

# Agent Skill

Install the `socq-social-research` Skill to teach a coding agent how to choose SocQ endpoints, shape inputs, control cost, and complete asynchronous collections.

```bash theme={"system"}
npx skills add SocQAPI/socq-devtools
```

## Skill versus MCP

| Component | Role |
| - | - |
| MCP | Gives the agent live SocQ tools that can submit and read data tasks |
| Agent Skill | Teaches the agent which tool to choose and how to run a reliable research workflow |

Use them together when possible. MCP provides execution; the Skill provides endpoint selection, billing awareness, polling, pagination, and cross-platform workflow guidance.

Billing behavior and API-key limits are documented in the [API overview](https://docs.socq.ai/api-manual/agent-api/overview.md) and [Authentication](https://docs.socq.ai/api-manual/agent-api/authentication.md).

## What you can ask

```text theme={"system"}
Collect the latest comments from this Instagram Reel, wait for the task,
then summarize recurring positive and negative themes.
```

```text theme={"system"}
Compare the latest posts from these three X profiles. Use the same result
limit for each profile and return a normalized engagement table.
```

```text theme={"system"}
Find recent YouTube videos about AI coding agents, collect their comments,
and explain which topics produce the strongest audience response.
```

The Skill guides the agent through:

* mapping user intent to a Capability Registry endpoint;
* choosing URL, username, hashtag, or query inputs;
* checking schemas and estimating credits before large jobs;
* submitting with an idempotency key when retries are possible;
* polling asynchronous tasks instead of resubmitting;
* following cursor pagination and retrieving raw files;
* recovering from authentication, validation, rate, credit, and provider errors;
* coordinating comparable cross-platform research.

Before a paid large-volume, cross-platform, or multi-endpoint run, the Skill reports the expected credit cost and asks for confirmation. It does not silently retry failed paid requests.

## Execution preference

The Skill prefers:

1. remote MCP;
2. the SocQ stdio MCP bridge;
3. the SocQ CLI when MCP is unavailable;
4. direct REST only as the final fallback.

Endpoint references are generated from the same Capability Registry as MCP and OpenAPI, so endpoint IDs and input fields remain consistent across integrations.

## Results and reporting

The Skill uses the same stable result schema across MCP, CLI, and REST integrations. It treats `queued` and `running` tasks as incomplete, saves task IDs for resumption, and follows opaque `next_cursor` values to the approved limit.

A completed response identifies the selected endpoints and execution path, summarizes inputs and filters, reports expected and actual credits when available, lists task IDs and terminal states, states result and page counts, and discloses failed platforms, unsupported filters, or incomplete coverage.

## Request attribution

Tasks submitted under the Skill retain both the Skill origin and its execution path in `request_source`:

| Skill execution path | Recorded value |
| - | - |
| Remote or stdio MCP | `skill-mcp` |
| CLI fallback | `skill-cli` |
| Direct REST fallback | `skill-rest` |

The Skill passes `_request_source: "skill"` to MCP execution tools, `--request-source skill` to CLI commands, or `X-Socq-Source: skill-rest` to direct REST requests. Polling an existing task does not require an attribution marker.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.