ASCN Integrations

This document is normative. RFC2119 keywords (

MUST

SHOULD

MAY

) define required behavior.

Mission

Design and deliver missing capability as reusable ASCN integrations, then package them as user-visible plugins.

When To Use

Use this skill when a workflow task cannot be completed with existing handlers/triggers/tools.

Typical triggers:

missing handler for a required API/service
missing trigger type for required event source
schema/contract mismatch blocks reliable workflow composition
required UI ergonomics (
```
params_ui
```
, options, conditional fields) are missing

Required Inputs

The integrator MUST collect:

```
workspace_id
```
(UUID)
capability gap summary (what cannot be built today)
target use-cases (at least one concrete workflow scenario)
expected input/output contract (JSON-level)
auth/secret requirements
publish target (
```
user
```
plugin first, system copy later)

workspace_id

or contract expectations are missing, stop and request them.

Required MCP Tool Surface

```
control.docs.get
```
```
control.registry.list
```
```
control.registry.details
```
```
control.workflows.list
```
```
control.workflows.describe
```
```
control.workflows.validate
```
```
control.workflows.create
```
```
control.workflows.patch
```
```
control.workflows.activate
```
```
control.tools.ensure_export
```
```
control.tools.list_exports
```
```
control.plugins.create_plugin
```
```
control.plugins.update_plugin
```
```
control.plugins.list
```

Delivery Modes

Mode A: Workflow-backed integration (preferred first)

Use existing handlers to build a reusable workflow and export it through

Trigger.Tool

Mode B: Native integration (new handler/trigger code)

Use only when Mode A cannot satisfy latency, auth, determinism, or protocol constraints.

Native integrations MUST still be wrapped/published as plugins for user consumption.

Deterministic Flow

Discover existing capability (

control.registry.list

control.registry.details

control.tools.list_exports

Produce contract draft:
- canonical handler id (
```
Vendor.Action
```
  )
- ```
params_schema
```
  (input object)
- ```
returns_schema
```
  (output object)
Choose delivery mode (
```
A
```
or
```
B
```
) with explicit reason.
Implement integration.
Validate workflow/config contract (
```
control.workflows.validate
```
).

Activate export (

control.workflows.activate

control.tools.ensure_export

Bundle handlers into plugin (
```
control.plugins.create_plugin
```
then
```
update_plugin
```
if needed).
Verify plugin visibility with
```
control.plugins.list
```
and registry views.

Plugin Packaging Rules

Plugin name MUST be stable and vendor/domain-scoped (e.g.
```
StripeOps
```
,
```
CRMHubspot
```
).
Handler names MUST be canonical and collision-safe.
One plugin MAY contain multiple handlers if they share domain and auth model.
Plugin definitions SHOULD include UI metadata (
```
name
```
,
```
description
```
,
```
icon
```
,
```
tags
```
) before handoff.
Unwrapped
```
Trigger.Tool
```
exports MUST still be user-visible as flat
```
User.<Handler>
```
entries.
Wrapped/published handlers MUST be rendered as first-class plugin cards/forms with plugin metadata (
```
name
```
,
```
description
```
,
```
icon
```
) and handler
```
params_ui
```
.

Params UI Best Practices

params_ui

MUST be human-usable and contract-aligned.

Every key in
```
params_ui
```
SHOULD exist in
```
params_schema.properties
```
.
Localize labels/hints where possible (
```
en
```
,
```
ru
```
).

Prefer explicit controls:

string

string_multiline

number

boolean

options

array

object

string_json

Use conditional visibility for complex forms via
```
displayOptions.show
```
.
Put dangerous/advanced options behind conditional toggles.
Include safe defaults where deterministic behavior is expected.
Use
```
options
```
only for selectable values; use
```
displayOptions.show
```
only for conditional visibility.
Keep field order identical to the execution mental model (auth -> target -> behavior -> advanced).

Example conditional field pattern:

json

[
  {
    "key": "auth_mode",
    "control": "options",
    "label": {"en": "Auth mode"},
    "options": [
      {"value": "api_key", "label": {"en": "API key"}},
      {"value": "oauth", "label": {"en": "OAuth"}}
    ]
  },
  {
    "key": "api_key",
    "control": "string",
    "label": {"en": "API key"},
    "displayOptions": {"show": {"auth_mode": ["api_key"]}}
  }
]

Minimal

params_ui

field contract (recommended):

json

{
  "key": "string",
  "control": "string|string_multiline|number|boolean|options|array|object|string_json",
  "label": {"en": "Field label"},
  "hint": {"en": "Optional guidance"},
  "required": false,
  "default": null,
  "options": [
    {"value": "v1", "label": {"en": "Value 1"}}
  ],
  "displayOptions": {"show": {"other_key": ["match_value"]}}
}

Rules for this contract:

```
options
```
MUST exist only when
```
control=options
```
.
```
displayOptions.show
```
MUST reference keys that exist in the same
```
params_ui
```
.
```
required=true
```
fields SHOULD be present in
```
params_schema.required
```
.
Secret-bearing fields SHOULD use hints directing users to secrets, not literal defaults.

Security & Secrets

Credentials MUST come from secrets (
```
={{ $secrets.name }}
```
), never literals.
```
params_schema
```
SHOULD mark required secret-driven fields clearly.
Integration MUST document minimum secret set for successful invocation.

Output Contract

Every completion MUST include:

json

{
  "integration": {
    "mode": "workflow|native",
    "capability_status": "implemented",
    "handler_names": ["Vendor.Action"]
  },
  "plugin": {
    "plugin_name": "VendorOps",
    "created_or_updated": true
  },
  "verification": {
    "validated": true,
    "activated": true,
    "visible_in_plugins_list": true
  },
  "open_items": []
}

Hand-off Back To ASCN Operator

After integration delivery:

return canonical handler/plugin identifiers
return required secrets and minimal invocation payload
instruct caller to resume lifecycle operations with
```
ascn-operator
```

ascn-integrations

NPX Install

Tags

SKILL.md Content

ASCN Integrations

Mission

When To Use

Required Inputs

Required MCP Tool Surface

Delivery Modes

Mode A: Workflow-backed integration (preferred first)

Mode B: Native integration (new handler/trigger code)

Deterministic Flow

Plugin Packaging Rules

Params UI Best Practices

Security & Secrets

Output Contract

Hand-off Back To ASCN Operator