SDK Skills

These skills teach AI assistants (Claude Code, Gemini CLI, or any MCP-compatible agent) how to use the Sec-Gemini Python SDK. Copy the skill content into a file and upload it to Sec-Gemini, or save it locally for your AI assistant to reference.

How to Use These Skills

Upload to Sec-Gemini

from sec_gemini import SecGemini

async with SecGemini(api_key="YOUR_KEY") as client:
    with open("sdk-usage-skill.md") as f:
        await client.skills.upload(name="sdk-usage-skill.md", content=f.read())

Save Locally for Your AI Assistant

Save the skill content as a markdown file in your project and reference it in your AI assistant’s configuration (e.g., CLAUDE.md for Claude Code, .gemini/ for Gemini CLI).

---

Skill: Sec-Gemini SDK Usage

This skill teaches an AI assistant how to use the Sec-Gemini Python SDK to create sessions, send prompts, stream responses, and manage resources.

---
name: sec-gemini-sdk-usage
description: How to use the Sec-Gemini Python SDK for programmatic session management
---

## Sec-Gemini Python SDK

The `sec-gemini` package provides an async Python client for the Sec-Gemini security AI agent.

### Installation

```bash
pip install sec-gemini
```

### Quick Reference

```python
from sec_gemini import SecGemini

# Connect (use context manager for automatic cleanup)
async with SecGemini(api_key="YOUR_KEY") as client:

    # Sessions
    session = await client.sessions.create()
    sessions = await client.sessions.list()
    session = await client.sessions.get("session-id")
    await session.delete()

    # Prompt and stream
    await session.prompt("Analyze example.com DNS security")
    async for msg in session.messages.stream():
        # msg is a dict with keys: message_type, content, title, source_type, id
        if msg.get("message_type") == "MESSAGE_TYPE_RESPONSE":
            print(msg["content"])

    # Session control
    await session.pause()
    await session.resume()
    await session.cancel()

    # Files
    await session.files.upload("/path/to/file.txt")
    files = await session.files.list()  # returns FileInfo with .filename, .url
    await session.files.delete("file.txt")

    # Skills
    await client.skills.upload(name="my-skill.md", content="...")
    uploaded = await client.skills.list_uploaded()  # returns list[str]
    content = await client.skills.get("my-skill.md")
    await client.skills.delete("my-skill.md")

    # MCPs (account level)
    mcps = await client.mcps.list()
    new = await client.mcps.add(name="my-mcp", uri="https://...")
    await client.mcps.remove(id=new.id)

    # MCPs (session level)
    session_mcps = await session.mcps.list()
    await session.mcps.set(["https://mcp-url/sse"])

    # Tool confirmations
    info = await session.confirmations.get_info()
    await session.confirmations.send_tool_confirmation(action_id, True)
    await session.confirmations.set_config(always_ask=True)
```

### Key Message Types

- `MESSAGE_TYPE_RESPONSE` -- Agent's final answer
- `MESSAGE_TYPE_THOUGHT` -- Agent's reasoning
- `MESSAGE_TYPE_TOOL_CALL` -- Agent calling a tool
- `MESSAGE_TYPE_TOOL_RESULT` -- Tool output
- `MESSAGE_TYPE_AGENT_IS_DONE` -- Session completed
- `MESSAGE_TYPE_TOOL_CONFIRMATION_REQUEST` -- Needs user approval

### Important Notes

- All SDK methods are async. Use `await` for every call.
- `session.messages.stream()` yields `dict` objects, not Pydantic models.
- `session.prompt()` is fire-and-forget; it does not return the response. Use `stream()` to get messages.
- The agent runs server-side. If the client disconnects, reconnect and call `stream()` again to resume.
- Files uploaded to sessions expire after 7 days.

---

Skill: Security Analysis Workflow

This skill teaches an AI assistant a structured approach to security analysis using the SDK.

---
name: security-analysis-workflow
description: Structured security analysis workflow using the Sec-Gemini SDK
---

## Security Analysis Workflow

When asked to perform a security analysis using Sec-Gemini:

### Step 1: Initialize
```python
from sec_gemini import SecGemini

client = SecGemini(api_key=API_KEY)
await client.start()
session = await client.sessions.create()
```

### Step 2: Upload Context (if provided)
If the user provides files (configs, logs, headers), upload them first:
```python
await session.files.upload("/path/to/file")
```

### Step 3: Send Analysis Prompt
Frame the prompt with specific scope and objectives:
```python
await session.prompt("Analyze the email security posture of example.com. Check SPF, DKIM, DMARC, and MX configuration.")
```

### Step 4: Stream and Collect Results
```python
results = []
async for msg in session.messages.stream():
    if msg.get("message_type") == "MESSAGE_TYPE_RESPONSE":
        results.append(msg["content"])
    elif msg.get("message_type") == "MESSAGE_TYPE_TOOL_CONFIRMATION_REQUEST":
        # Auto-approve or ask the user
        info = await session.confirmations.get_info()
        await session.confirmations.send_tool_confirmation(info.confirmation_info.id, True)
```

### Step 5: Present Findings
Summarize the agent's findings in a structured format with severity ratings.

### Step 6: Cleanup
```python
await session.delete()
await client.close()
```