Skills Service

TL;DR

The Skills service lets you list installed skills, inspect their system prompts, and run them with client.skills.run(). Skills are AI-powered tools (like ssl-cert-checker) that the agent executes using its full toolset — terminal commands, file access, HTTP requests. Supports structured output via Pydantic models, custom options (model, timeout), and tool result tracking.

Run AI skills installed on your machines.

How do I list available skills?


from cmdop import AsyncCMDOPClient
 
# Connect to the local agent via Unix socket
async with AsyncCMDOPClient.local() as client:
    # List all skills installed on the machine
    skills = await client.skills.list()
 
    for skill in skills:
        print(f"{skill.name}: {skill.description}")

For remote machines, set the target first:


# Connect through cloud relay
async with AsyncCMDOPClient.remote(api_key="cmdop_xxx") as client:
    # Target a specific machine by hostname
    await client.skills.set_machine("my-server")
 
    skills = await client.skills.list()

What information does a skill have?


from cmdop import SkillInfo
 
# SkillInfo fields returned by list()
skill: SkillInfo
print(f"Name: {skill.name}")               # Skill identifier (e.g. "ssl-cert-checker")
print(f"Description: {skill.description}")  # What the skill does
print(f"Author: {skill.author}")            # Skill author (optional)
print(f"Version: {skill.version}")          # Skill version (optional)
print(f"Model: {skill.model}")              # Preferred LLM model (optional)
print(f"Origin: {skill.origin}")            # Where loaded from: builtin, global, workspace
print(f"Requires: {skill.required_bins}")   # External binaries needed (e.g. ["openssl"])

How do I inspect a skill?

Get the full details including system prompt:


# Show detailed information about a specific skill
detail = await client.skills.show("ssl-cert-checker")
 
if detail.found:
    info = detail.info
    print(f"Name: {info.name}")
    print(f"Description: {info.description}")
    print(f"Origin: {info.origin}")
    print(f"Source: {detail.source}")            # File path on the machine
 
    # The system prompt (markdown) that drives the skill
    print(f"System prompt ({len(detail.content)} chars):")
    print(detail.content[:500])
else:
    print(f"Not found: {detail.error}")

How do I run a skill?


# Run a skill with a natural-language prompt
result = await client.skills.run(
    "ssl-cert-checker",
    "Check SSL certificates for github.com and google.com",
)
 
if result.success:
    print(result.text)        # AI-generated text response
else:
    print(f"Error: {result.error}")
 
# Execution metadata
print(f"Duration: {result.duration_seconds:.1f}s")
print(f"Tokens: {result.usage.total_tokens}")

How does structured output work?

Define a Pydantic model to get typed data back:


from pydantic import BaseModel, Field
 
# Define the expected output structure
class CertInfo(BaseModel):
    domain: str = Field(description="Domain name")
    valid: bool = Field(description="Whether the certificate is valid")
    issuer: str = Field(default="", description="Certificate issuer")
    expires_in_days: int = Field(default=0, description="Days until expiration")
    error: str = Field(default="", description="Error if check failed")
 
class SSLReport(BaseModel):
    certificates: list[CertInfo] = Field(description="Certificate info per domain")
    all_valid: bool = Field(description="True if all certificates are valid")
    summary: str = Field(description="Brief summary of the check")
 
# Pass output_model to get structured data
result = await client.skills.run(
    "ssl-cert-checker",
    "Check SSL for github.com, google.com, expired.badssl.com",
    output_model=SSLReport,
)
 
if result.success and result.data:
    report: SSLReport = result.data
 
    print(f"All valid: {report.all_valid}")
    print(f"Summary: {report.summary}")
 
    for cert in report.certificates:
        status = "OK" if cert.valid else "FAIL"
        print(f"  {cert.domain}: {status} ({cert.expires_in_days}d)")

What run options are available?


from cmdop import SkillRunOptions
 
# Override model and timeout for a skill run
result = await client.skills.run(
    "code-review",
    "Review this PR for security issues",
    options=SkillRunOptions(
        model="openai/gpt-4o",      # Override the skill's default model
        timeout_seconds=600,          # Max execution time (10-600s, default 300)
    ),
)

How do I track tool usage?

Skills execute tools (shell commands, file reads, etc.) during their run:


result = await client.skills.run(
    "ssl-cert-checker",
    "Check SSL for cmdop.com",
)
 
# Inspect which tools the AI used
if result.tool_results:
    print(f"Tools used: {len(result.tool_results)}")
    for tr in result.tool_results:
        status = "ok" if tr.success else "FAIL"
        print(f"  [{status}] {tr.tool_name} ({tr.duration_ms}ms)")

What does the SkillRunResult contain?


from cmdop import SkillRunResult
 
result: SkillRunResult
print(f"Success: {result.success}")              # Whether the skill completed
print(f"Text: {result.text}")                    # Text response from the AI
print(f"Error: {result.error}")                  # Error message if failed
print(f"Duration: {result.duration_seconds}s")   # Execution time in seconds
print(f"Request ID: {result.request_id}")        # For correlation/debugging
 
# Token usage
print(f"Input tokens: {result.usage.input_tokens}")
print(f"Output tokens: {result.usage.output_tokens}")
print(f"Total tokens: {result.usage.total_tokens}")
 
# Structured data (when output_model is provided)
print(f"Data: {result.data}")                    # Parsed Pydantic model instance
print(f"Raw JSON: {result.output_json}")         # Raw JSON string

How do I use skills with different connection modes?

Skills work with both local and remote connections:


# Local agent — direct Unix socket, no API key needed
async with AsyncCMDOPClient.local() as client:
    skills = await client.skills.list()
 
# Remote — through cloud relay, requires API key
async with AsyncCMDOPClient.remote(
    api_key="cmdop_xxx",
    server="grpc.cmdop.com:443",
) as client:
    await client.skills.set_machine("my-server")
    skills = await client.skills.list()

How do I use the sync client?


from cmdop import CMDOPClient
 
# Synchronous client usage (same API, without await)
with CMDOPClient.local() as client:
    skills = client.skills.list()
 
    result = client.skills.run(
        "ssl-cert-checker",
        "Check SSL for github.com",
    )
    print(result.text)

Error Handling


from cmdop.exceptions import (
    CMDOPError,
    MethodNotFoundError,
    ConnectionTimeoutError,
    AgentNotRunningError,
)
 
try:
    result = await client.skills.run(
        "ssl-cert-checker",
        "Check SSL for example.com",
    )
except MethodNotFoundError:
    # Server doesn't support skills — restart it or update proto
    print("Skills not available. Restart the gRPC server.")
except ConnectionTimeoutError:
    # Skill took too long to execute
    print("Skill execution timed out")
except AgentNotRunningError:
    # Local agent is not running
    print("Start the agent: cmdop serve")
except CMDOPError as e:
    # Catch-all for other SDK errors
    print(f"Error: {e}")

What skills are available?

Skills are installed on the agent machine. Common types:

Origin	Description	Example
`builtin`	Bundled with the agent	code-review, docker, git, shell
`global`	Installed system-wide	ssl-cert-checker
`workspace`	Project-specific	Custom skills in `.cmdop/skills/`

Browse available skills: cmdop.com/skills

AI Agent Service — Run AI tasks with structured output
Terminal Service — Execute commands directly
Error Handling — Handle SDK errors