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.

Available Tools

Skills can reference any tool the agent has access to. Here are the key ones:

Tool	What it does
lookup_vulnerability	Look up CVE details, CVSS scores, affected software
dns_lookup	Query DNS records (A, MX, TXT, CNAME, etc.)
whois_lookup	WHOIS query for a domain or IP
check_email_security	Check SPF, DKIM, DMARC records
ssl_check	Inspect SSL/TLS certificate
fetch_http	Fetch content from a URL
http_headers	Get HTTP response headers
grep_http	Search HTTP response body with regex
tcp_port_check	Check if a TCP port is open
bash	Execute a shell command (via BYOT)
python_exec	Execute Python code (via BYOT)
javascript_exec	Execute JavaScript code (via BYOT)
read_file / write_file	Read and write local files (via BYOT)
grep / find_files	Search file contents and find files (via BYOT)

Tools marked “via BYOT” require a BYOT client running locally.

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.