Skip to main content

​
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.

​
Skill versus MCP

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 and Authentication.

​
What you can ask

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: 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.