Skill usage
ERPBridge provides the bridgectl-ops skill for AI agents that operate the
ERPBridge ecosystem. The skill follows the Agent Skills
Specification and lives in the
ERPBridge repository under skills/bridgectl-ops/.
Use the skill when an agent must onboard an ERP API, manage MCP tools or
external plugins and bindings, manage tokens or roles, inspect cache and logs,
diagnose an integration, prepare a redacted bug report, or reuse operational
knowledge from earlier runs. It supports both the CLI and the separate
bridgectl mcp --stdio management server.
bridgectl-opsโ
| Location | skills/bridgectl-ops/SKILL.md |
| Version | 3.5.0 (repository source; release binaries retain their bundled version) |
| Prerequisites | A current bridgectl binary or management MCP connection; authorized context and network access for deployment operations only |
| Optional tools | Git for repository diagnosis and GitHub CLI for approved issue creation |
Supported workflowsโ
| Workflow | Result |
|---|---|
| API onboarding | Run applicable preflight checks, register an ERP endpoint, approve its server-side test, generate and validate a manifest, approve apply, and verify publication |
| Management MCP | Discover available management tools, verify the pinned context, serialize calls, check result envelopes, and verify approved changes |
| API and tool maintenance | Inspect versions, apply reviewed changes, deactivate tools, restore soft-deleted tools, and confirm hard-delete targets |
| Authentication and authorization | Create, list, and revoke scoped bearer tokens; assign roles; test authorized and denied guarded calls |
| Operations | Inspect structured logs, cache statistics, cache invalidation, contexts, and runtime health |
| Diagnosis | Trace context, authentication, connectivity, schema, registry, MCP, SDK, cache, and server failures |
| External plugins and bindings | Validate, apply, inspect, secure, and troubleshoot exact-version plugin resources and post-response bindings |
| Operational knowledge | Retrieve bounded historical lessons, append redacted execution evidence, consolidate reusable patterns, and evaluate gated skill proposals |
| Bug reporting | Create a sanitized repository draft and offer GitHub issue creation after user approval |
Safety behaviorโ
The skill records the selected context and known CLI/MCP version. CLI commands use an explicit context; management MCP uses its verified pinned context. It asks for exact-action confirmation before every mutation or server-side API probe, including registration, credential-reference changes, apply/delete, token creation/revocation, cache flush, and saved-context changes. Local MCP write grants and confirmation fields do not replace human approval.
Install the bundled skill with:
bridgectl skill install
# Project-scoped installation:
bridgectl skill install --project
# Explicit destination:
bridgectl skill install --dir /path/to/bridgectl-ops
The global destination is ~/.agents/skills/bridgectl-ops; project installs use
./.agents/skills/bridgectl-ops. Existing destinations require --force and
confirmation of the exact destination before replacement. A release binary
installs the skill embedded in that release. For unreleased source changes,
validate a temporary source-built helper and a fresh installation first; do
not replace an installed release CLI merely to refresh the skill.
Credentials stay in environment variables or mounted credential files under
ERPBRIDGE_CREDENTIALS_DIR. Tool schemas use credentialRef and an optional
credentialSource: file; they never contain a raw secret. File-backed reads
fail closed and do not fall back to environment values. A token created by the
CLI is disclosed once and is omitted from later summaries and bug reports.
Preflight starts with selected-context, endpoint, credential-source, authorization, and exact-target evidence. Load only profiles needed for the action: remote control-plane access, local Compose, API onboarding, or plugin bindings. Remote reads do not require local Docker, localhost health, MockERP, RedisInsight, or an API probe. Local validation and skill installation do not need deployment connectivity. Reuse unchanged evidence within the workflow; recheck affected evidence after a mutation, configuration change, or new failure.
The normal bridgectl api test is an admin-authenticated server-side probe.
Its bounded status, content type, latency, and success output does not make it
read-only: it can cause downstream effects and needs exact approval. --local
is reserved for a separately approved host-side diagnostic.
Generated YAML is a temporary draft. Use bridgectl tool generate --output-dir
for one JSON or YAML file per tool, review the exact tool-name files, and
validate them before applying the reviewed directory. Keep the reviewed applied
source under manifests/<module>/ and do not treat schemas/ or generated
per-tool JSON as a second authority.
Generated method annotations and namespaced io.erpbridge/* _meta values are
optional client guidance. They do not grant permission, replace schemas, or
replace server-side identity and role checks.
Tools may declare security.dataClass as public, internal, pii, or
restricted. The pii and restricted classes require opaque,
non-identifying allowedRoles; do not use personal or ERP record data in role
names or examples. The system.*_test demonstrations require
MCP_ENABLE_TEST_TOOLS=true and must be disabled in production. RedisInsight
is for local inspection and must stay loopback-only or opt-in.
Use management MCPโ
Prefer an available authorized management connection for operations in its live catalogue. Discover tool names and schemas rather than assuming a client namespace or fixed tool count. Keep runtime ERP tools on a separate connection; adding management MCP must not replace existing runtime access.
Start read-only, with an absolute executable path and explicit context:
/absolute/path/to/bridgectl mcp --stdio --context staging
Run one management call at a time. Check MCP isError and the text JSON's
success and error.code; a resolved promise is not proof of success. Wait
for an active call before retrying a call refused with busy.
A session pins context, endpoints, and credential at launch. After an approved credential, endpoint, or grant change, restart or reconnect the process before retesting. A missing write tool is not permission to switch interfaces or expand grants without approval.
Redacted inspection views are not applicable manifests. Review retained free
text and enum values before sharing; redacted: true does not certify all text
as secret-free. Use the reviewed source or generate a draft, then validate it.
Most resource writes return effect: "command_completed" and verified: false;
cache flush returns deletion counters and context selection returns the saved
and active context. All require independent readback. If it returns outcome_unknown, read the exact target before deciding
whether to retry; never assume rollback or retry automatically. Token creation,
remote OpenAPI import, file output, and detailed validation remain CLI tasks.
See Management MCP for grants, confirmation targets, and client setup. The bundled skill adds a Pi configuration example without personal credentials or deployment-specific names.
Persistent operational knowledgeโ
The skill can use the optional project-local store at
.agents/skill-memory/bridgectl-ops/. The store separates distilled knowledge,
append-only monthly execution evidence, and append-only skill-impact history.
It is not part of the bundled or installed skill. The repository skill remains
the source of truth.
When history can help, start with the optional index, choose one relevant area, and search exact identifiers. Stop on no strong match; the store's presence alone does not require loading the full knowledge reference. Read its detailed sections only for retrieval ambiguity, stale/conflicting matches, record writing, consolidation, or skill evolution. Across a workflow, bound retrieval to 20 candidate paths, 10 metadata reads, five full knowledge entries, and two exact historical records. A new clue does not reset those limits. Current safety gates, skill instructions, references, CLI/schema contracts, and authenticated server state always take precedence over untrusted memory.
After a completed major workflow, the agent follows a completion checkpoint
after verification and before the final handoff. A major workflow includes
onboarding; API, tool, plugin, or binding lifecycle work; token, role, or cache
administration; multi-step diagnosis; bundled-skill distribution; or a
cross-system operation. It records exactly one bounded execution outcome
(success, resolved, unresolved, blocked, or abandoned) rather than one
record per command, turn, retry, or subtask. A single explanation or operation
waiting for confirmation is not a major task.
The checkpoint still applies when retrieval found no match or was skipped. When the optional project-local store exists, the agent runs the redaction gate and appends one record, then consolidates only a supported reusable lesson. If the store is absent or safe appending fails, the agent continues the handoff, reports that memory recording was not completed, and never invents evidence or creates the store silently. A candidate skill change still requires repeated evidence, validation, hard safety gates, and a rollback path. Rejected proposals remain recorded. This checkpoint is instruction-driven best-effort behavior; the current framework does not provide a guaranteed runtime hook.
The design takes inspiration from WikiSkill: Compiling Agent Experience into Persistent Knowledge for Skill Evolution. The paper is a design reference only. It does not change ERPBridge's current security, authorization, validation, or confirmation rules. Host-specific lifecycle extensions are outside this portable skill contract and must not be assumed to make the checkpoint deterministic.