Using Skills

Skills are markdown-based instruction files that teach the Sec-Gemini agent how to approach specific types of work. When loaded into a session, the agent follows the skill's instructions, uses the right tools, and produces structured output.

What is a Skill?

A skill is a markdown file with YAML frontmatter. It tells the agent what to do, which tools to use, and how to format results.

Example: Vulnerability Triage Skill

This example walks through a complete skill. We'll use it to show the format, tool references, and upload flow.

The Skill File

---
name: vuln-triage
description: Triage and prioritize CVEs for a given software stack
---

## Instructions

When given a list of CVEs or a software inventory:

1. For each CVE, use `lookup_vulnerability` to determine:
   - Affected software and versions
   - CVSS score and attack vector
   - Whether it is actively exploited in the wild
   - Whether a patch or workaround exists

2. If the user provides a target system, use `tcp_port_check` to verify
   which services are actually exposed, and `http_headers` to fingerprint
   running software versions.

3. Prioritize findings:
   - **Critical** -- Actively exploited, network-accessible, no auth required
   - **High** -- Network-accessible with known exploit but not yet seen in the wild
   - **Medium** -- Requires local access or user interaction
   - **Low** -- Theoretical or minimal impact

4. For each critical/high finding, recommend a specific action:
   patch version, config change, or compensating control.

## Output Format

Present results as a prioritized markdown table:

| Priority | CVE | Software | CVSS | Exploited? | Action |
|----------|-----|----------|------|------------|--------|

Follow with a summary paragraph noting overall risk posture
and the most urgent items to address.

Upload the Skill

from sec_gemini import SecGemini

async with SecGemini(api_key="YOUR_API_KEY") as client:
    # Upload from a string
    await client.skills.upload(
        name="vuln-triage.md",
        content=open("vuln-triage.md").read()
    )

    # Or inline
    await client.skills.upload(
        name="vuln-triage.md",
        content="""---
name: vuln-triage
description: Triage and prioritize CVEs for a given software stack
---
...skill content here...
"""
    )

Use the Skill

Once uploaded, the agent loads the skill automatically when relevant. Just prompt it:

session = await client.sessions.create()
await session.prompt(
    "Triage these CVEs for our Apache 2.4.51 + OpenSSL 3.0.2 stack: "
    "CVE-2024-3094, CVE-2023-44487, CVE-2022-22720"
)

async for msg in session.messages.stream():
    if msg.get("message_type") == "MESSAGE_TYPE_RESPONSE":
        print(msg["content"])

The agent will use lookup_vulnerability for each CVE, check for active exploitation, and produce the prioritized table defined in the skill.

Managing Skills

# List your uploaded skills
uploaded = await client.skills.list_uploaded()
for name in uploaded:
    print(name)

# Get skill content
content = await client.skills.get("vuln-triage.md")

# Delete a skill
await client.skills.delete("vuln-triage.md")

Skill Format Reference

Skills use YAML frontmatter followed by markdown content:

Field	Required	Description
name	Yes	Unique identifier for the skill
description	Yes	One-line description (shown in skill listings)

The body can contain any markdown. Effective skills include:

• Instructions -- Step-by-step guidance referencing specific tools by name
• Output Format -- How to structure results (tables, sections, severity ratings)
• Constraints -- What the agent should or should not do

Tips for Writing Skills

• Reference tools by their exact name (e.g., lookup_vulnerability, dns_lookup) so the agent knows which tools to reach for.
• Be specific about output format -- the agent follows structure instructions well.
• Keep instructions action-oriented. "Use ssl_check on each domain" is better than "check SSL certificates."
• Test iteratively: upload, prompt, review output, refine the skill.

See the SDK Skills and BYOT Skills pages for ready-to-use skills that teach AI assistants how to use the Sec-Gemini package itself.