StreamNative Agent Skills

Agent skills that teach any skill-compatible AI agent how to manage StreamNative Cloud resources through StreamNative Cloud remote MCP tools or the snctl CLI. Distributed as the streamnative-agent-skills plugin. Built to the agentskills spec; installable as a Claude Code plugin or as portable skill directories in Cursor, Gemini CLI, OpenCode, Goose, Codex, and more.

At a glance: 7 domain skills · 48 guided workflows · 33 reference docs · 22 starter YAML manifests · 7 snctl smoke walkthroughs · 7 remote MCP smoke walkthroughs · 16 machine-readable smoke specs.

---

Quick start

After installing the plugin and setting up snctl, just ask your agent in natural language:

Create a serverless Pulsar instance named events in us-east-1.

Give me a service account with admin access and export its key.

Create a 3-partition Kafka topic user-events and produce 10 test messages.

Set up BYOC to my AWS account 123456789012 with a VPC in eu-west-1.

Deploy a Pulsar Function from word-count.jar that reads from topic in and writes to out.

The right skill activates based on the request. You never invoke skills explicitly — the agent picks.

---

Prerequisites

Pick one execution base:

1. Remote MCP (preferred when your agent exposes MCP tools): connect the StreamNative Cloud remote MCP server with org-level Cloud tools and/or fixed cluster-level Pulsar/Kafka tools enabled. Remote MCP server is public preview and disabled by default; org-level MCP and cluster-level MCP are both disabled by default and must be enabled separately in StreamNative Cloud UI. New clusters also start with cluster-level MCP disabled. The skills use sncloud_*, pulsar_*, and kafka_* MCP tools when available.
2. snctl fallback/baseline: install and authenticate snctl.

   curl -fsSL https://downloads.streamnative.cloud/snctl/install.sh | sh

   Or via Homebrew:

   brew install streamnative/streamnative/snctl

   Authenticate:
   • Interactive: snctl auth login
   • Automation: snctl auth activate-service-account --key-file ./key.json

Remote MCP cannot cover every local credential flow yet; keep snctl available for API keys, Cloud Secrets, service-account key export/activation, and local config/token tasks.

---

Install

Claude Code (plugin — recommended)

/plugin marketplace add streamnative/streamnative-agent-skills
/plugin install streamnative-agent-skills

Registers all seven currently documented skills at once. Plugin metadata: .claude-plugin/plugin.json.

Other skill-compatible agents

Clone the repo and point your agent at the relevant skills/<skill-name>/ directory. Each skill is a self-contained agentskills package.

git clone https://github.com/streamnative/streamnative-agent-skills.git
# Follow your tool's "add skill" flow (Cursor, Gemini CLI, OpenCode, Goose, Codex, etc.)

Selective install

Copy a single skills/<skill-name>/ directory into the agent's skills directory.

---

What's inside (the 7 skills)

Skill	Workflows	Covers	Activates on
cloud-core	7	Install, auth, config, context, API resources, logs	"install snctl", "log in", "switch org", "service account"
byoc-infrastructure	6	Cloud connections, environments, tiered-storage volumes	"BYOC", "my AWS/GCP/Azure account", "VPC CIDR", "tiered storage"
pulsar-clusters	6	Pulsar instance/cluster/gateway — serverless, dedicated, BYOC, BYOC Pro	"create cluster", "pulsarinstance", "scale brokers", "gateway"
kafka-clusters	7	Kafka Instance/KafkaCluster — dedicated, BYOC, BYOC Pro, AuthV2 contexts	"kafkacluster", "Kafka cluster", "throughput unit", "Kafka service context"
identity	7	Users, service accounts, roles, API keys, secrets, OIDC, identity pools	"grant access", "API key", "role binding", "OIDC", "federated login"
pulsar-admin	8	Tenants, namespaces, topics, subscriptions, Pulsar Functions	"tenant", "namespace", "topic", "produce/consume", "Pulsar function"
kafka-admin	7	Kafka topics, groups, partitions, Schema Registry, Kafka Connect	"Kafka topic", "consumer group", "schema registry", "Kafka Connect"

---

Features

Execution bases

• Remote MCP: first-class route when agent runtime exposes StreamNative Cloud remote MCP tools. Org-level control-plane uses domain tools such as sncloud_byoc_read/write, sncloud_identity_read/write, sncloud_clusters_read/write, plus sncloud_resource_catalog and sncloud_resource_schema. Data-plane admin uses feature-gated Pulsar/Kafka MCP tools after fixed cluster binding or sncloud_context_use_cluster; both require cluster-level MCP enabled for the target cluster in StreamNative Cloud UI.
• snctl: portable fallback route and baseline for local credential/config operations and workflows not exposed by remote MCP.

Remote MCP write tools expect JSON-string manifests and a dry-run-first workflow. Do not use generic sncloud_resources_* names; current public contract is domain-scoped.

Resource kinds covered (control plane)

Every manageable control-plane resource kind is owned by exactly one skill:

• Foundational: CloudConnection, CloudEnvironment, Volume
• Pulsar infrastructure: PulsarInstance, PulsarCluster, PulsarGateway
• Kafka infrastructure: Instance, KafkaCluster, controller-managed SnSchemaRegistry
• Identity & access: User, ServiceAccount, ServiceAccountBinding, Role, RoleBinding, APIKey, Secret, OIDCProvider, IdentityPool
• Messaging: Subscription (control-plane kind)

Deployment types

PulsarInstance supports serverless, dedicated, BYOC, and BYOC Pro. Kafka Instance / KafkaCluster currently supports dedicated, dedicated-pro, BYOC, and BYOC Pro; serverless KafkaCluster is not supported today.

Data-plane coverage

• Pulsar: tenants, namespaces, topics (persistent + non-persistent, partitioned + non-partitioned), subscriptions (all 4 types), permissions, Pulsar Functions, produce/consume.
• Kafka: topics, consumer groups, partitions, Schema Registry (AVRO / JSON / Protobuf), produce/consume. Kafka Connect is available for PulsarCluster/KSN contexts; direct KafkaCluster contexts may not expose Connect.

Tooling bundled with this repo

• scripts/install-snctl.sh — install a pinned snctl from the canonical GCS bucket.
• scripts/validate-skills.sh — validate every skill against the agentskills spec (name/dir parity, description presence, ≤500-line body).
• scripts/check-help-drift.sh — parse every snctl … command cited in SKILL.md files and run --help against your installed version to catch drift.
• scripts/check-manifests.sh — dry-run snctl apply -f on every shipped YAML manifest.
• GitHub Actions workflow that runs the three checkers on every PR.

---

How it works

Skills are Markdown documents with YAML frontmatter. They live in skills/<name>/SKILL.md plus adjacent references/ and assets/ directories.

Progressive disclosure

Agents load content lazily to keep the context window small:

1. Metadata tier (~100 tokens per skill): only name + description are pre-loaded. The agent uses these to decide activation.
2. Instructions tier (≤500 lines per skill): full SKILL.md body loads only when the skill activates for a request.
3. References tier: files under references/ and manifests under assets/manifests/ load only when the body explicitly points to them.

Result: a user asking "create a Kafka topic" only pays the token cost for kafka-admin, not all 7 skills at once.

Activation model

1. User sends a request.
2. Agent matches the request against every skill's description field.
3. Best-matching skill activates → body loads.
4. If the body says "see references/foo.md for X", the agent loads that file only when X comes up.
5. Agent uses available StreamNative Cloud remote MCP tools, or runs snctl commands from its shell tool, following the skill's workflows, flags, and pitfalls.

Skill boundaries

• One resource kind = one owning skill. No duplication.
• Cross-skill referrals are explicit. E.g., pulsar-clusters tells the agent to open byoc-infrastructure first when the user wants a BYOC deployment.
• Description strings are keyword-distinct to prevent collisions (e.g., Pulsar Functions appear in two skills but each disclaims the other in its description).

See the design spec for the full ownership table and decomposition rationale.

Why guidance-only (no executable scripts)

The skills ship expert procedural knowledge; the agent uses its own MCP or shell tools directly. This keeps skills portable across every agentskills-compatible agent without requiring a script runtime. scripts/ is reserved for future opt-in.

---

Development

• Design spec: docs/superpowers/specs/ — decomposition decisions, ownership table.
• Implementation plan: docs/superpowers/plans/ — task-by-task build order.
• Smoke-test walkthroughs: docs/smoke-tests/ — snctl route acceptance criteria.
• Machine-readable smoke specs: tests/smoke-specs/ — runnable with scripts/smoke-runner.py; require real test/staging credentials for non---dry-run execution.
• Smoke benchmark reports: scripts/benchmark-report.py aggregates smoke-runner summary.json files into reports/benchmark-<timestamp>.{json,md,csv} for same-case snctl vs remote MCP token/time comparisons. The runner can invoke Claude Code or Codex adapters.
• Remote MCP smoke-test walkthroughs: docs/smoke-tests/remote-mcp/ — MCP route acceptance criteria.
• CI: .github/workflows/validate.yml — runs the three scripts on every PR.

Local validation

./scripts/install-snctl.sh     # or skip if snctl already on PATH
./scripts/validate-skills.sh   # agentskills spec + structural
./scripts/check-help-drift.sh  # every cited snctl command exists
./scripts/check-manifests.sh   # every shipped YAML dry-runs

Adding a skill or snctl resource

See CONTRIBUTING.md.

---

Versioning

• Plugin: semver, bumped on any skill change (starts at 0.1.0).
• Each skill: its own metadata.version in frontmatter, bumped when that skill's content changes.
• snctl compatibility: each skill pins snctl-min-version in frontmatter. The current floor is 1.5.0 — aligned with when snctl context stabilized.

---

License

Apache-2.0. See LICENSE.