Skills Arena SDK

pip install skills-arena

export ANTHROPIC_API_KEY=sk-ant-...

from skills_arena import Arena

arena = Arena()
results = arena.evaluate(
    skill="./my-skill.md",
    task="web search and content extraction"
)

print(f"Score: {results.score}/100 ({results.grade})")
print(f"Selection Rate: {results.selection_rate:.0%}")

results = arena.compare(
    skills=["./my-skill.md", "./competitor.md"],
    task="web search",
)

print(f"Winner: {results.winner}")
for name, rate in results.selection_rates.items():
    print(f"  {name}: {rate:.0%}")

from skills_arena import Arena, Config

arena = Arena(Config(scenarios=30, agents=["claude-code"]))

results = arena.evaluate(
    skill="./my-skill.md",
    task="web search and content extraction",
)

print(f"Score: {results.score}/100")
print(f"Grade: {results.grade}")
print(f"Selection Rate: {results.selection_rate:.0%}")
print(f"False Positive Rate: {results.false_positive_rate:.0%}")

results = arena.compare(
    skills=["./my-skill.md", "./competitor.md"],
    task="web search",
    scenarios=20,
)

print(f"Winner: {results.winner}")
print(f"Selection Rates: {results.selection_rates}")

# See which scenarios you lost
for scenario_id, stealers in results.steals.items():
    print(f"Lost scenario {scenario_id} to: {stealers}")

from skills_arena import CustomScenario, GenerateScenarios

# Fully custom
results = arena.compare(
    skills=["./my-skill.md", "./competitor.md"],
    scenarios=[
        CustomScenario(prompt="Find recent AI news articles"),
        CustomScenario(
            prompt="Scrape pricing from stripe.com",
            expected_skill="My Skill",   # enables steal detection
            tags=["scraping"],
        ),
    ],
)

results = arena.compare(
    skills=["./my-skill.md", "./competitor.md"],
    task="web search",
    scenarios=[
        CustomScenario(prompt="My critical edge case"),
        GenerateScenarios(count=10),   # generate 10 more
    ],
)

from skills_arena import Arena, Config

config = Config(
    scenarios=50,
    agents=["claude-code"],
    temperature=0.7,
    include_adversarial=True,
    scenario_strategy="per_skill",
    timeout_seconds=30,
)

arena = Arena(config)

task: "web search and information retrieval"

skills:
  - path: ./skills/my-search.md
    name: my-search
  - path: ./skills/competitor.md
    name: competitor

evaluation:
  scenarios: 50
  agents: [claude-code]
  include_adversarial: true
  temperature: 0.7

arena = Arena.from_config("./arena.yaml")
results = arena.run()

def on_progress(progress):
    print(f"[{progress.stage}] {progress.percent:.0f}% — {progress.message}")

results = arena.compare(
    skills=["./a.md", "./b.md"],
    task="search",
    on_progress=on_progress,
)

# Stages: parsing → generation → running → complete

insights = arena.insights(
    skill="./my-skill.md",
    results=evaluation_results,
)

for insight in insights:
    print(f"[{insight.severity}] {insight.message}")
    if insight.suggestion:
        print(f"  → {insight.suggestion}")

class Arena:
    def __init__(self, config: Config | None = None)

    @classmethod
    def from_config(cls, path: str | Path) -> Arena

    # Synchronous
    def evaluate(skill, task, *, on_progress=None) -> EvaluationResult
    def compare(skills, task=None, *, scenarios=None, on_progress=None) -> ComparisonResult
    def insights(skill, results=None) -> list[Insight]

    # Async
    async def evaluate_async(skill, task, *, on_progress=None) -> EvaluationResult
    async def compare_async(skills, task=None, *, scenarios=None, on_progress=None) -> ComparisonResult

class Skill(BaseModel):
    name: str                    # Skill identifier
    description: str             # Full description text
    parameters: list[Parameter]  # Function parameters
    when_to_use: list[str]       # Example triggers
    source_format: SkillFormat   # CLAUDE_CODE, OPENAI, MCP, GENERIC
    token_count: int             # Approximate tokens
    raw_content: str             # Original file content
    source_path: str | None      # Source file path

class Parser:
    @classmethod
    def parse(source: str | Path | dict) -> Skill      # Auto-detect format

    @classmethod
    def parse_claude_code(source: str | Path) -> Skill  # .md with YAML frontmatter

    @classmethod
    def parse_openai(source: str | Path | dict) -> Skill  # JSON function schema

    @classmethod
    def parse_mcp(source: str | Path | dict) -> Skill  # MCP tool definition

    @classmethod
    def parse_generic(source: str | Path) -> Skill      # Plain text