codehava-agent-kit 1.0.0 → 2.0.0

package/templates/.agent/skills/gemini-api-dev/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: gemini-api-dev
+description: "The Gemini API provides access to Google's most advanced AI models. Key capabilities include:"
+risk: unknown
+source: community
+date_added: "2026-02-27"
+---
+
+# Gemini API Development Skill
+
+## Overview
+
+The Gemini API provides access to Google's most advanced AI models. Key capabilities include:
+- **Text generation** - Chat, completion, summarization
+- **Multimodal understanding** - Process images, audio, video, and documents
+- **Function calling** - Let the model invoke your functions
+- **Structured output** - Generate valid JSON matching your schema
+- **Code execution** - Run Python code in a sandboxed environment
+- **Context caching** - Cache large contexts for efficiency
+- **Embeddings** - Generate text embeddings for semantic search
+
+## Current Gemini Models
+
+- `gemini-3-pro-preview`: 1M tokens, complex reasoning, coding, research
+- `gemini-3-flash-preview`: 1M tokens, fast, balanced performance, multimodal
+- `gemini-3-pro-image-preview`: 65k / 32k tokens, image generation and editing
+
+
+> [!IMPORTANT]
+> Models like `gemini-2.5-*`, `gemini-2.0-*`, `gemini-1.5-*` are legacy and deprecated. Use the new models above. Your knowledge is outdated.
+
+## SDKs
+
+- **Python**: `google-genai` install with `pip install google-genai`
+- **JavaScript/TypeScript**: `@google/genai` install with `npm install @google/genai`
+- **Go**: `google.golang.org/genai` install with `go get google.golang.org/genai`
+
+> [!WARNING]
+> Legacy SDKs `google-generativeai` (Python) and `@google/generative-ai` (JS) are deprecated. Migrate to the new SDKs above urgently by following the Migration Guide.
+
+## Quick Start
+
+### Python
+```python
+from google import genai
+
+client = genai.Client()
+response = client.models.generate_content(
+    model="gemini-3-flash-preview",
+    contents="Explain quantum computing"
+)
+print(response.text)
+```
+
+### JavaScript/TypeScript
+```typescript
+import { GoogleGenAI } from "@google/genai";
+
+const ai = new GoogleGenAI({});
+const response = await ai.models.generateContent({
+  model: "gemini-3-flash-preview",
+  contents: "Explain quantum computing"
+});
+console.log(response.text);
+```
+
+### Go
+```go
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"google.golang.org/genai"
+)
+
+func main() {
+	ctx := context.Background()
+	client, err := genai.NewClient(ctx, nil)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	resp, err := client.Models.GenerateContent(ctx, "gemini-3-flash-preview", genai.Text("Explain quantum computing"), nil)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Println(resp.Text)
+}
+```
+
+## API spec (source of truth)
+
+**Always use the latest REST API discovery spec as the source of truth for API definitions** (request/response schemas, parameters, methods). Fetch the spec when implementing or debugging API integration:
+
+- **v1beta** (default): `https://generativelanguage.googleapis.com/$discovery/rest?version=v1beta`  
+  Use this unless the integration is explicitly pinned to v1. The official SDKs (google-genai, @google/genai, google.golang.org/genai) target v1beta.
+- **v1**: `https://generativelanguage.googleapis.com/$discovery/rest?version=v1`  
+  Use only when the integration is specifically set to v1.
+
+When in doubt, use v1beta. Refer to the spec for exact field names, types, and supported operations.
+
+## How to use the Gemini API
+
+For detailed API documentation, fetch from the official docs index:
+
+**llms.txt URL**: `https://ai.google.dev/gemini-api/docs/llms.txt`
+
+This index contains links to all documentation pages in `.md.txt` format. Use web fetch tools to:
+
+1. Fetch `llms.txt` to discover available documentation pages
+2. Fetch specific pages (e.g., `https://ai.google.dev/gemini-api/docs/function-calling.md.txt`)
+
+### Key Documentation Pages 
+
+> [!IMPORTANT]
+> Those are not all the documentation pages. Use the `llms.txt` index to discover available documentation pages
+
+- [Models](https://ai.google.dev/gemini-api/docs/models.md.txt)
+- [Google AI Studio quickstart](https://ai.google.dev/gemini-api/docs/ai-studio-quickstart.md.txt)
+- [Nano Banana image generation](https://ai.google.dev/gemini-api/docs/image-generation.md.txt)
+- [Function calling with the Gemini API](https://ai.google.dev/gemini-api/docs/function-calling.md.txt)
+- [Structured outputs](https://ai.google.dev/gemini-api/docs/structured-output.md.txt)
+- [Text generation](https://ai.google.dev/gemini-api/docs/text-generation.md.txt)
+- [Image understanding](https://ai.google.dev/gemini-api/docs/image-understanding.md.txt)
+- [Embeddings](https://ai.google.dev/gemini-api/docs/embeddings.md.txt)
+- [Interactions API](https://ai.google.dev/gemini-api/docs/interactions.md.txt)
+- [SDK migration guide](https://ai.google.dev/gemini-api/docs/migrate.md.txt)
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/templates/.agent/skills/gemini-api-integration/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: gemini-api-integration
+description: "Use when integrating Google Gemini API into projects. Covers model selection, multimodal inputs, streaming, function calling, and production best practices."
+risk: safe
+source: community
+date_added: "2026-03-04"
+---
+
+# Gemini API Integration
+
+## Overview
+
+This skill guides AI agents through integrating Google Gemini API into applications — from basic text generation to advanced multimodal, function calling, and streaming use cases. It covers the full Gemini SDK lifecycle with production-grade patterns.
+
+## When to Use This Skill
+
+- Use when setting up Gemini API for the first time in a Node.js, Python, or browser project
+- Use when implementing multimodal inputs (text + image/audio/video)
+- Use when adding streaming responses to improve perceived latency
+- Use when implementing function calling / tool use with Gemini
+- Use when optimizing model selection (Flash vs Pro vs Ultra) for cost and performance
+- Use when debugging Gemini API errors, rate limits, or quota issues
+
+## Step-by-Step Guide
+
+### 1. Installation & Setup
+
+**Node.js / TypeScript:**
+```bash
+npm install @google/generative-ai
+```
+
+**Python:**
+```bash
+pip install google-generativeai
+```
+
+Set your API key securely:
+```bash
+export GEMINI_API_KEY="your-api-key-here"
+```
+
+### 2. Basic Text Generation
+
+**Node.js:**
+```javascript
+import { GoogleGenerativeAI } from "@google/generative-ai";
+
+const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);
+const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });
+
+const result = await model.generateContent("Explain async/await in JavaScript");
+console.log(result.response.text());
+```
+
+**Python:**
+```python
+import google.generativeai as genai
+import os
+
+genai.configure(api_key=os.environ["GEMINI_API_KEY"])
+model = genai.GenerativeModel("gemini-1.5-flash")
+
+response = model.generate_content("Explain async/await in JavaScript")
+print(response.text)
+```
+
+### 3. Streaming Responses
+
+```javascript
+const result = await model.generateContentStream("Write a detailed blog post about AI");
+
+for await (const chunk of result.stream) {
+  process.stdout.write(chunk.text());
+}
+```
+
+### 4. Multimodal Input (Text + Image)
+
+```javascript
+import fs from "fs";
+
+const imageData = fs.readFileSync("screenshot.png");
+const imagePart = {
+  inlineData: {
+    data: imageData.toString("base64"),
+    mimeType: "image/png",
+  },
+};
+
+const result = await model.generateContent(["Describe this image:", imagePart]);
+console.log(result.response.text());
+```
+
+### 5. Function Calling / Tool Use
+
+```javascript
+const tools = [{
+  functionDeclarations: [{
+    name: "get_weather",
+    description: "Get current weather for a city",
+    parameters: {
+      type: "OBJECT",
+      properties: {
+        city: { type: "STRING", description: "City name" },
+      },
+      required: ["city"],
+    },
+  }],
+}];
+
+const model = genAI.getGenerativeModel({ model: "gemini-1.5-pro", tools });
+const result = await model.generateContent("What's the weather in Mumbai?");
+
+const call = result.response.functionCalls()?.[0];
+if (call) {
+  // Execute the actual function
+  const weatherData = await getWeather(call.args.city);
+  // Send result back to model
+}
+```
+
+### 6. Multi-turn Chat
+
+```javascript
+const chat = model.startChat({
+  history: [
+    { role: "user", parts: [{ text: "You are a helpful coding assistant." }] },
+    { role: "model", parts: [{ text: "Sure! I'm ready to help with code." }] },
+  ],
+});
+
+const response = await chat.sendMessage("How do I reverse a string in Python?");
+console.log(response.response.text());
+```
+
+### 7. Model Selection Guide
+
+| Model | Best For | Speed | Cost |
+|-------|----------|-------|------|
+| `gemini-1.5-flash` | High-throughput, cost-sensitive tasks | Fast | Low |
+| `gemini-1.5-pro` | Complex reasoning, long context | Medium | Medium |
+| `gemini-2.0-flash` | Latest fast model, multimodal | Very Fast | Low |
+| `gemini-2.0-pro` | Most capable, advanced tasks | Slow | High |
+
+## Best Practices
+
+- ✅ **Do:** Use `gemini-1.5-flash` for most tasks — it's fast and cost-effective
+- ✅ **Do:** Always stream responses for user-facing chat UIs to reduce perceived latency
+- ✅ **Do:** Store API keys in environment variables, never hard-code them
+- ✅ **Do:** Implement exponential backoff for rate limit (429) errors
+- ✅ **Do:** Use `systemInstruction` to set persistent model behavior
+- ❌ **Don't:** Use `gemini-pro` for simple tasks — Flash is cheaper and faster
+- ❌ **Don't:** Send large base64 images inline for files > 20MB — use File API instead
+- ❌ **Don't:** Ignore safety ratings in responses for production apps
+
+## Error Handling
+
+```javascript
+try {
+  const result = await model.generateContent(prompt);
+  return result.response.text();
+} catch (error) {
+  if (error.status === 429) {
+    // Rate limited — wait and retry with exponential backoff
+    await new Promise(r => setTimeout(r, 2 ** retryCount * 1000));
+  } else if (error.status === 400) {
+    // Invalid request — check prompt or parameters
+    console.error("Invalid request:", error.message);
+  } else {
+    throw error;
+  }
+}
+```
+
+## Troubleshooting
+
+**Problem:** `API_KEY_INVALID` error
+**Solution:** Ensure `GEMINI_API_KEY` environment variable is set and the key is active in Google AI Studio.
+
+**Problem:** Response blocked by safety filters
+**Solution:** Check `result.response.promptFeedback.blockReason` and adjust your prompt or safety settings.
+
+**Problem:** Slow response times
+**Solution:** Switch to `gemini-1.5-flash` and enable streaming. Consider caching repeated prompts.
+
+**Problem:** `RESOURCE_EXHAUSTED` (quota exceeded)
+**Solution:** Check your quota in Google Cloud Console. Implement request queuing and exponential backoff.

package/templates/.agent/skills/gha-security-review/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: gha-security-review
+description: "Find exploitable vulnerabilities in GitHub Actions workflows. Every finding MUST include a concrete exploitation scenario — if you can't build the attack, don't report it."
+risk: safe
+source: community
+date_added: 2026-03-16
+---
+
+<!--
+Attack patterns and real-world examples sourced from the HackerBot Claw campaign analysis
+by StepSecurity (2025): https://www.stepsecurity.io/blog/hackerbot-claw-github-actions-exploitation
+-->
+
+# GitHub Actions Security Review
+
+Find exploitable vulnerabilities in GitHub Actions workflows. Every finding MUST include a concrete exploitation scenario — if you can't build the attack, don't report it.
+
+This skill encodes attack patterns from real GitHub Actions exploits — not generic CI/CD theory.
+
+## Scope
+
+Review the workflows provided (file, diff, or repo). Research the codebase as needed to trace complete attack paths before reporting.
+
+### Files to Review
+
+- `.github/workflows/*.yml` — all workflow definitions
+- `action.yml` / `action.yaml` — composite actions in the repo
+- `.github/actions/*/action.yml` — local reusable actions
+- Config files loaded by workflows: `CLAUDE.md`, `AGENTS.md`, `Makefile`, shell scripts under `.github/`
+
+### Out of Scope
+
+- Workflows in other repositories (only note the dependency)
+- GitHub App installation permissions (note if relevant)
+
+## Threat Model
+
+Only report vulnerabilities exploitable by an **external attacker** — someone **without** write access to the repository. The attacker can open PRs from forks, create issues, and post comments. They cannot push to branches, trigger `workflow_dispatch`, or trigger manual workflows.
+
+**Do not flag** vulnerabilities that require write access to exploit:
+- `workflow_dispatch` input injection — requires write access to trigger
+- Expression injection in `push`-only workflows on protected branches
+- `workflow_call` input injection where all callers are internal
+- Secrets in `workflow_dispatch`/`schedule`-only workflows
+
+## Confidence
+
+Report only **HIGH** and **MEDIUM** confidence findings. Do not report theoretical issues.
+
+| Confidence | Criteria | Action |
+|---|---|---|
+| **HIGH** | Traced the full attack path, confirmed exploitable | Report with exploitation scenario and fix |
+| **MEDIUM** | Attack path partially confirmed, uncertain link | Report as needs verification |
+| **LOW** | Theoretical or mitigated elsewhere | Do not report |
+
+For each HIGH finding, provide all five elements:
+
+1. **Entry point** — How does the attacker get in? (fork PR, issue comment, branch name, etc.)
+2. **Payload** — What does the attacker send? (actual code/YAML/input)
+3. **Execution mechanism** — How does the payload run? (expression expansion, checkout + script, etc.)
+4. **Impact** — What does the attacker gain? (token theft, code execution, repo write access)
+5. **PoC sketch** — Concrete steps an attacker would follow
+
+If you cannot construct all five, report as MEDIUM (needs verification).
+
+---
+
+## Step 1: Classify Triggers and Load References
+
+For each workflow, identify triggers and load the appropriate reference:
+
+| Trigger / Pattern | Load Reference |
+|---|---|
+| `pull_request_target` | `references/pwn-request.md` |
+| `issue_comment` with command parsing | `references/comment-triggered-commands.md` |
+| `${{ }}` in `run:` blocks | `references/expression-injection.md` |
+| PATs / deploy keys / elevated credentials | `references/credential-escalation.md` |
+| Checkout PR code + config file loading | `references/ai-prompt-injection-via-ci.md` |
+| Third-party actions (especially unpinned) | `references/supply-chain.md` |
+| `permissions:` block or secrets usage | `references/permissions-and-secrets.md` |
+| Self-hosted runners, cache/artifact usage | `references/runner-infrastructure.md` |
+| Any confirmed finding | `references/real-world-attacks.md` |
+
+Load references selectively — only what's relevant to the triggers found.
+
+## Step 2: Check for Vulnerability Classes
+
+### Check 1: Pwn Request
+
+Does the workflow use `pull_request_target` AND check out fork code?
+- Look for `actions/checkout` with `ref:` pointing to PR head
+- Look for local actions (`./.github/actions/`) that would come from the fork
+- Check if any `run:` step executes code from the checked-out PR
+
+### Check 2: Expression Injection
+
+Are `${{ }}` expressions used inside `run:` blocks in externally-triggerable workflows?
+- Map every `${{ }}` expression in every `run:` step
+- Confirm the value is attacker-controlled (PR title, branch name, comment body — not numeric IDs, SHAs, or repository names)
+- Confirm the expression is in a `run:` block, not `if:`, `with:`, or job-level `env:`
+
+### Check 3: Unauthorized Command Execution
+
+Does an `issue_comment`-triggered workflow execute commands without authorization?
+- Is there an `author_association` check?
+- Can any GitHub user trigger the command?
+- Does the command handler also use injectable expressions?
+
+### Check 4: Credential Escalation
+
+Are elevated credentials (PATs, deploy keys) accessible to untrusted code?
+- What's the blast radius of each secret?
+- Could a compromised workflow steal long-lived tokens?
+
+### Check 5: Config File Poisoning
+
+Does the workflow load configuration from PR-supplied files?
+- AI agent instructions: `CLAUDE.md`, `AGENTS.md`, `.cursorrules`
+- Build configuration: `Makefile`, shell scripts
+
+### Check 6: Supply Chain
+
+Are third-party actions securely pinned?
+
+### Check 7: Permissions and Secrets
+
+Are workflow permissions minimal? Are secrets properly scoped?
+
+### Check 8: Runner Infrastructure
+
+Are self-hosted runners, caches, or artifacts used securely?
+
+## Safe Patterns (Do Not Flag)
+
+Before reporting, check if the pattern is actually safe:
+
+| Pattern | Why Safe |
+|---|---|
+| `pull_request_target` WITHOUT checkout of fork code | Never executes attacker code |
+| `${{ github.event.pull_request.number }}` in `run:` | Numeric only — not injectable |
+| `${{ github.repository }}` / `github.repository_owner` | Repo owner controls this |
+| `${{ secrets.* }}` | Not an expression injection vector |
+| `${{ }}` in `if:` conditions | Evaluated by Actions runtime, not shell |
+| `${{ }}` in `with:` inputs | Passed as string parameters, not shell-evaluated |
+| Actions pinned to full SHA | Immutable reference |
+| `pull_request` trigger (not `_target`) | Runs in fork context with read-only token |
+| Any expression in `workflow_dispatch`/`schedule`/`push` to protected branches | Requires write access — outside threat model |
+
+**Key distinction:** `${{ }}` is dangerous in `run:` blocks (shell expansion) but safe in `if:`, `with:`, and `env:` at the job/step level (Actions runtime evaluation).
+
+## Step 3: Validate Before Reporting
+
+Before including any finding, read the actual workflow YAML and trace the complete attack path:
+
+1. **Read the full workflow** — don't rely on grep output alone
+2. **Trace the trigger** — confirm the event and check `if:` conditions that gate execution
+3. **Trace the expression/checkout** — confirm it's in a `run:` block or actually references fork code
+4. **Confirm attacker control** — verify the value maps to something an external attacker sets
+5. **Check existing mitigations** — env var wrapping, author_association checks, restricted permissions, SHA pinning
+
+If any link is broken, mark MEDIUM (needs verification) or drop the finding.
+
+**If no checks produced a finding, report zero findings. Do not invent issues.**
+
+## Step 4: Report Findings
+
+````markdown
+## GitHub Actions Security Review
+
+### Findings
+
+#### [GHA-001] [Title] (Severity: Critical/High/Medium)
+- **Workflow**: `.github/workflows/release.yml:15`
+- **Trigger**: `pull_request_target`
+- **Confidence**: HIGH — confirmed through attack path tracing
+- **Exploitation Scenario**:
+  1. [Step-by-step attack]
+- **Impact**: [What attacker gains]
+- **Fix**: [Code that fixes the issue]
+
+### Needs Verification
+[MEDIUM confidence items with explanation of what to verify]
+
+### Reviewed and Cleared
+[Workflows reviewed and confirmed safe]
+````
+
+If no findings: "No exploitable vulnerabilities identified. All workflows reviewed and cleared."