market/skills/using-services/SKILL.md

name, description, version, type, risk_level, status, disable-model-invocation, tags, metadata, market

name	description	version	type	risk_level	status	disable-model-invocation	tags	metadata	market
using-services	Discover and invoke HTTP/MCP services already registered in the global catalog. Use when the user asks the Agent to call an API, search for an existing service, or query a backend that was registered via the registering-services skill. 调用某个 API、查找已有服务、访问已注册的后端服务时使用。	1.0.0	meta	low	enabled	true	service catalog http mcp meta	author updated_at i18n desirecore 2026-05-28 default_locale source_locale locales zh-CN en-US en-US zh-CN zh-CN en-US name short_desc description body translated_by 使用服务 发现并调用全局目录中已注册的服务 发现并调用全局应用与服务目录中已经注册过的 HTTP/MCP 服务。Use when 用户让 Agent 调用某个 API、查找已有服务，或访问通过 registering-services 注册的后端。 ./SKILL.zh-CN.md human name short_desc description body translated_by Using Services Discover and invoke registered services from the catalog Discover and invoke HTTP/MCP services already registered in the global catalog. Use when the user asks the Agent to call an API, search for an existing service, or query a backend that was registered via the registering-services skill. ./SKILL.md human	category maintainer channel productivity name verified DesireCore Official true latest

using-services Skill

L0: One-line Summary

Teach the Agent how to look up and call services from the global "Apps & Services" catalog.

L1: Overview

The "Apps & Services" catalog stores all registered HTTP/MCP services. This meta-skill is your manual for finding the right service and invoking it correctly. Each non-trivial registered service also has its own svc-<id> Skill auto-generated from its operations — prefer that when it exists; this meta-skill is the fallback for ad-hoc discovery.

When to use

• The user asks you to do something that might already have a registered service (e.g. "search the product database", "send a notification")
• You see svc-<id> Skill in your available skills list — activate it directly
• You need to call an HTTP API and want to check if it's been registered (to benefit from governance, credential injection, and audit)

When NOT to use

• The user gives you a one-off URL to fetch — use HttpRequest directly
• You already have the per-service svc-<id> Skill activated — follow it instead, it's more specific

L2: How to discover and call

Step 1 — List the catalog

Fetch the registry:

tool: HttpRequest
parameters:
  url: http://127.0.0.1:<agent-service-port>/api/registry/services
  method: GET

Response shape (excerpt):

{
  "data": {
    "services": [
      {
        "id": "acme-search-api",
        "name": "Acme Search API",
        "protocol": "http",
        "endpoint": "https://api.acme.example/search",
        "tags": ["search", "products"],
        "status": "online",
        "origin": "agent",
        "reviewStatus": "approved",
        "riskLevel": "medium",
        "operations": [...]
      }
    ],
    "total": 1,
    "source": "official"
  }
}

Step 2 — Pick a candidate

Filter by tags, protocol, name. Important checks before invoking:

• status === 'online' → safe to call
• status === 'offline' / 'error' → tell the user the service is down, don't retry blindly
• status === 'degraded' → degrade gracefully, mention it to the user
• reviewStatus === 'pending' (only origin='agent') → you can only call it if registeredBy is you; otherwise ask the user to promote it
• riskLevel === 'critical' → expect a human approval prompt on every call

Step 3 — Build the request (HTTP services)

If the service has operations, prefer them — they define stable contract points. Build the URL as <endpoint><operation.path>.

tool: HttpRequest
parameters:
  url: https://api.acme.example/search/v1/items?q=widget
  method: GET
  headers:
    Authorization: "Bearer ${secrets/api-keys/acme}"  # resolved at call time

If the service declares auth.secretRef, do not prompt the user for the secret value during chat. The HttpRequest tool resolves it automatically.

Step 4 — Build the request (MCP services)

MCP services aren't called via HttpRequest — they are tools exposed through the Agent's mcp_servers config:

1. If you haven't added the MCP service to your Agent yet, POST to http://127.0.0.1:<agent-service-port>/api/agents/<your-id>/mcp-servers with { serverId: '<service.id>', config: <connection> }
2. Next query, MCP discovery will auto-expose tools from the server
3. Call the tools by their MCP-declared names directly

Step 5 — Handle the response

• 2xx → parse and use
• 4xx → likely a client error (bad params, missing auth); fix the request, then retry once; if it still fails, report to the user
• 5xx → server-side problem, report status of the service back so the user knows
• Service-approval rejected → response will contain "decision":"rejected"; do not retry, ask the user how to proceed

Step 6 — Don't fall through to raw URL fetching

If the catalog has a service for what you need, use it. Don't bypass governance by calling an undeclared URL directly — HttpRequest will still work, but you lose:

• Approval gating for high-risk operations
• Credential injection (you'd need to ask the user for keys yourself)
• Audit trail and lastUsed tracking
• Other Agents being able to reuse your call patterns

Failure modes

• Catalog read fails: just fall back to direct HttpRequest and warn the user that governance is bypassed.
• No matching service: ask the user if they want to register a new one — activate registering-services skill.
• status === 'offline': report the situation, suggest checking the underlying service, don't call anyway.