diff --git a/.agents/skills/create-stackpack/SKILL.md b/.agents/skills/create-stackpack/SKILL.md new file mode 100644 index 0000000..c6a72a4 --- /dev/null +++ b/.agents/skills/create-stackpack/SKILL.md @@ -0,0 +1,115 @@ +--- +name: create-stackpack +description: Create or extend SUSE Observability StackPacks for a product or technology using OpenTelemetry data, semantic conventions, mappings, presentations, and monitors. +--- + +# Create a StackPack + +Start with the product or technology the user wants to observe. +Use the current declarative scaffold and adapt it to that integration. + +## Sources + +Read the official [creation guide](https://documentation.suse.com/cloudnative/suse-observability/latest/en/setup/custom-integrations/create.html) before starting. +Follow its reference links for the settings being changed. +Use the [StackPack reference](https://documentation.suse.com/cloudnative/suse-observability/latest/en/setup/custom-integrations/stackpacks.html) for project structure, versioning, and CLI commands. +Use [contrib-stackpacks](https://github.com/StackVista/contrib-stackpacks/tree/main/stackpacks) for working examples: + +- `open-telemetry`: component and relation mappings, presentations, and monitors. +- `otel-k8s-crd`: topology from Kubernetes custom-resource events. +- `suse-observability`: presentations and monitors for existing platform components. + +Read only the relevant example files. Prefer current schemas over copying an entire integration. + +## Telemetry design and discovery + +Use OpenTelemetry as the base data model. Prefer collection through the OpenTelemetry Collector. +Find existing receivers or instrumentation for the target technology before proposing custom collection. +Identify the required signals, resource identity, and Collector configuration. +If collection is missing, provide the required configuration and ingestion instructions with the StackPack. + +Use the relevant [OpenTelemetry semantic conventions](https://github.com/open-telemetry/semantic-conventions) for resource attributes, metrics, spans, and logs. +Read the technology-specific conventions and check their stability and support in the selected receiver or instrumentation. +Prefer standard names and units. Document extensions only where no suitable convention exists. +Compare conventions with observed telemetry, including metric-name and label transformations during ingestion. +If they differ, make collection normalization or mapping compatibility explicit. + +Use the official [MCP connection guide](https://documentation.suse.com/cloudnative/suse-observability/latest/en/use/ai-assistant/mcp-server.html) to connect your assistant to the SUSE Observability MCP server. +When it is available, use its query tools to inspect data for the target technology. +Read the relevant MCP domain guides first and establish that MCP and CLI target the intended instance. +Scope queries to relevant resources and time ranges. +Inspect available metrics, labels, topology, traces, and logs to establish identifiers and usable signals. +Use those results to author mappings and queries, then check their behavior after deployment. +If MCP is unavailable, use CLI queries or supplied telemetry samples. +If data is absent, document the collection gap and leave runtime behavior unverified. + +## CLI and authentication + +Check whether `sts` is available. +If it is missing, ask whether the user will install it. +Direct them to the **CLI** main menu item in the SUSE Observability UI for installation. +Wait for installation before running CLI commands. Continue independent design work while waiting. +Use the latest stable Go `sts` CLI from [stackstate-cli releases](https://github.com/StackVista/stackstate-cli/releases/latest). +Use the official [CLI installation guide](https://documentation.suse.com/cloudnative/suse-observability/latest/en/setup/cli/cli-sts.html) for installation details. +Resolve the release on each task. Do not embed a fixed CLI version in this skill. +Compare the installed version with that release and ask the user to upgrade when necessary. +Use the matching operating-system and architecture artifact, and check its published checksum before execution. + +The user authenticates the CLI to the correct SUSE Observability instance. +Do not log in, change contexts, request tokens, or read credential files. +If authentication fails, ask the user to authenticate and continue local work. +Before instance operations, establish the intended target from the user's request without displaying credentials. +Inspect command help from the installed CLI when flags or server compatibility are unclear. + +## Create and customize + +1. Establish the target product or technology, integration name, and desired topology or monitoring behavior. + Use telemetry discovery to select signals and resource attributes. Ask for missing evidence rather than inventing it. +2. Scaffold into a new directory: + + ```bash + sts stackpack scaffold --name my-stackpack --display-name "My StackPack" + ``` + +3. Read the generated `README.md` and `stackpack.yaml`. Preserve the required settings and resource paths. +4. Replace demo content with the requested integration. Keep identifiers unique within the pack namespace. + Align component identifiers, relation endpoints, monitor bindings, and presentation selectors. + Use actual telemetry labels in queries and meaningful production thresholds in monitors. + Add only the mappings, presentations, monitors, and resources the integration needs. +5. Package from the StackPack directory: + + ```bash + sts stackpack package -d . + ``` + +Packaging checks local structure. It does not prove server schema validity or successful installation. + +## Validate and deploy + +For authorized instance validation, use: + +```bash +sts stackpack validate -d . +``` + +Validation sends the package to the configured server. +For CI without an instance, use the offline validator described in the StackPack reference, pinned to the target server release. +For an authorized development deployment, use: + +```bash +sts stackpack test-deploy -d . --yes +``` + +This command uploads and installs or upgrades the pack with a test version suffix. +It can upgrade an existing installation. It is not a dry run. +Repeat after edits within the authorized scope. +Check the resulting topology, relations, metric queries, monitor bindings, and presentations against matching telemetry. +Use MCP `topology_query` and `component_get` to check component identities, properties, and relation endpoints. +Use `metrics_query_instant` or `metrics_query_range` to run the actual PromQL queries, and `metrics_bound` to check component bindings. +Use `monitors_overview`, `monitor_config`, and `monitor_violations` to check installed monitors and their results. +Verify rendered presentations in the SUSE Observability UI; MCP queries do not establish their visual correctness. + +For delivery, package again and report the generated `.sts` path. +If upload is requested, run `sts stackpack upload --file `. +Upload makes a version available. Installation is a separate operation. +Report which local and instance checks passed, and which remain untested. diff --git a/.claude/skills/create-stackpack b/.claude/skills/create-stackpack new file mode 120000 index 0000000..bd49a91 --- /dev/null +++ b/.claude/skills/create-stackpack @@ -0,0 +1 @@ +../../.agents/skills/create-stackpack \ No newline at end of file diff --git a/README.md b/README.md index 46c1a2d..d8a2e97 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,11 @@ # contrib-stackpacks SUSE Observability Community Stackpacks + +Use the [Create a StackPack agent skill](.agents/skills/create-stackpack/SKILL.md) to +create or extend an integration with the latest StackPack documentation, the `sts` +CLI, and MCP queries for runtime validation. + +Codex, Antigravity, and Gemini CLI load the skill from `.agents/skills/`. +Claude Code loads it through the `.claude/skills/create-stackpack` symlink. +For other projects, copy the `create-stackpack` directory into your assistant's +supported skill directory.