AGNT Skills

In AGNT, everything executable is a Skill. Agents with tool loops, one-shot prompts, HTTP plugin integrations, MCP server connectors — they're all skills, differentiated by a single kind field.

This unified model means one API for create, read, update, delete, version, publish, and execute. No separate agent API, no separate plugin registry.

Skill kinds

Quick start

Create an agent skill

curl -X POST https://api.agnt.ai/skills \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "title": "My Agent",
    "description": "A helpful agent that answers questions.",
    "kind": "agent",
    "modelStrategy": "medium",
    "access": "private"
  }'

Response:

{
  "success": true,
  "skill": {
    "id": "6789abc...",
    "name": "my-agent",
    "title": "My Agent",
    "description": "A helpful agent that answers questions.",
    "kind": "agent",
    "status": "active",
    "access": "private",
    "listed": false,
    "dispatchable": false,
    "modelStrategy": "medium",
    "createdAt": "2026-03-06T10:00:00.000Z",
    "installation": {
      "id": "inst_abc...",
      "source": "own",
      "shared": true,
      "locked": false,
      "alias": null
    }
  }
}

Create a prompt skill

curl -X POST https://api.agnt.ai/skills \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "summarizer",
    "title": "Summarizer",
    "description": "Summarizes long text into bullet points.",
    "kind": "prompt",
    "access": "private",
    "variables": [
      { "key": "text", "description": "The text to summarize", "type": "string", "required": true },
      { "key": "max_bullets", "description": "Maximum number of bullet points", "type": "string", "required": false }
    ]
  }'

List your skills

curl https://api.agnt.ai/skills \
  -H "Authorization: Bearer $TOKEN"

Response shape:

{
  "skills": [
    {
      "id": "6789abc...",
      "name": "my-agent",
      "title": "My Agent",
      "kind": "agent",
      "access": "private",
      "tags": [],
      "installation": {
        "id": "inst_abc...",
        "source": "own",
        "shared": true,
        "locked": false,
        "alias": null
      }
    },
    {
      "id": "xyz789...",
      "name": "calendar-plugin",
      "title": "Calendar",
      "kind": "http",
      "access": "private",
      "tags": ["calendar"],
      "installation": {
        "id": "inst_def...",
        "source": "grant",
        "shared": true,
        "locked": true,
        "alias": null
      }
    }
  ],
  "total": 2,
  "page": 1,
  "limit": 50
}

Filter by kind or source:

# Only agent skills
curl "https://api.agnt.ai/skills?kind=agent" \
  -H "Authorization: Bearer $TOKEN"

# Only skills you authored (studio authoring view)
curl "https://api.agnt.ai/skills?source=own" \
  -H "Authorization: Bearer $TOKEN"

# Only enabled skills
curl "https://api.agnt.ai/skills?shared=true" \
  -H "Authorization: Bearer $TOKEN"

Assign plugin skills to an agent

An agent skill calls http or mcp skills as tools during its execution loop. Install them by ID:

curl -X POST https://api.agnt.ai/skills/$AGENT_SKILL_ID/skills \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "skillId": "$PLUGIN_SKILL_ID" }'

Core concepts

Files

Skills with kind='agent' or kind='prompt' are authored using files. Each file belongs to a section:

• system — system message content, rendered as instructions.md
• messages — user message content, rendered as messages.md

Files contain blocks of text with variable interpolation. Variables are declared on the skill and resolved at execution time. The Studio editor is the primary tool for authoring files — it provides block-based editing with live variable preview.

Variables

Variables are declared on the skill and interpolated into file content using {{variable_key}} syntax.

Declaration:

{
  "key": "user_name",
  "description": "The name of the user",
  "type": "string",
  "required": true
}

Usage in a file:

Hello {{user_name}}, here is your summary of {{document_title}}:

Variable fields:

Required variables that are missing at execution time cause the execution to fail with a validation error. Optional variables that are omitted are interpolated as empty strings.

Tool definitions

For kind='agent' skills, toolDefs declares the tools available during the execution loop. Each tool definition corresponds to either a system tool, a plugin skill, or a custom tool handled by your application.

{
  "name": "search_calendar",
  "description": "Search the user's calendar for events",
  "parameters": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "Search query" },
      "date_range": { "type": "string", "description": "e.g. 'next 7 days'" }
    },
    "required": ["query"]
  }
}

Every agent skill should include finish_agent_run as a tool — this is how the agent signals completion and returns a structured result. Prompt skills never need it.

kind='agent' vs kind='prompt'

Use kind='prompt' for: summarization, classification, extraction, rewriting, and any task that is a single LLM call. Use kind='agent' when the task requires tool calls, external integrations, or multi-step reasoning.

Model strategy

agent and prompt skills have a modelStrategy field (low, medium, high) that maps to the account's configured model tiers. This determines which model and routing strategy is used at execution time. The account owner configures which specific models correspond to each tier.

Versions

Every time you publish a skill, an immutable SkillVersion is created with a snapshot of the full manifest. Versions are numbered sequentially starting at 1. You can roll back to any previous version.

# Publish a new version
curl -X POST https://api.agnt.ai/skills/$SKILL_ID/publish \
  -H "Authorization: Bearer $TOKEN"

# List all versions
curl https://api.agnt.ai/skills/$SKILL_ID/versions \
  -H "Authorization: Bearer $TOKEN"

# Get a specific version
curl https://api.agnt.ai/skills/$SKILL_ID/versions/3 \
  -H "Authorization: Bearer $TOKEN"

Access and marketplace

• access: 'public' | 'private' — public skills can be discovered and used by other accounts
• listed: boolean — controls whether the skill appears on the marketplace (independent of access)
• dispatchable: boolean — marks an agent skill as available for orchestrator dispatch (sub-agent routing)

These are independent fields. A skill can be public but not listed, or private and dispatchable.

Pricing

{
  "model": "free | fixed | credits",
  "perMonth": 29,
  "creditsPerMinute": 50
}

• free — no charge
• fixed — monthly subscription (perMonth in USD)
• credits — consumed per minute of execution (creditsPerMinute; 1 credit = $0.01)

Pricing is independent of access and listed. You can charge for private skills shared within your organization.

Forking

Set fork.fromSkillId to fork an existing public skill into your account. The fork is a full copy — you own it and can modify it independently. The original skill is tracked in fork.fromSkillId for attribution.

Content visibility

contentVisibility: 'transparent' | 'opaque' controls whether a plugin skill's file content is exposed to the calling agent.

• transparent — the agent can read the plugin skill's instructions (useful for orchestration prompts)
• opaque — the agent knows the plugin skill exists and can call it, but cannot inspect its instructions (useful for proprietary skills)

This also affects what GET /skills returns for non-own skills:

• Own skills (installation.source = 'own') always return full skill data
• Non-own transparent skills return full skill data
• Non-own opaque skills return public metadata only: name, title, description, kind, access, tags, installCount, pricing

Skill pool and installations

Every account has a skill pool — the set of skills it can use. GET /skills always returns the full pool with installation context merged into each skill.

The installation object in each skill response describes how that account relates to the skill:

The installation.shared flag controls whether Prime can discover and use the skill. Toggle it off to pause without uninstalling. Locked installs (installation.locked: true) cannot be toggled or deleted — these are system skills managed by AGNT.

# Install a skill from another account
curl -X POST https://api.agnt.ai/skills/$SKILL_ID/install \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "alias": "my-crm" }'

# Toggle off (pause without uninstalling)
curl -X PATCH https://api.agnt.ai/skills/installs/$INSTALL_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "shared": false }'

# Uninstall
curl -X DELETE https://api.agnt.ai/skills/installs/$INSTALL_ID \
  -H "Authorization: Bearer $TOKEN"

The optional alias field lets you rename a skill locally — useful when installing a skill from another account under a friendlier name. Prime uses the alias instead of the skill's original name.

Grants and shared access

Accounts can grant access to their skills to other accounts via the Grants API. Once a grant is active, the grantee's skill pool will include the skill with installation.source = 'grant'.

The v2 manifest

The manifest is the canonical execution contract for a skill. It is generated by GET /skills/:skillId/manifest and includes everything needed to run the skill: resolved files, tools, variables, model configuration, and dependencies.

{
  "$schema": "https://agnt.ai/schemas/manifest/v2.json",
  "kind": "SkillManifest",
  "apiVersion": "v2",
  "metadata": {
    "name": "summarizer",
    "title": "Summarizer",
    "description": "Summarizes text into bullet points.",
    "kind": "prompt",
    "access": "private",
    "tags": [],
    "etag": "d41d8cd98f00b204e9800998ecf8427e",
    "createdAt": "2026-03-06T10:00:00.000Z"
  },
  "spec": {
    "routingStrategy": "fallback",
    "enableToolCalls": false,
    "variables": [
      { "key": "text", "type": "string", "required": true, "description": "The text to summarize" }
    ],
    "files": [
      {
        "section": "system",
        "name": "instructions.md",
        "order": 0,
        "condition": null,
        "blocks": [
          { "type": "text", "order": 0, "content": "You are a concise summarizer. Extract the key points from the provided text as bullet points.\n\nMaximum {{max_bullets}} bullets." }
        ]
      }
    ],
    "tools": [],
    "models": [],
    "dependencies": []
  }
}

Key manifest fields:

Conditions

Both files and tool definitions support conditional inclusion via a condition field. This lets you build context-aware agents that adapt their instructions and available tools based on variable values.

A condition is either a leaf (single comparison) or a compound (logical group):

{
  "operator": "AND",
  "rules": [
    { "variable": "user_role", "op": "eq", "value": "admin" },
    { "variable": "feature_flag", "op": "eq", "value": "true" }
  ]
}

Supported op values: eq, neq, contains, not_contains, starts_with, ends_with, gt, gte, lt, lte, is_empty, is_not_empty.

API reference

Endpoints

Query parameters for GET /skills

Admin endpoints

Marketplace endpoints

Skill object

GET /skills always returns each skill with its installation context nested inline.

{
  "id": "6789abc...",
  "name": "my-agent",
  "title": "My Agent",
  "description": "A helpful agent.",
  "kind": "agent",
  "status": "active",
  "access": "private",
  "listed": false,
  "dispatchable": false,
  "modelStrategy": "medium",
  "tags": ["productivity"],
  "contentVisibility": "transparent",
  "variables": [...],
  "toolDefs": [...],
  "pricing": { "model": "free" },
  "createdAt": "2026-03-06T10:00:00.000Z",
  "updatedAt": "2026-03-06T10:00:00.000Z",
  "installation": {
    "id": "inst_abc...",
    "source": "own",
    "shared": true,
    "locked": false,
    "alias": null
  }
}

For non-own skills with contentVisibility: 'opaque', only public metadata is returned — the full variables, toolDefs, and file content are omitted. The installation context is always included.

Installation object

The installation object is nested in every skill returned by GET /skills and GET /skills/:skillId.

{
  "id": "inst_abc...",
  "source": "own",
  "shared": true,
  "locked": false,
  "alias": null
}

Create a skill

Creating a skill automatically creates a source: 'own' install so it appears in your skill pool immediately.

Update a skill

curl -X PATCH https://api.agnt.ai/skills/$SKILL_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Better Summarizer",
    "listed": true
  }'

PATCH is partial — only send the fields you want to change.

Update an install

curl -X PATCH https://api.agnt.ai/skills/installs/$INSTALL_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "shared": false }'

Returns the full skill + updated installation object. Locked installs return 403 Forbidden.

Export the manifest

curl https://api.agnt.ai/skills/$SKILL_ID/manifest \
  -H "Authorization: Bearer $TOKEN"

Returns the full v2 SkillManifest envelope. The etag is a content hash of spec — use it to detect changes since your last fetch.

Compile

Compile the skill against a specific set of variables and get back the resolved system message, messages array, and model config. Useful for testing and debugging before execution.

curl -X POST https://api.agnt.ai/skills/$SKILL_ID/compile \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": { "user_name": "Alice", "context": "onboarding" }
  }'

Response:

{
  "system": "You are a helpful assistant. Hello Alice...",
  "messages": [],
  "tools": [ ... ],
  "model": { "provider": "anthropic", "model": "claude-sonnet-4-6", "temperature": 0.7 },
  "warnings": []
}

The warnings array surfaces issues (unresolved variables, missing references, failed conditions) without blocking the response.

Diff

curl https://api.agnt.ai/skills/$SKILL_ID/diff \
  -H "Authorization: Bearer $TOKEN"

Returns a structured diff of the current draft against the last published version. Use this to review changes before publishing.

For coding agents

• Use kind to route execution logic. agent runs a tool loop and returns a structured result from finish_agent_run. prompt returns raw LLM text in a single turn. Don't send tool-call requests to prompt skills.
• Check dispatchable before dispatching sub-tasks. Only agent skills with dispatchable: true can receive dispatched tasks from an orchestrator.
• installation.source tells you the relationship. own means full edit access in Studio. grant or import means read-only or limited access.
• installation.locked: true means hands off. Locked installs are system-managed — don't attempt to toggle or delete them.
• contentVisibility: 'opaque' means a non-own skill's file content is hidden. You can still call it — you just can't inspect its variables or instructions.
• Use ?source=own for the authoring view. Studio uses this filter to show only skills you can edit.
• Manifests are the execution contract. Fetch GET /skills/:skillId/manifest to get the complete resolved spec before executing. The etag tells you if it has changed since your last fetch.
• Variables are declared, not inferred. All variables used in files must be declared in variables. Undeclared variables are left as literal {{key}} strings at execution time.
• enableToolCalls: false in the manifest is the canonical signal for a prompt skill. Check it before deciding how to handle execution output.
• Conditions are evaluated at execution time. A file or tool with a condition that evaluates false is completely excluded from the compiled manifest — the model never sees it.