{
  "schemaVersion": "1.0",
  "item": {
    "slug": "football-data",
    "name": "Football Data",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/antonelli182/football-data",
    "canonicalUrl": "https://clawhub.ai/antonelli182/football-data",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/football-data",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=football-data",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "SKILL.md",
      "references/commands.md",
      "references/data-coverage.md",
      "references/schemas.md",
      "scripts/validate_params.sh"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/football-data"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/football-data",
    "agentPageUrl": "https://openagent3.xyz/skills/football-data/agent",
    "manifestUrl": "https://openagent3.xyz/skills/football-data/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/football-data/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Setup",
        "body": "Before first use, check if the CLI is available:\n\nwhich sports-skills || pip install sports-skills\n\nIf pip install fails (package not found or Python version error), install from GitHub:\n\npip install git+https://github.com/machina-sports/sports-skills.git\n\nThe package requires Python 3.10+. If your default Python is older, use a specific version:\n\npython3 --version  # check version\n# If < 3.10, try: python3.12 -m pip install sports-skills\n# On macOS with Homebrew: /opt/homebrew/bin/python3.12 -m pip install sports-skills\n\nNo API keys required."
      },
      {
        "title": "Quick Start",
        "body": "Prefer the CLI — it avoids Python import path issues:\n\nsports-skills football get_daily_schedule\nsports-skills football get_season_standings --season_id=premier-league-2025\n\nPython SDK (alternative):\n\nfrom sports_skills import football\n\nstandings = football.get_season_standings(season_id=\"premier-league-2025\")\nschedule = football.get_daily_schedule()"
      },
      {
        "title": "Choosing the Season",
        "body": "Derive the current year from the system prompt's date (e.g., currentDate: 2026-02-16 → current year is 2026).\n\nIf the user specifies a season, use it as-is.\nIf the user says \"current\", \"latest\", or doesn't specify: Call get_current_season(competition_id=\"...\") to get the active season_id. Do NOT guess or hardcode the year.\nSeason format: Always {league-slug}-{year} (e.g., \"premier-league-2025\" for the 2025-26 season). The year is the start year of the season, not the end year.\nMLS exception: MLS runs spring-fall within a single calendar year. Use get_current_season(competition_id=\"mls\") — don't assume MLS follows European calendar.\nNever hardcode a season_id. Always derive it via get_current_season() or from the system date."
      },
      {
        "title": "Data Coverage by League",
        "body": "Not all data is available for every league. Use the right command for the right league.\n\nCommandAll 13 leaguesTop 5 onlyPL onlyget_season_standingsxget_daily_schedulexget_season_schedulexget_season_teamsxsearch_teamxget_team_schedulexget_team_profilexget_event_summaryxget_event_lineupsxget_event_statisticsxget_event_timelinexget_current_seasonxget_competitionsxget_event_xgxget_event_players_statistics (with xG)xget_season_leadersxget_missing_playersx\n\nTop 5 leagues (Understat): EPL, La Liga, Bundesliga, Serie A, Ligue 1.\nPL only (FPL): Premier League — injury news, player stats, ownership, ICT index.\nAll leagues: via ESPN — scores, standings, schedules, match summaries, lineups, team stats.\nTransfermarkt: Works for any player with a tm_player_id — market values and transfer history.\n\nNote: MLS uses a different season structure (spring-fall calendar). Use get_current_season(competition_id=\"mls\") to detect the right season_id."
      },
      {
        "title": "ID Conventions",
        "body": "season_id: {league-slug}-{year} e.g. \"premier-league-2025\", \"la-liga-2025\"\ncompetition_id: league slug e.g. \"premier-league\", \"serie-a\", \"champions-league\"\nteam_id: ESPN team ID (numeric string) e.g. \"359\" (Arsenal), \"86\" (Real Madrid)\nevent_id: ESPN event ID (numeric string) e.g. \"740847\"\nfpl_id: FPL element ID or code (PL players only)\ntm_player_id: Transfermarkt player ID e.g. \"433177\" (Saka), \"342229\" (Mbappe)"
      },
      {
        "title": "get_current_season",
        "body": "Detect current season for a competition. Works for all leagues.\n\ncompetition_id (str, required): Competition slug\n\nReturns data.competition and data.season:\n\n{\"competition\": {\"id\": \"premier-league\", \"name\": \"Premier League\"}, \"season\": {\"id\": \"premier-league-2025\", \"name\": \"2025-26 English Premier League\", \"year\": \"2025\"}}"
      },
      {
        "title": "get_competitions",
        "body": "List available competitions with current season info. No params. Works for all leagues.\n\nReturns data.competitions[] with id, name, code, current_season."
      },
      {
        "title": "get_competition_seasons",
        "body": "Get available seasons for a competition. Works for all leagues.\n\ncompetition_id (str, required): Competition slug"
      },
      {
        "title": "get_season_schedule",
        "body": "Get full season match schedule. Works for all leagues.\n\nseason_id (str, required): Season slug (e.g., \"premier-league-2025\")\n\nReturns data.schedules[] — same shape as events below."
      },
      {
        "title": "get_season_standings",
        "body": "Get league table for a season. Works for all leagues.\n\nseason_id (str, required): Season slug\n\nReturns data.standings[].entries[]:\n\n{\n  \"position\": 1,\n  \"team\": {\"id\": \"359\", \"name\": \"Arsenal\", \"short_name\": \"Arsenal\", \"abbreviation\": \"ARS\", \"crest\": \"https://...\"},\n  \"played\": 26, \"won\": 17, \"drawn\": 6, \"lost\": 3,\n  \"goals_for\": 50, \"goals_against\": 18, \"goal_difference\": 32, \"points\": 57\n}"
      },
      {
        "title": "get_season_leaders",
        "body": "Get top scorers/leaders for a season. Premier League only (via FPL).\n\nseason_id (str, required): Season slug (must be premier-league-*)\n\nReturns data.leaders[] — note: player name is nested under .player.name:\n\n{\n  \"player\": {\"id\": \"223094\", \"name\": \"Erling Haaland\", \"first_name\": \"Erling\", \"last_name\": \"Haaland\", \"position\": \"Forward\"},\n  \"team\": {\"id\": \"43\", \"name\": \"Man City\"},\n  \"goals\": 22, \"assists\": 6, \"penalties\": 0, \"played_matches\": 25\n}\n\nReturns empty for non-PL leagues."
      },
      {
        "title": "get_season_teams",
        "body": "Get teams in a season. Works for all leagues.\n\nseason_id (str, required): Season slug"
      },
      {
        "title": "search_team",
        "body": "Search for a team by name across all leagues (or a specific one). Uses fuzzy matching.\n\nquery (str, required): Team name to search (e.g., \"Corinthians\", \"Barcelona\", \"Man Utd\")\ncompetition_id (str, optional): Limit search to one league (e.g., \"serie-a-brazil\", \"premier-league\")\n\nReturns data.results[] with team, competition, and season for each match:\n\n{\"team\": {\"id\": \"874\", \"name\": \"Corinthians\"}, \"competition\": {\"id\": \"serie-a-brazil\", \"name\": \"Serie A Brazil\"}, \"season\": {\"id\": \"serie-a-brazil-2025\", \"year\": \"2025\"}}"
      },
      {
        "title": "get_team_profile",
        "body": "Get basic team info (name, crest, venue). Does not return squad/roster — use get_season_leaders to find PL player IDs, then get_player_profile for individual player data.\n\nteam_id (str, required): ESPN team ID\nleague_slug (str, optional): League hint (faster resolution)\n\nReturns data.team and data.venue. data.players[] is empty — see \"Deep dive on a PL team\" example below for the recommended workflow."
      },
      {
        "title": "get_daily_schedule",
        "body": "Get all matches for a specific date across all leagues.\n\ndate (str, optional): Date in YYYY-MM-DD format. Defaults to today.\n\nReturns data.date and data.events[]:\n\n{\n  \"id\": \"748381\", \"status\": \"not_started\", \"start_time\": \"2026-02-16T20:00Z\",\n  \"competition\": {\"id\": \"la-liga\", \"name\": \"La Liga\"},\n  \"season\": {\"id\": \"la-liga-2025\", \"year\": \"2025\"},\n  \"venue\": {\"name\": \"Estadi Montilivi\", \"city\": \"Girona\"},\n  \"competitors\": [\n    {\"team\": {\"id\": \"9812\", \"name\": \"Girona\", \"abbreviation\": \"GIR\"}, \"qualifier\": \"home\", \"score\": 0},\n    {\"team\": {\"id\": \"83\", \"name\": \"Barcelona\", \"abbreviation\": \"BAR\"}, \"qualifier\": \"away\", \"score\": 0}\n  ],\n  \"scores\": {\"home\": 0, \"away\": 0}\n}\n\nStatus values: \"not_started\", \"live\", \"halftime\", \"closed\", \"postponed\"."
      },
      {
        "title": "get_event_summary",
        "body": "Get match summary with scores. Works for all leagues.\n\nevent_id (str, required): Match/event ID\n\nReturns data.event (same shape as daily schedule events)."
      },
      {
        "title": "get_event_lineups",
        "body": "Get match lineups. Works for all leagues (when available from ESPN).\n\nevent_id (str, required): Match/event ID\n\nReturns data.lineups[]:\n\n{\n  \"team\": {\"id\": \"364\", \"name\": \"Liverpool\", \"abbreviation\": \"LIV\"},\n  \"qualifier\": \"home\",\n  \"formation\": \"4-3-3\",\n  \"starting\": [{\"id\": \"275599\", \"name\": \"Caoimhín Kelleher\", \"position\": \"Goalkeeper\", \"shirt_number\": 1}],\n  \"bench\": [{\"id\": \"...\", \"name\": \"...\", \"position\": \"...\", \"shirt_number\": 62}]\n}"
      },
      {
        "title": "get_event_statistics",
        "body": "Get match team statistics. Works for all leagues.\n\nevent_id (str, required): Match/event ID\n\nReturns data.teams[]:\n\n{\n  \"team\": {\"id\": \"244\", \"name\": \"Brentford\"},\n  \"qualifier\": \"home\",\n  \"statistics\": {\"ball_possession\": \"40.8\", \"shots_total\": \"10\", \"shots_on_target\": \"3\", \"fouls\": \"12\", \"corners\": \"4\"}\n}"
      },
      {
        "title": "get_event_timeline",
        "body": "Get match timeline/key events (goals, cards, substitutions). Works for all leagues.\n\nevent_id (str, required): Match/event ID\n\nReturns data.timeline[] with goal, card, and substitution events."
      },
      {
        "title": "get_team_schedule",
        "body": "Get schedule for a specific team — includes both past results and upcoming fixtures. Works for all leagues.\n\nteam_id (str, required): ESPN team ID\nleague_slug (str, optional): League hint (faster resolution)\nseason_year (str, optional): Season year filter\ncompetition_id (str, optional): Filter results to a single competition (e.g., \"serie-a-brazil\", \"premier-league\")"
      },
      {
        "title": "get_head_to_head",
        "body": "UNAVAILABLE — requires licensed data. Do not call this command; it will return empty results. Instead, use get_team_schedule for both teams and filter overlapping matches manually.\n\nteam_id (str, required): First team ID\nteam_id_2 (str, required): Second team ID"
      },
      {
        "title": "get_event_xg",
        "body": "Get expected goals (xG) data from Understat. Top 5 leagues only: EPL, La Liga, Bundesliga, Serie A, Ligue 1. Returns empty for other leagues.\n\nevent_id (str, required): Match/event ID\n\nReturns data.teams[] and data.shots[]:\n\n{\"team\": {\"id\": \"244\", \"name\": \"Brentford\"}, \"qualifier\": \"home\", \"xg\": 1.812}\n\ndata.shots[] contains individual shot data with xG per shot. Note: very recent matches (last 24-48h) may not be indexed on Understat yet."
      },
      {
        "title": "get_event_players_statistics",
        "body": "Get player-level match statistics with xG enrichment. Works for all leagues (basic stats from ESPN). xG/xA enrichment only for top 5 leagues (Understat).\n\nevent_id (str, required): Match/event ID\n\nReturns data.teams[].players[]:\n\n{\n  \"id\": \"...\", \"name\": \"Bukayo Saka\", \"position\": \"Midfielder\", \"shirt_number\": 7, \"starter\": true,\n  \"statistics\": {\"appearances\": \"1\", \"shotsTotal\": \"3\", \"shotsOnTarget\": \"1\", \"foulsCommitted\": \"1\", \"xg\": \"0.45\", \"xa\": \"0.12\"}\n}\n\nxg and xa fields only present for top 5 leagues."
      },
      {
        "title": "get_missing_players",
        "body": "Get injured/missing/doubtful players. Premier League only (via FPL). Returns empty for other leagues.\n\nseason_id (str, required): Season slug (must be premier-league-*)\n\nReturns data.teams[].players[]:\n\n{\n  \"id\": \"463748\", \"name\": \"Mikel Merino Zazón\", \"web_name\": \"Merino\",\n  \"position\": \"Midfielder\", \"status\": \"injured\",\n  \"news\": \"Foot injury - Unknown return date\",\n  \"chance_of_playing_this_round\": 0, \"chance_of_playing_next_round\": 0\n}\n\nStatus values: \"injured\", \"unavailable\", \"doubtful\", \"suspended\"."
      },
      {
        "title": "get_season_transfers",
        "body": "Get transfer history for specific players via Transfermarkt. Works for any league.\n\nseason_id (str, required): Season slug (used to filter transfers by year)\ntm_player_ids (list, required): Transfermarkt player IDs\n\nReturns data.transfers[]:\n\n{\n  \"player_tm_id\": \"433177\", \"date\": \"2019-07-01\", \"season\": \"19/20\",\n  \"from_team\": {\"name\": \"Arsenal U23\", \"image\": \"https://...\"},\n  \"to_team\": {\"name\": \"Arsenal\", \"image\": \"https://...\"},\n  \"fee\": \"-\", \"market_value\": \"-\"\n}"
      },
      {
        "title": "get_player_season_stats",
        "body": "Get player season stats via ESPN overview endpoint. Works for any league with ESPN athlete IDs.\n\nplayer_id (str, required): ESPN athlete ID\nleague_slug (str, optional): League slug hint (e.g., \"eng.1\", \"esp.1\"). Defaults to auto-detect.\n\nReturns season stats (goals, assists, appearances, etc.) and game log when available."
      },
      {
        "title": "get_player_profile",
        "body": "Get player profile. Works for any player if you have their Transfermarkt or FPL ID. At least one ID required.\n\nfpl_id (str, optional): FPL player ID (PL players only)\ntm_player_id (str, optional): Transfermarkt player ID (any league)\n\nWith tm_player_id, returns data.player with:\n\n{\n  \"market_value\": {\"value\": 130000000, \"currency\": \"EUR\", \"formatted\": \"€130.00m\", \"date\": \"09/12/2025\", \"age\": \"24\", \"club\": \"Arsenal FC\"},\n  \"market_value_history\": [{\"value\": 7000000, \"formatted\": \"€7.00m\", \"date\": \"23/09/2019\", \"club\": \"Arsenal FC\"}],\n  \"transfer_history\": [\n    {\"player_tm_id\": \"433177\", \"date\": \"2019-07-01\", \"season\": \"19/20\", \"from_team\": {\"name\": \"Arsenal U23\"}, \"to_team\": {\"name\": \"Arsenal\"}, \"fee\": \"-\"}\n  ]\n}\n\nWith fpl_id, also includes data.player.fpl_data with FPL stats (points, form, ICT index, ownership, etc.)."
      },
      {
        "title": "Supported Leagues",
        "body": "Premier League, La Liga, Bundesliga, Serie A, Ligue 1, MLS, Championship, Eredivisie, Primeira Liga, Serie A Brazil, Champions League, European Championship, World Cup."
      },
      {
        "title": "Data Sources",
        "body": "SourceWhat it providesLeague coverageESPNScores, standings, schedules, lineups, match stats, timelinesAll 13 leaguesopenfootballSchedules, standings, team lists (fallback when ESPN is down)10 leagues (all except CL, Euros, World Cup)UnderstatxG per match, xG per shot, player xG/xATop 5 (EPL, La Liga, Bundesliga, Serie A, Ligue 1)FPLTop scorers, injuries, player stats, ownershipPremier League onlyTransfermarktMarket values, transfer historyAny player (requires tm_player_id)\n\nFor licensed data with full coverage across all sports (Sportradar, Opta, Genius Sports), see Machina Sports."
      },
      {
        "title": "Examples",
        "body": "User: \"Show me the Premier League table\"\n\nCall get_current_season(competition_id=\"premier-league\") to get the current season_id\nCall get_season_standings(season_id=<season_id from step 1>)\nPresent standings table with position, team, played, won, drawn, lost, GD, points\n\nUser: \"How did Arsenal vs Liverpool go?\"\n\nCall get_daily_schedule() or get_team_schedule(team_id=\"359\") to find the event_id\nCall get_event_summary(event_id=\"...\") for the score\nCall get_event_statistics(event_id=\"...\") for possession, shots, etc.\nCall get_event_xg(event_id=\"...\") for xG comparison (EPL — top 5 only)\nPresent match report with scores, key stats, and xG\n\nUser: \"Deep dive on Chelsea's recent form\"\n\nCall search_team(query=\"Chelsea\") → team_id=363, competition=premier-league\nCall get_team_schedule(team_id=\"363\", competition_id=\"premier-league\") → find recent closed events\nFor each recent match, call in parallel:\n\nget_event_xg(event_id=\"...\") for xG comparison and shot map\nget_event_statistics(event_id=\"...\") for possession, shots, passes\nget_event_players_statistics(event_id=\"...\") for individual player xG/xA\n\n\nCall get_missing_players(season_id=<season_id>) → filter Chelsea's injured/doubtful players\nCall get_season_leaders(season_id=<season_id>) → filter Chelsea players, get their FPL IDs\nCall get_player_profile(fpl_id=\"...\", tm_player_id=\"...\") for key players — combine FPL stats (form, ownership, ICT) with Transfermarkt data (market value, transfer history)\nPresent: xG trend across matches, key player stats, injury report, market values\n\nUser: \"What's Saka's market value?\"\n\nCall get_player_profile(tm_player_id=\"433177\") for Transfermarkt data\nOptionally add fpl_id for FPL stats if Premier League player\nPresent market value, value history, and transfer history\n\nUser: \"Tell me about Corinthians\"\n\nCall search_team(query=\"Corinthians\") → team_id=874, competition=serie-a-brazil\nCall get_team_schedule(team_id=\"874\", competition_id=\"serie-a-brazil\") for fixtures\nPick a recent match and call get_event_timeline(event_id=\"...\") for goals, cards, subs\nNote: xG, FPL stats, and season leaders are NOT available for Brazilian Serie A"
      },
      {
        "title": "Error Handling",
        "body": "When a command fails (wrong event_id, missing data, network error, etc.), do not surface the raw error to the user. Instead:\n\nCatch it silently — treat the failure as an exploratory miss, not a fatal error.\nTry alternatives — e.g., if an event_id returns no data, call get_daily_schedule() or get_team_schedule() to discover the correct ID. If ESPN is down, openfootball data may still be available via get_season_standings or get_season_schedule.\nOnly report failure after exhausting alternatives — and when you do, give a clean human-readable message (e.g., \"I couldn't find that match — can you confirm the teams or date?\"), not a traceback or raw CLI output.\n\nThis is especially important when the agent is responding through messaging platforms (Telegram, Slack, etc.) where raw exec failures look broken."
      },
      {
        "title": "Common Mistakes",
        "body": "These are the ONLY valid commands. Do not invent or guess command names:\n\nget_current_season\nget_competitions\nget_competition_seasons\nget_season_schedule\nget_season_standings\nget_season_leaders\nget_season_teams\nsearch_team\nget_team_profile\nget_daily_schedule\nget_event_summary\nget_event_lineups\nget_event_statistics\nget_event_timeline\nget_team_schedule\nget_head_to_head\nget_event_xg\nget_event_players_statistics\nget_missing_players\nget_season_transfers\nget_player_profile\nget_player_season_stats\n\nCommands that DO NOT exist (commonly hallucinated):\n\nget_standings — the correct command is get_season_standings (requires season_id).\nget_live_scores — not available. Use get_daily_schedule() for today's matches; status field shows \"live\" for in-progress games.\nget_team_squad / get_team_roster — get_team_profile does NOT return players. Use get_season_leaders for PL player IDs, then get_player_profile for individual data.\nget_transfers — the correct command is get_season_transfers (requires season_id + tm_player_ids).\nget_match_results / get_match — use get_event_summary with an event_id.\nget_player_stats — use get_event_players_statistics for match-level stats, or get_player_profile for career data.\n\nOther common mistakes:\n\nUsing get_season_leaders or get_missing_players on non-PL leagues — they return empty. Check the Data Coverage table.\nUsing get_event_xg on leagues outside the top 5 — returns empty. Only works for EPL, La Liga, Bundesliga, Serie A, Ligue 1.\nGuessing team_id or event_id instead of discovering them via search_team, get_daily_schedule, or get_season_schedule.\n\nIf you're unsure whether a command exists, check this list. Do not try commands that aren't listed above."
      },
      {
        "title": "Troubleshooting",
        "body": "sports-skills command not found: Package not installed. Run pip install sports-skills. If the package is not found on PyPI, install from GitHub: pip install git+https://github.com/machina-sports/sports-skills.git. Requires Python 3.10+ — see Setup section.\nModuleNotFoundError: No module named 'sports_skills': Same as above — install the package. Prefer the CLI over Python imports to avoid path issues.\nEmpty results for PL-only commands on other leagues: get_season_leaders and get_missing_players only return data for Premier League. They silently return empty for other leagues — check the Data Coverage table.\nget_team_profile returns empty players: This is expected — squad rosters are not available. To get player data for a PL team, use get_season_leaders to find players and their FPL IDs, then get_player_profile(fpl_id=\"...\") for detailed stats. For Transfermarkt data, you need the player's tm_player_id.\nFinding FPL IDs and Transfermarkt IDs: Use get_season_leaders(season_id=\"premier-league-2025\") to discover FPL IDs for PL players. Transfermarkt IDs must be looked up on transfermarkt.com — the ID is the number at the end of the player's URL. Well-known examples: Cole Palmer = 568177, Bukayo Saka = 433177, Mbappe = 342229.\nNo xG for recent matches: Understat data may lag 24-48 hours after a match ends. If get_event_xg returns empty for a recent top-5 match, try again later.\nWrong season_id format: Must be {league-slug}-{year} e.g. \"premier-league-2025\". Not \"2025-2026\", not \"EPL-2025\". Use get_current_season() to discover the correct format.\nTeam/event IDs unknown: Use search_team(query=\"team name\") to find team IDs by name, or get_season_teams to list all teams in a season. Use get_daily_schedule or get_season_schedule to find event IDs. IDs are ESPN numeric strings."
      }
    ],
    "body": "Football Data\nSetup\n\nBefore first use, check if the CLI is available:\n\nwhich sports-skills || pip install sports-skills\n\n\nIf pip install fails (package not found or Python version error), install from GitHub:\n\npip install git+https://github.com/machina-sports/sports-skills.git\n\n\nThe package requires Python 3.10+. If your default Python is older, use a specific version:\n\npython3 --version  # check version\n# If < 3.10, try: python3.12 -m pip install sports-skills\n# On macOS with Homebrew: /opt/homebrew/bin/python3.12 -m pip install sports-skills\n\n\nNo API keys required.\n\nQuick Start\n\nPrefer the CLI — it avoids Python import path issues:\n\nsports-skills football get_daily_schedule\nsports-skills football get_season_standings --season_id=premier-league-2025\n\n\nPython SDK (alternative):\n\nfrom sports_skills import football\n\nstandings = football.get_season_standings(season_id=\"premier-league-2025\")\nschedule = football.get_daily_schedule()\n\nChoosing the Season\n\nDerive the current year from the system prompt's date (e.g., currentDate: 2026-02-16 → current year is 2026).\n\nIf the user specifies a season, use it as-is.\nIf the user says \"current\", \"latest\", or doesn't specify: Call get_current_season(competition_id=\"...\") to get the active season_id. Do NOT guess or hardcode the year.\nSeason format: Always {league-slug}-{year} (e.g., \"premier-league-2025\" for the 2025-26 season). The year is the start year of the season, not the end year.\nMLS exception: MLS runs spring-fall within a single calendar year. Use get_current_season(competition_id=\"mls\") — don't assume MLS follows European calendar.\nNever hardcode a season_id. Always derive it via get_current_season() or from the system date.\nData Coverage by League\n\nNot all data is available for every league. Use the right command for the right league.\n\nCommand\tAll 13 leagues\tTop 5 only\tPL only\nget_season_standings\tx\t\t\nget_daily_schedule\tx\t\t\nget_season_schedule\tx\t\t\nget_season_teams\tx\t\t\nsearch_team\tx\t\t\nget_team_schedule\tx\t\t\nget_team_profile\tx\t\t\nget_event_summary\tx\t\t\nget_event_lineups\tx\t\t\nget_event_statistics\tx\t\t\nget_event_timeline\tx\t\t\nget_current_season\tx\t\t\nget_competitions\tx\t\t\nget_event_xg\t\tx\t\nget_event_players_statistics (with xG)\t\tx\t\nget_season_leaders\t\t\tx\nget_missing_players\t\t\tx\n\nTop 5 leagues (Understat): EPL, La Liga, Bundesliga, Serie A, Ligue 1. PL only (FPL): Premier League — injury news, player stats, ownership, ICT index. All leagues: via ESPN — scores, standings, schedules, match summaries, lineups, team stats. Transfermarkt: Works for any player with a tm_player_id — market values and transfer history.\n\nNote: MLS uses a different season structure (spring-fall calendar). Use get_current_season(competition_id=\"mls\") to detect the right season_id.\n\nID Conventions\nseason_id: {league-slug}-{year} e.g. \"premier-league-2025\", \"la-liga-2025\"\ncompetition_id: league slug e.g. \"premier-league\", \"serie-a\", \"champions-league\"\nteam_id: ESPN team ID (numeric string) e.g. \"359\" (Arsenal), \"86\" (Real Madrid)\nevent_id: ESPN event ID (numeric string) e.g. \"740847\"\nfpl_id: FPL element ID or code (PL players only)\ntm_player_id: Transfermarkt player ID e.g. \"433177\" (Saka), \"342229\" (Mbappe)\nCommands\nget_current_season\n\nDetect current season for a competition. Works for all leagues.\n\ncompetition_id (str, required): Competition slug\n\nReturns data.competition and data.season:\n\n{\"competition\": {\"id\": \"premier-league\", \"name\": \"Premier League\"}, \"season\": {\"id\": \"premier-league-2025\", \"name\": \"2025-26 English Premier League\", \"year\": \"2025\"}}\n\nget_competitions\n\nList available competitions with current season info. No params. Works for all leagues.\n\nReturns data.competitions[] with id, name, code, current_season.\n\nget_competition_seasons\n\nGet available seasons for a competition. Works for all leagues.\n\ncompetition_id (str, required): Competition slug\nget_season_schedule\n\nGet full season match schedule. Works for all leagues.\n\nseason_id (str, required): Season slug (e.g., \"premier-league-2025\")\n\nReturns data.schedules[] — same shape as events below.\n\nget_season_standings\n\nGet league table for a season. Works for all leagues.\n\nseason_id (str, required): Season slug\n\nReturns data.standings[].entries[]:\n\n{\n  \"position\": 1,\n  \"team\": {\"id\": \"359\", \"name\": \"Arsenal\", \"short_name\": \"Arsenal\", \"abbreviation\": \"ARS\", \"crest\": \"https://...\"},\n  \"played\": 26, \"won\": 17, \"drawn\": 6, \"lost\": 3,\n  \"goals_for\": 50, \"goals_against\": 18, \"goal_difference\": 32, \"points\": 57\n}\n\nget_season_leaders\n\nGet top scorers/leaders for a season. Premier League only (via FPL).\n\nseason_id (str, required): Season slug (must be premier-league-*)\n\nReturns data.leaders[] — note: player name is nested under .player.name:\n\n{\n  \"player\": {\"id\": \"223094\", \"name\": \"Erling Haaland\", \"first_name\": \"Erling\", \"last_name\": \"Haaland\", \"position\": \"Forward\"},\n  \"team\": {\"id\": \"43\", \"name\": \"Man City\"},\n  \"goals\": 22, \"assists\": 6, \"penalties\": 0, \"played_matches\": 25\n}\n\n\nReturns empty for non-PL leagues.\n\nget_season_teams\n\nGet teams in a season. Works for all leagues.\n\nseason_id (str, required): Season slug\nsearch_team\n\nSearch for a team by name across all leagues (or a specific one). Uses fuzzy matching.\n\nquery (str, required): Team name to search (e.g., \"Corinthians\", \"Barcelona\", \"Man Utd\")\ncompetition_id (str, optional): Limit search to one league (e.g., \"serie-a-brazil\", \"premier-league\")\n\nReturns data.results[] with team, competition, and season for each match:\n\n{\"team\": {\"id\": \"874\", \"name\": \"Corinthians\"}, \"competition\": {\"id\": \"serie-a-brazil\", \"name\": \"Serie A Brazil\"}, \"season\": {\"id\": \"serie-a-brazil-2025\", \"year\": \"2025\"}}\n\nget_team_profile\n\nGet basic team info (name, crest, venue). Does not return squad/roster — use get_season_leaders to find PL player IDs, then get_player_profile for individual player data.\n\nteam_id (str, required): ESPN team ID\nleague_slug (str, optional): League hint (faster resolution)\n\nReturns data.team and data.venue. data.players[] is empty — see \"Deep dive on a PL team\" example below for the recommended workflow.\n\nget_daily_schedule\n\nGet all matches for a specific date across all leagues.\n\ndate (str, optional): Date in YYYY-MM-DD format. Defaults to today.\n\nReturns data.date and data.events[]:\n\n{\n  \"id\": \"748381\", \"status\": \"not_started\", \"start_time\": \"2026-02-16T20:00Z\",\n  \"competition\": {\"id\": \"la-liga\", \"name\": \"La Liga\"},\n  \"season\": {\"id\": \"la-liga-2025\", \"year\": \"2025\"},\n  \"venue\": {\"name\": \"Estadi Montilivi\", \"city\": \"Girona\"},\n  \"competitors\": [\n    {\"team\": {\"id\": \"9812\", \"name\": \"Girona\", \"abbreviation\": \"GIR\"}, \"qualifier\": \"home\", \"score\": 0},\n    {\"team\": {\"id\": \"83\", \"name\": \"Barcelona\", \"abbreviation\": \"BAR\"}, \"qualifier\": \"away\", \"score\": 0}\n  ],\n  \"scores\": {\"home\": 0, \"away\": 0}\n}\n\n\nStatus values: \"not_started\", \"live\", \"halftime\", \"closed\", \"postponed\".\n\nget_event_summary\n\nGet match summary with scores. Works for all leagues.\n\nevent_id (str, required): Match/event ID\n\nReturns data.event (same shape as daily schedule events).\n\nget_event_lineups\n\nGet match lineups. Works for all leagues (when available from ESPN).\n\nevent_id (str, required): Match/event ID\n\nReturns data.lineups[]:\n\n{\n  \"team\": {\"id\": \"364\", \"name\": \"Liverpool\", \"abbreviation\": \"LIV\"},\n  \"qualifier\": \"home\",\n  \"formation\": \"4-3-3\",\n  \"starting\": [{\"id\": \"275599\", \"name\": \"Caoimhín Kelleher\", \"position\": \"Goalkeeper\", \"shirt_number\": 1}],\n  \"bench\": [{\"id\": \"...\", \"name\": \"...\", \"position\": \"...\", \"shirt_number\": 62}]\n}\n\nget_event_statistics\n\nGet match team statistics. Works for all leagues.\n\nevent_id (str, required): Match/event ID\n\nReturns data.teams[]:\n\n{\n  \"team\": {\"id\": \"244\", \"name\": \"Brentford\"},\n  \"qualifier\": \"home\",\n  \"statistics\": {\"ball_possession\": \"40.8\", \"shots_total\": \"10\", \"shots_on_target\": \"3\", \"fouls\": \"12\", \"corners\": \"4\"}\n}\n\nget_event_timeline\n\nGet match timeline/key events (goals, cards, substitutions). Works for all leagues.\n\nevent_id (str, required): Match/event ID\n\nReturns data.timeline[] with goal, card, and substitution events.\n\nget_team_schedule\n\nGet schedule for a specific team — includes both past results and upcoming fixtures. Works for all leagues.\n\nteam_id (str, required): ESPN team ID\nleague_slug (str, optional): League hint (faster resolution)\nseason_year (str, optional): Season year filter\ncompetition_id (str, optional): Filter results to a single competition (e.g., \"serie-a-brazil\", \"premier-league\")\nget_head_to_head\n\nUNAVAILABLE — requires licensed data. Do not call this command; it will return empty results. Instead, use get_team_schedule for both teams and filter overlapping matches manually.\n\nteam_id (str, required): First team ID\nteam_id_2 (str, required): Second team ID\nget_event_xg\n\nGet expected goals (xG) data from Understat. Top 5 leagues only: EPL, La Liga, Bundesliga, Serie A, Ligue 1. Returns empty for other leagues.\n\nevent_id (str, required): Match/event ID\n\nReturns data.teams[] and data.shots[]:\n\n{\"team\": {\"id\": \"244\", \"name\": \"Brentford\"}, \"qualifier\": \"home\", \"xg\": 1.812}\n\n\ndata.shots[] contains individual shot data with xG per shot. Note: very recent matches (last 24-48h) may not be indexed on Understat yet.\n\nget_event_players_statistics\n\nGet player-level match statistics with xG enrichment. Works for all leagues (basic stats from ESPN). xG/xA enrichment only for top 5 leagues (Understat).\n\nevent_id (str, required): Match/event ID\n\nReturns data.teams[].players[]:\n\n{\n  \"id\": \"...\", \"name\": \"Bukayo Saka\", \"position\": \"Midfielder\", \"shirt_number\": 7, \"starter\": true,\n  \"statistics\": {\"appearances\": \"1\", \"shotsTotal\": \"3\", \"shotsOnTarget\": \"1\", \"foulsCommitted\": \"1\", \"xg\": \"0.45\", \"xa\": \"0.12\"}\n}\n\n\nxg and xa fields only present for top 5 leagues.\n\nget_missing_players\n\nGet injured/missing/doubtful players. Premier League only (via FPL). Returns empty for other leagues.\n\nseason_id (str, required): Season slug (must be premier-league-*)\n\nReturns data.teams[].players[]:\n\n{\n  \"id\": \"463748\", \"name\": \"Mikel Merino Zazón\", \"web_name\": \"Merino\",\n  \"position\": \"Midfielder\", \"status\": \"injured\",\n  \"news\": \"Foot injury - Unknown return date\",\n  \"chance_of_playing_this_round\": 0, \"chance_of_playing_next_round\": 0\n}\n\n\nStatus values: \"injured\", \"unavailable\", \"doubtful\", \"suspended\".\n\nget_season_transfers\n\nGet transfer history for specific players via Transfermarkt. Works for any league.\n\nseason_id (str, required): Season slug (used to filter transfers by year)\ntm_player_ids (list, required): Transfermarkt player IDs\n\nReturns data.transfers[]:\n\n{\n  \"player_tm_id\": \"433177\", \"date\": \"2019-07-01\", \"season\": \"19/20\",\n  \"from_team\": {\"name\": \"Arsenal U23\", \"image\": \"https://...\"},\n  \"to_team\": {\"name\": \"Arsenal\", \"image\": \"https://...\"},\n  \"fee\": \"-\", \"market_value\": \"-\"\n}\n\nget_player_season_stats\n\nGet player season stats via ESPN overview endpoint. Works for any league with ESPN athlete IDs.\n\nplayer_id (str, required): ESPN athlete ID\nleague_slug (str, optional): League slug hint (e.g., \"eng.1\", \"esp.1\"). Defaults to auto-detect.\n\nReturns season stats (goals, assists, appearances, etc.) and game log when available.\n\nget_player_profile\n\nGet player profile. Works for any player if you have their Transfermarkt or FPL ID. At least one ID required.\n\nfpl_id (str, optional): FPL player ID (PL players only)\ntm_player_id (str, optional): Transfermarkt player ID (any league)\n\nWith tm_player_id, returns data.player with:\n\n{\n  \"market_value\": {\"value\": 130000000, \"currency\": \"EUR\", \"formatted\": \"€130.00m\", \"date\": \"09/12/2025\", \"age\": \"24\", \"club\": \"Arsenal FC\"},\n  \"market_value_history\": [{\"value\": 7000000, \"formatted\": \"€7.00m\", \"date\": \"23/09/2019\", \"club\": \"Arsenal FC\"}],\n  \"transfer_history\": [\n    {\"player_tm_id\": \"433177\", \"date\": \"2019-07-01\", \"season\": \"19/20\", \"from_team\": {\"name\": \"Arsenal U23\"}, \"to_team\": {\"name\": \"Arsenal\"}, \"fee\": \"-\"}\n  ]\n}\n\n\nWith fpl_id, also includes data.player.fpl_data with FPL stats (points, form, ICT index, ownership, etc.).\n\nSupported Leagues\n\nPremier League, La Liga, Bundesliga, Serie A, Ligue 1, MLS, Championship, Eredivisie, Primeira Liga, Serie A Brazil, Champions League, European Championship, World Cup.\n\nData Sources\nSource\tWhat it provides\tLeague coverage\nESPN\tScores, standings, schedules, lineups, match stats, timelines\tAll 13 leagues\nopenfootball\tSchedules, standings, team lists (fallback when ESPN is down)\t10 leagues (all except CL, Euros, World Cup)\nUnderstat\txG per match, xG per shot, player xG/xA\tTop 5 (EPL, La Liga, Bundesliga, Serie A, Ligue 1)\nFPL\tTop scorers, injuries, player stats, ownership\tPremier League only\nTransfermarkt\tMarket values, transfer history\tAny player (requires tm_player_id)\n\nFor licensed data with full coverage across all sports (Sportradar, Opta, Genius Sports), see Machina Sports.\n\nExamples\n\nUser: \"Show me the Premier League table\"\n\nCall get_current_season(competition_id=\"premier-league\") to get the current season_id\nCall get_season_standings(season_id=<season_id from step 1>)\nPresent standings table with position, team, played, won, drawn, lost, GD, points\n\nUser: \"How did Arsenal vs Liverpool go?\"\n\nCall get_daily_schedule() or get_team_schedule(team_id=\"359\") to find the event_id\nCall get_event_summary(event_id=\"...\") for the score\nCall get_event_statistics(event_id=\"...\") for possession, shots, etc.\nCall get_event_xg(event_id=\"...\") for xG comparison (EPL — top 5 only)\nPresent match report with scores, key stats, and xG\n\nUser: \"Deep dive on Chelsea's recent form\"\n\nCall search_team(query=\"Chelsea\") → team_id=363, competition=premier-league\nCall get_team_schedule(team_id=\"363\", competition_id=\"premier-league\") → find recent closed events\nFor each recent match, call in parallel:\nget_event_xg(event_id=\"...\") for xG comparison and shot map\nget_event_statistics(event_id=\"...\") for possession, shots, passes\nget_event_players_statistics(event_id=\"...\") for individual player xG/xA\nCall get_missing_players(season_id=<season_id>) → filter Chelsea's injured/doubtful players\nCall get_season_leaders(season_id=<season_id>) → filter Chelsea players, get their FPL IDs\nCall get_player_profile(fpl_id=\"...\", tm_player_id=\"...\") for key players — combine FPL stats (form, ownership, ICT) with Transfermarkt data (market value, transfer history)\nPresent: xG trend across matches, key player stats, injury report, market values\n\nUser: \"What's Saka's market value?\"\n\nCall get_player_profile(tm_player_id=\"433177\") for Transfermarkt data\nOptionally add fpl_id for FPL stats if Premier League player\nPresent market value, value history, and transfer history\n\nUser: \"Tell me about Corinthians\"\n\nCall search_team(query=\"Corinthians\") → team_id=874, competition=serie-a-brazil\nCall get_team_schedule(team_id=\"874\", competition_id=\"serie-a-brazil\") for fixtures\nPick a recent match and call get_event_timeline(event_id=\"...\") for goals, cards, subs\nNote: xG, FPL stats, and season leaders are NOT available for Brazilian Serie A\nError Handling\n\nWhen a command fails (wrong event_id, missing data, network error, etc.), do not surface the raw error to the user. Instead:\n\nCatch it silently — treat the failure as an exploratory miss, not a fatal error.\nTry alternatives — e.g., if an event_id returns no data, call get_daily_schedule() or get_team_schedule() to discover the correct ID. If ESPN is down, openfootball data may still be available via get_season_standings or get_season_schedule.\nOnly report failure after exhausting alternatives — and when you do, give a clean human-readable message (e.g., \"I couldn't find that match — can you confirm the teams or date?\"), not a traceback or raw CLI output.\n\nThis is especially important when the agent is responding through messaging platforms (Telegram, Slack, etc.) where raw exec failures look broken.\n\nCommon Mistakes\n\nThese are the ONLY valid commands. Do not invent or guess command names:\n\nget_current_season\nget_competitions\nget_competition_seasons\nget_season_schedule\nget_season_standings\nget_season_leaders\nget_season_teams\nsearch_team\nget_team_profile\nget_daily_schedule\nget_event_summary\nget_event_lineups\nget_event_statistics\nget_event_timeline\nget_team_schedule\nget_head_to_head\nget_event_xg\nget_event_players_statistics\nget_missing_players\nget_season_transfers\nget_player_profile\nget_player_season_stats\n\nCommands that DO NOT exist (commonly hallucinated):\n\nget_standings — the correct command is get_season_standings (requires season_id).\nget_live_scores — not available. Use get_daily_schedule() for today's matches; status field shows \"live\" for in-progress games.\nget_team_squad / get_team_roster — get_team_profile does NOT return players. Use get_season_leaders for PL player IDs, then get_player_profile for individual data.\nget_transfers — the correct command is get_season_transfers (requires season_id + tm_player_ids).\nget_match_results / get_match — use get_event_summary with an event_id.\nget_player_stats — use get_event_players_statistics for match-level stats, or get_player_profile for career data.\n\nOther common mistakes:\n\nUsing get_season_leaders or get_missing_players on non-PL leagues — they return empty. Check the Data Coverage table.\nUsing get_event_xg on leagues outside the top 5 — returns empty. Only works for EPL, La Liga, Bundesliga, Serie A, Ligue 1.\nGuessing team_id or event_id instead of discovering them via search_team, get_daily_schedule, or get_season_schedule.\n\nIf you're unsure whether a command exists, check this list. Do not try commands that aren't listed above.\n\nTroubleshooting\nsports-skills command not found: Package not installed. Run pip install sports-skills. If the package is not found on PyPI, install from GitHub: pip install git+https://github.com/machina-sports/sports-skills.git. Requires Python 3.10+ — see Setup section.\nModuleNotFoundError: No module named 'sports_skills': Same as above — install the package. Prefer the CLI over Python imports to avoid path issues.\nEmpty results for PL-only commands on other leagues: get_season_leaders and get_missing_players only return data for Premier League. They silently return empty for other leagues — check the Data Coverage table.\nget_team_profile returns empty players: This is expected — squad rosters are not available. To get player data for a PL team, use get_season_leaders to find players and their FPL IDs, then get_player_profile(fpl_id=\"...\") for detailed stats. For Transfermarkt data, you need the player's tm_player_id.\nFinding FPL IDs and Transfermarkt IDs: Use get_season_leaders(season_id=\"premier-league-2025\") to discover FPL IDs for PL players. Transfermarkt IDs must be looked up on transfermarkt.com — the ID is the number at the end of the player's URL. Well-known examples: Cole Palmer = 568177, Bukayo Saka = 433177, Mbappe = 342229.\nNo xG for recent matches: Understat data may lag 24-48 hours after a match ends. If get_event_xg returns empty for a recent top-5 match, try again later.\nWrong season_id format: Must be {league-slug}-{year} e.g. \"premier-league-2025\". Not \"2025-2026\", not \"EPL-2025\". Use get_current_season() to discover the correct format.\nTeam/event IDs unknown: Use search_team(query=\"team name\") to find team IDs by name, or get_season_teams to list all teams in a season. Use get_daily_schedule or get_season_schedule to find event IDs. IDs are ESPN numeric strings."
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/antonelli182/football-data",
    "publisherUrl": "https://clawhub.ai/antonelli182/football-data",
    "owner": "antonelli182",
    "version": "0.1.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/football-data",
    "downloadUrl": "https://openagent3.xyz/downloads/football-data",
    "agentUrl": "https://openagent3.xyz/skills/football-data/agent",
    "manifestUrl": "https://openagent3.xyz/skills/football-data/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/football-data/agent.md"
  }
}