Source: docs/skill/micro-agent-integrator/SKILL.md

---

name: micro-agent-integrator

description: >-

Use when integrating an external application with Forgium Agent over the

Public API, including HTTP and business capabilities.

version: 1.0.0

---

Forgium Agent Integrator

Use this skill to integrate an external application with forgium-agent and add

business capabilities for your application.

Package paths — read first

This file lives at skill/micro-agent-integrator/SKILL.md in the exported

public-docs package. <FORGIUM_AGENT_DOCS_ROOT> means that package root; after

copying the package it is normally docs/vendor/forgium-agent.

Read in this order:

  1. <FORGIUM_AGENT_DOCS_ROOT>/integration/overview.md
  2. <FORGIUM_AGENT_DOCS_ROOT>/integration/getting-started.md
  3. <FORGIUM_AGENT_DOCS_ROOT>/integration/environments.md
  4. <FORGIUM_AGENT_DOCS_ROOT>/integration/capability-handoff.md when live host-application data or actions are required.
  5. <FORGIUM_AGENT_DOCS_ROOT>/integration/api.openapi.yaml for the authoritative request and response contract.

The universal agent prompt at

<FORGIUM_AGENT_DOCS_ROOT>/integration/use-with-an-agent.md is the fallback when

the consuming runtime cannot load this Skill.

Authority boundary

You are an integrator agent and own the lifecycle of capabilities available

to the supplied API key. You may import, test, update, activate, and disable

those capabilities through the Public API.

You need:

| Variable | Purpose |
|---|---|
| `FORGIUM_AGENT_BASE_URL` | Public API base URL |
| `FORGIUM_AGENT_API_KEY` | API key for `/v1/*` |

If either value is missing, ask the Forgium administrator to provide it. Use

only the public API and documentation; do not request platform-operator

credentials or access to internal services.

Required capability decision

A generic answer such as “I do not have access”, “I cannot access private

data”, or “I only provide general information” to a domain question means the

required capability is absent or inactive.

When the user asks to implement, integrate, or fix that behavior, you **must

not** stop at diagnosis or return a gap list. Complete this sequence:

  1. Inspect the host application's chat adapter and verify it calls

POST /v1/channels/http/messages.

  1. Implement the application's business endpoint and local JSON data source when

absent. Validate input and return only approved fields.

  1. Test that endpoint directly.
  2. Expose it at an exact reachable HTTPS URL on port 443 using the application's

authorized deployment path or a temporary HTTPS tunnel for development.

localhost, 127.0.0.1, and api.example.com are never manifest URLs.

  1. Generate a scoped token in the application API and register it through the

credential vault. Do not create an unauthenticated endpoint.

  1. Create <project-root>/forgium-agent.capabilities.json with the real URL

and its credential_ref, following

<FORGIUM_AGENT_DOCS_ROOT>/integration/capability-handoff.md.

  1. Import, contract-test, and activate the capability through the Public API.
  2. Send the chat query again and verify the grounded response.

A temporary HTTPS tunnel is endpoint exposure for development, not a proxy or

architecture workaround. Do not add prompt enrichment, chat middleware, or a

direct lookup call from /api/chat as a substitute for a capability.

If the environment cannot deploy or create a tunnel, finish local implementation

and manifest work and report that one concrete blocker. Do not leave a placeholder

URL or claim that the capability is active.

Self-service capability API

All requests use Authorization: Bearer $FORGIUM_AGENT_API_KEY:

# Store the endpoint token encrypted in the credential vault. The token is
# never persisted in the manifest, plaintext storage, logs, or API responses.
curl -fsS -X PUT "$FORGIUM_AGENT_BASE_URL/v1/capability-credentials/cred_people_api" \
  -H "Authorization: Bearer $FORGIUM_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"auth_type":"bearer","secret":"'"$PEOPLE_API_TOKEN"'"}'

# Import a draft capability using the configured API key.
curl -fsS -X POST "$FORGIUM_AGENT_BASE_URL/v1/capabilities/import" \
  -H "Authorization: Bearer $FORGIUM_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: capability-import-$(date +%s)" \
  --data-binary @forgium-agent.capabilities.json

# Use the capability ID returned by import.
curl -fsS -X POST "$FORGIUM_AGENT_BASE_URL/v1/capabilities/$CAPABILITY_ID/test" \
  -H "Authorization: Bearer $FORGIUM_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"arguments":{"name":"Juan Pérez"}}'

curl -fsS -X POST "$FORGIUM_AGENT_BASE_URL/v1/capabilities/$CAPABILITY_ID/activate" \
  -H "Authorization: Bearer $FORGIUM_AGENT_API_KEY"

The import starts as draft; activation requires a passed test for its current

revision. Only active capabilities are available to the model.

Credentials

Self-service capabilities must use bearer, api_key, or basic and reference

a credential provisioned first through PUT /v1/capability-credentials/{credentialRef}.

The vault encrypts the secret with the platform vault key; plaintext is never

stored in D1, the manifest, logs, prompts, or API responses. auth.type: "none"

is rejected for self-service imports, preventing an integrator from normalizing

an open endpoint.

Completion criteria

Your integration is complete only when: