Skip to content

Commit 8324129

Browse files
muralibasanimuralibasani
authored
Merge pull request #1 from Aiven-Open/HelenMel-patch-1
Revise SECURITY.md for clarity and structure
2 parents 1cd3e41 + 1fdfacc commit 8324129

3 files changed

Lines changed: 354 additions & 3 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 275 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,275 @@
1+
# Contributing to aiven-skills-bundle
2+
3+
Thank you for your interest in contributing! This repository is a curated collection of
4+
**AI agent skills** for Aiven — structured instructions and supporting code that let AI
5+
assistants (Cursor, Claude CLI, etc.) manage Aiven-managed data services end-to-end.
6+
7+
If you have an idea for a new skill or an improvement to an existing one, please read
8+
this guide before opening a pull request.
9+
10+
---
11+
12+
## Table of Contents
13+
14+
1. [Repository Layout](#repository-layout)
15+
2. [Skill Structure](#skill-structure)
16+
3. [SKILL.md Requirements](#skillmd-requirements)
17+
4. [Quality Guidelines](#quality-guidelines)
18+
5. [Testing & Verification](#testing--verification)
19+
6. [Opening a Pull Request](#opening-a-pull-request)
20+
7. [Commit Messages](#commit-messages)
21+
8. [Security](#security)
22+
23+
---
24+
25+
## Repository Layout
26+
27+
```
28+
aiven-skills-bundle/
29+
├── skills/
30+
│ └── <skill-name>/ # one directory per skill
31+
│ ├── SKILL.md # required — agent instructions
32+
│ ├── reference.md # optional — CLI cheat sheet / troubleshooting
33+
│ ├── scripts/ # optional — shell scripts invoked by the skill
34+
│ └── templates/ # optional — code templates copied to the workspace
35+
├── README.md
36+
├── CONTRIBUTING.md
37+
└── SECURITY.md
38+
```
39+
40+
Each skill lives in `skills/<skill-name>/`. The name must be lowercase, hyphen-separated,
41+
and describe both the Aiven service and the tooling used (e.g. `aiven-kafka-setup-avn`).
42+
43+
---
44+
45+
## Skill Structure
46+
47+
A minimal skill contains only `SKILL.md`. A full skill looks like:
48+
49+
```
50+
skills/aiven-kafka-setup-avn/
51+
├── SKILL.md
52+
├── SERVICE_CREATION_AVN.md # interactive region/plan selection detail
53+
├── reference.md # avn CLI cheat sheet
54+
├── scripts/
55+
│ ├── setup_aiven_kafka.sh
56+
│ ├── run_producer.sh
57+
│ ├── run_consumer.sh
58+
│ ├── generate_orders.py
59+
│ ├── verify_output.py
60+
│ └── teardown.sh
61+
└── templates/
62+
├── order.avsc
63+
├── producer_consumer_java/
64+
│ ├── Producer.java
65+
│ ├── Consumer.java
66+
│ ├── Order.java
67+
│ └── pom.xml
68+
└── producer_consumer_python/
69+
├── producer.py
70+
├── consumer.py
71+
├── order.py
72+
└── requirements.txt
73+
```
74+
75+
### Scripts
76+
77+
- Must be `bash` or `python3` (using only the standard library — no additional dependencies).
78+
- Must be idempotent: running them twice must not break anything.
79+
- Must not print credentials or secrets to stdout/stderr.
80+
- Passwords must only ever be stored in environment variables and verified by length
81+
(`${#VAR}`), never echoed.
82+
83+
### Templates
84+
85+
- Code templates are copied into the user's workspace at runtime; they must compile
86+
and run without modification once environment variables are sourced.
87+
- Java templates require Java 17+ and Maven. Python templates require Python 3.9+.
88+
- All production-quality conventions apply: structured logging (no bare `print`),
89+
specific exception handling, type hints (Python), linting (Checkstyle / PEP 8).
90+
91+
---
92+
93+
## SKILL.md Requirements
94+
95+
`SKILL.md` is the file the AI agent reads. It must start with a YAML front-matter block:
96+
97+
```yaml
98+
---
99+
name: aiven-<service>-setup-<tool>
100+
description: >
101+
One or two sentences describing WHAT the skill does and WHEN to trigger it.
102+
Include natural-language trigger phrases (e.g. "create a Kafka cluster",
103+
"set up Kafka", "start a Kafka service").
104+
version: "0.1"
105+
license: Apache-2.0
106+
allowed-tools: Bash(avn:*) Bash(jq:*) Read
107+
---
108+
```
109+
110+
| Field | Requirement |
111+
|---|---|
112+
| `name` | Lowercase, hyphens only, max 64 chars, unique in this repo |
113+
| `description` | Max 1 024 chars; include natural-language trigger phrases |
114+
| `version` | Semantic version string, quoted (`"0.1"`, `"1.0"`) |
115+
| `license` | Must be `Apache-2.0` |
116+
| `allowed-tools` | Explicit allowlist of Bash commands the agent may run |
117+
118+
### Required Sections
119+
120+
Every `SKILL.md` must contain these sections (in order):
121+
122+
1. **Prerequisites** — what the agent must verify before doing anything (CLI login,
123+
tool versions, language runtimes). Include a clear stop-and-wait instruction if a
124+
prerequisite is not met.
125+
2. **User input** — before running any scripts, it is good practice to ask the user
126+
clarifying questions (e.g. cloud region, service plan, language preference). Use the
127+
`AskQuestion` tool so the agent collects all required information upfront rather than
128+
interrupting the workflow mid-execution. Document the exact questions and their
129+
default values here.
130+
3. **Step-by-step instructions** — numbered, each with a concrete shell command or
131+
agent action and a verification step.
132+
4. **Teardown** — how to clean up. The agent must **not** run teardown automatically;
133+
it should inform the user how to do it when they are ready.
134+
5. **File Reference** — a table mapping every supporting file to its purpose.
135+
136+
### Agent Behaviour Constraints
137+
138+
Document these explicitly in `SKILL.md` when relevant:
139+
140+
- **Fail fast on missing runtimes.** If `java` or `python3` is absent and required,
141+
stop immediately. Do not advise the user how to install programming languages.
142+
- **Advise on missing CLI tools.** If `avn`, `jq`, or similar tools are absent, suggest
143+
the install command (e.g. `python3 -m pip install aiven-client`), but first check
144+
that the required installer (`python3`) is available.
145+
- **Never read secrets.** Do not `cat` or `echo` files that contain passwords (e.g.
146+
`env.sh`). Verify credentials by length only.
147+
- **Always run end-to-end.** A skill that creates a service but never runs a working
148+
example is incomplete. Every skill must produce a verifiable, runnable result.
149+
150+
---
151+
152+
## Quality Guidelines
153+
154+
| Area | Requirement |
155+
|---|---|
156+
| **Completeness** | The agent must reach a runnable end state without human intervention (beyond answering prompted questions). |
157+
| **Verifiability** | Every significant step must include a check command so the agent can confirm success before proceeding. |
158+
| **Idempotency** | Scripts must tolerate being run more than once (e.g. `avn service create` should check existence first). |
159+
| **No hardcoded secrets** | Credentials, passwords, and tokens must come from environment variables, never from files committed to the repo. |
160+
| **Language quality** | Code templates must meet the same bar as production code: structured logging, specific exception handling, linting passes. |
161+
| **Minimal scope** | One skill, one workflow. If you need to cover multiple tools (e.g. `avn` vs Terraform vs REST API), create separate skills. |
162+
163+
---
164+
165+
## Testing & Verification
166+
167+
Because the expected output of a skill is a **running Aiven service with a working
168+
example**, testing is done through an agentic IDE or CLI tool, not a unit test suite.
169+
170+
### Option A — Cursor (Agentic IDE)
171+
172+
1. Open this repository in Cursor.
173+
2. Open a new chat in **Agent** mode.
174+
3. Type a natural-language trigger phrase, for example:
175+
176+
```
177+
Create me a simple Kafka cluster
178+
```
179+
180+
4. Observe the agent read `SKILL.md`, ask any required questions, and execute all steps
181+
autonomously.
182+
5. Verify the final output by checking that `orders_completed.csv` contains the expected
183+
rows (or whatever the skill's verification step specifies).
184+
185+
### Option B — Claude CLI
186+
187+
```bash
188+
claude "create me a simple Kafka"
189+
```
190+
191+
The Claude CLI will discover `SKILL.md` in the repository context and follow the
192+
instructions end-to-end.
193+
194+
### What "passing" looks like
195+
196+
A skill is considered verified when:
197+
198+
- [ ] All prerequisite checks pass (or the agent stops correctly on failure).
199+
- [ ] The cloud service reaches `RUNNING` state.
200+
- [ ] The producer runs and exits cleanly.
201+
- [ ] The consumer runs and exits cleanly.
202+
- [ ] The verification script (`verify_output.py` or equivalent) reports success.
203+
- [ ] The agent prints teardown instructions without running them automatically.
204+
205+
If **any** of the above steps fail, the skill is not ready to merge.
206+
207+
---
208+
209+
## Opening a Pull Request
210+
211+
1. **Fork** the repository and create a branch:
212+
213+
```bash
214+
git checkout -b feat/aiven-pg-setup-avn
215+
```
216+
217+
2. **Add your skill** under `skills/<skill-name>/`.
218+
219+
3. **Test end-to-end** using Cursor or the Claude CLI (see [Testing](#testing--verification)).
220+
Include a brief description of your test run in the PR body (which cloud provider,
221+
which plan, which language template).
222+
223+
4. **Open a pull request** with:
224+
- A clear title following [Conventional Commits](#commit-messages) style.
225+
- The PR body describing:
226+
- What the skill does and when it triggers.
227+
- How you tested it (agentic IDE / CLI, region, plan, language).
228+
- Any known limitations or follow-up work.
229+
230+
5. Stay responsive to review feedback. We may ask for additional verification steps or
231+
code changes before merging.
232+
233+
---
234+
235+
## Commit Messages
236+
237+
This project follows the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
238+
specification. Please use one of these types:
239+
240+
| Type | When to use |
241+
|---|---|
242+
| `feat` | New skill or new capability in an existing skill |
243+
| `fix` | Bug fix in a script, template, or instruction |
244+
| `docs` | Changes to `SKILL.md`, `reference.md`, `README.md`, or `CONTRIBUTING.md` |
245+
| `refactor` | Code restructuring with no behaviour change |
246+
| `test` | New or updated verification scripts |
247+
| `chore` | Dependency updates, CI, tooling |
248+
249+
**Examples:**
250+
251+
```
252+
feat(aiven-pg-setup-avn): add PostgreSQL skill with psql template
253+
fix(aiven-kafka-setup-avn): handle avn schema create missing in older CLI versions
254+
docs(aiven-kafka-setup-avn): clarify TRUSTSTORE_PASSWORD in SERVICE_CREATION_AVN.md
255+
```
256+
257+
For guidance on writing good commit messages, see
258+
[Chris Beams' post](https://cbea.ms/git-commit/).
259+
260+
---
261+
262+
## Security
263+
264+
**Do NOT include in any commit:**
265+
266+
- API keys, passwords, or tokens.
267+
- Hardcoded Aiven project names or account IDs.
268+
- Output of `env.sh` or any file containing credentials.
269+
- Any `avn service user-list` output or similar.
270+
271+
All credential handling must go through environment variables. Verify values by length
272+
(`${#VAR} -gt 0`), never by printing them.
273+
274+
To report a security vulnerability, follow the process described in
275+
[SECURITY.md](SECURITY.md).

‎README.md‎

Lines changed: 54 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,59 @@
11
# aiven-skills-bundle
2-
A curated collection of AI-ready skills for Aiven. This repository enables developers to manage, monitor, and scale Aiven-managed data services directly through AI code editors like Cursor and Claude.
2+
3+
A curated collection of AI agent skills for Aiven. This repository enables developers
4+
to manage, monitor, and scale Aiven-managed data services directly through AI code
5+
editors like Cursor and Claude CLI.
6+
7+
## What is a Skill?
8+
9+
A **skill** is a self-contained package of structured instructions and supporting code
10+
that an AI agent reads and executes step-by-step. Each skill includes:
11+
12+
- A `SKILL.md` instruction file — the agent's source of truth for the entire workflow.
13+
- Optional supporting assets: shell scripts, code templates, Avro schemas, reference docs.
14+
15+
> **Key principle:** A skill is not documentation. The agent follows it literally and
16+
> produces a working, verifiable result — without manual intervention beyond answering
17+
> a few upfront questions.
18+
19+
## How to Use a Skill
20+
21+
Skills work with any agentic AI tool that can read files from this repository.
22+
23+
### Cursor (Agentic IDE)
24+
25+
1. Open this repository in Cursor.
26+
2. Start a new chat in **Agent** mode.
27+
3. Type a natural-language trigger, for example:
28+
29+
```
30+
Create me a simple Kafka cluster
31+
```
32+
33+
4. The agent reads the matching `SKILL.md`, asks any required clarifying questions
34+
(region, plan, language), and drives the entire workflow — service creation,
35+
configuration, and a running producer/consumer example — autonomously.
36+
37+
### Claude CLI
38+
39+
```bash
40+
claude "create me a simple Kafka"
41+
```
42+
43+
The CLI discovers `SKILL.md` in the repository context and follows the instructions
44+
end-to-end, prompting you only when a decision is needed.
45+
46+
---
347

448
## Available Skills
549

6-
| Skill Name | Command | Description |
7-
|------------|---------|-------------|
50+
| Skill Name | Trigger phrase | Description |
51+
|------------|----------------|-------------|
852
| Aiven Kafka Setup (avn CLI) | `aiven-kafka-setup-avn` | Create and configure an Apache Kafka cluster using the `avn` CLI tool, including SASL_SSL auth, Schema Registry, and a working producer-consumer example. |
53+
54+
---
55+
56+
## Contributing
57+
58+
Want to add a new skill or improve an existing one? See [CONTRIBUTING.md](CONTRIBUTING.md)
59+
for the skill structure, `SKILL.md` format, testing requirements, and PR guidelines.

‎SECURITY.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Security policy
2+
3+
## Supported versions
4+
5+
We release patches for security vulnerabilities. Which versions are eligible to receive such patches depend on the CVSS v3.0 Rating:
6+
7+
| CVSS v3.0 | Supported Versions |
8+
|-----------|---------------------|
9+
| 4.0-10.0 | Most recent release |
10+
11+
## Reporting a vulnerability
12+
13+
Please report (suspected) security vulnerabilities to our **[bug bounty program](https://bugcrowd.com/aiven-mbb-og)**. You will receive a response from us within 2 working days. If the issue is confirmed, we will release a patch as soon as possible depending on impact and complexity.
14+
15+
## Qualifying vulnerabilities
16+
17+
Any reproducible vulnerability that has a severe effect on the security or privacy of our users is likely to be in scope for the program.
18+
19+
We generally **aren't** interested in the following issues:
20+
* Social engineering (e.g. phishing, vishing, smishing) attacks
21+
* Brute force, DoS, text injection
22+
* Missing best practices such as HTTP security headers (CSP, X-XSS, etc.), email (SPF/DKIM/DMARC records), SSL/TLS configuration.
23+
* Software version disclosure / Banner identification issues / Descriptive error messages or headers (e.g. stack traces, application or server errors).
24+
* Clickjacking on pages with no sensitive actions
25+
* Theoretical vulnerabilities where you can't demonstrate a significant security impact with a proof of concept.

0 commit comments

Comments
 (0)