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 and Execute a Skill

🐍 Upload and Execute a Skill

import asyncio
from sec_gemini import SecGemini

async def main():
  async with SecGemini(api_key="YOUR_API_KEY") as client:
      # Upload skill inline
      await client.skills.upload(
          name="vuln-triage.md",
          content="""---
name: vuln-triage
description: Triage and prioritize CVEs for a given software stack
---
When given a list of CVEs:
1. Lookup vulnerability CVSS and active exploitation status
2. Recommend specific patch or workaround actions
3. Present findings in a prioritized table
"""
      )
      print("Skill 'vuln-triage.md' uploaded successfully.")

      # Create session and prompt using the skill
      session = await client.sessions.create()
      await session.prompt("Triage these CVEs for our stack: CVE-2024-3094, CVE-2023-44487")

      async for msg in session.messages.stream():
          msg_type = msg.get("message_type", "")
          if msg_type == "MESSAGE_TYPE_RESPONSE":
              print(f"\nAgent Output:\n{msg.get('content')}")
          elif msg_type == "MESSAGE_TYPE_THOUGHT":
              print(f"  (thinking: {msg.get('content')})")

asyncio.run(main())

Terminal Output

Managing Skills

🐍 Managing Skills via Python API

import asyncio
from sec_gemini import SecGemini

async def main():
  async with SecGemini(api_key="YOUR_API_KEY") as client:
      # List uploaded skills
      uploaded = await client.skills.list_uploaded()
      print("Uploaded Skills:")
      for name in uploaded:
          print(f"  - {name}")

      # Get skill content
      content = await client.skills.get("vuln-triage.md")
      print(f"\nSkill Content preview:\n{content[:120]}...")

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

asyncio.run(main())

Terminal Output

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.