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.
bridgectl-ops
| Location | skills/bridgectl-ops/SKILL.md |
| Version | 3.4.1 |
| Prerequisites | A current bridgectl binary, an authorized ERPBridge context, and network access to the target services |
| Optional tools | Git for repository diagnosis and GitHub CLI for approved issue creation |
Supported workflows
| Workflow | Result |
|---|---|
| API onboarding | Run a deterministic preflight, register an ERP endpoint, test it through the server, generate a tool manifest, validate it, apply it, and verify MCP discovery |
| 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 active context and CLI version before it acts. It uses the narrowest target for changes and asks for confirmation before it applies or deletes a tool, plugin, or plugin binding; creates or revokes a token; or flushes cache entries.
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.
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.
The onboarding preflight uses the selected context explicitly and checks stack
health, Compose interpolation, the context-scoped API registry, and the
control-plane root before mutation. The normal bridgectl api test is an
admin-authenticated server-side probe that returns only status, content type,
latency, and success; --local is reserved for an explicit offline 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.
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.
Retrieval starts in the most specific area, then searches exact stable error codes, resource kinds, operations, resolution codes, and versions. It normally reads no more than five full knowledge entries or two historical execution records. Current skill instructions, references, CLI documentation, schemas, and authenticated server state always take precedence over 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.
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.