Anatomy of a Skill Manifest: Every Field Explained

Every skill has a skill.json manifest that tells the agent what it is, how to run it, what it needs, and how users configure it. Here's every field, explained.

Required Fields

{
  "skill_id": "weather-lookup",
  "name": "Weather Lookup",
  "version": "1.0.0",
  "description": "Fetches current weather and forecasts for any location",
  "execution_tier": 1
}

Execution Tiers

• Tier 1 — most restricted. Short timeouts, minimal filesystem access. Good for simple tools.
• Tier 2 — moderate. Longer timeouts, more memory. Good for API integrations.
• Tier 3 — least restricted. Extended timeouts, broader access. For complex processing.

Entrypoint

Tells the agent how to launch your skill:

{
  "entrypoint": {
    "type": "node",
    "command": "node",
    "args": ["dist/index.js"],
    "env": {
      "NODE_ENV": "production"
    }
  }
}

The agent clears the environment before launching your skill. Only PATH and your declared env vars are available. This prevents accidental secret leakage.

Configuration Schema

Defines what settings your skill accepts from users:

{
  "config_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "api_key": {
        "type": "string",
        "title": "API Key",
        "description": "Your weather service API key",
        "x-secret": true
      },
      "units": {
        "type": "string",
        "title": "Temperature Units",
        "description": "Celsius or Fahrenheit",
        "enum": ["celsius", "fahrenheit"],
        "default": "celsius"
      },
      "cache_ttl": {
        "type": "integer",
        "title": "Cache Duration",
        "description": "How long to cache results (seconds)",
        "default": 300
      }
    },
    "required": ["api_key"]
  }
}

Supported Field Types

The x-secret Flag

Fields marked "x-secret": true are:

• Stored in the agent's encrypted vault (not in plaintext config)
• Masked in the UI (shown as ••••••••)
• Never logged or exposed in error messages
• Resolved at runtime and passed to your skill securely

Setup Steps

Groups config fields into a guided wizard:

{
  "setup_steps": [
    {
      "step_id": "credentials",
      "title": "API Credentials",
      "description": "Connect your weather service account",
      "fields": ["api_key"],
      "validation_command": "validate_credentials"
    },
    {
      "step_id": "preferences",
      "title": "Preferences",
      "description": "Configure display and caching options",
      "fields": ["units", "cache_ttl"]
    }
  ]
}

When validation_command is set, the agent calls your skill with that operation and the user's field values. Your skill can test the API key, verify a connection, or check permissions — and return success or a specific error message.

Pass-Through Config

When the agent invokes your skill, the user's configured values are available to your process. The config is persisted locally on the agent and merged with any platform-provided overrides at install time.

Here's how it flows:

1. User fills in the setup wizard (or the platform sends config during install)
2. Values are stored locally — secrets go to the encrypted vault, plain values to config.json
3. At invocation time, the agent resolves secrets from the vault and passes the full config to your skill as part of the invocation payload

Your skill receives the config in the request context:

{
  "operation": "get_weather",
  "payload": { "location": "Seattle" },
  "config": {
    "api_key": "resolved-from-vault",
    "units": "celsius",
    "cache_ttl": 300
  }
}

You never need to manage credential storage yourself. Declare x-secret, and the platform handles encryption, vault storage, and runtime resolution.

Capabilities

Optional flags for special skill behaviors:

{
  "capabilities": {
    "rag_provider": true
  }
}

Dependencies

Declare other skills your skill requires:

{
  "dependencies": [
    {
      "skill_id": "auth-helper",
      "min_version": "2.0.0"
    }
  ]
}

The agent checks dependencies at install time and warns the user if required skills are missing or unhealthy.

Documentation

Bundle docs with your skill for both users and the agent's LLM:

{
  "documentation": {
    "usage_guide": "docs/usage.md",
    "examples": [
      { "title": "Basic Weather Query", "file": "docs/examples/basic.md" },
      { "title": "Forecast Integration", "file": "docs/examples/forecast.md" }
    ]
  }
}

The agent's LLM can read your documentation to help users get started. Good docs = better user experience = more installs.

Complete Example

{
  "skill_id": "weather-lookup",
  "name": "Weather Lookup",
  "version": "1.0.0",
  "description": "Fetches current weather and forecasts for any location worldwide",
  "author": "Your Name",
  "license": "MIT",
  "tags": ["weather", "forecast", "location"],
  "execution_tier": 1,
  "entrypoint": {
    "type": "node",
    "command": "node",
    "args": ["dist/index.js"]
  },
  "capabilities": {},
  "dependencies": [],
  "config_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "api_key": {
        "type": "string",
        "title": "API Key",
        "description": "Your weather service API key",
        "x-secret": true
      },
      "units": {
        "type": "string",
        "title": "Units",
        "description": "Temperature units",
        "enum": ["celsius", "fahrenheit"],
        "default": "celsius"
      }
    },
    "required": ["api_key"]
  },
  "setup_steps": [
    {
      "step_id": "credentials",
      "title": "API Credentials",
      "description": "Enter your weather service API key",
      "fields": ["api_key"],
      "validation_command": "validate_credentials"
    },
    {
      "step_id": "preferences",
      "title": "Preferences",
      "description": "Choose your display preferences",
      "fields": ["units"]
    }
  ],
  "documentation": {
    "usage_guide": "docs/usage.md"
  }
}

Bookmark this page. You'll reference it every time you build a new skill.