Public

SkillMD Doctor

SkillMD Doctor checks whether a SKILL.md is concrete enough for an autonomous agent and probes live GET/HEAD endpoints before the agent relies on them.

Base URL: https://skillmd-doctor.vercel.app

GET /api/health

Returns service status.

Example curl:

curl -s https://skillmd-doctor.vercel.app/api/health

Example response:

{
  "ok": true,
  "service": "SkillMD Doctor",
  "version": "0.1.0"
}

GET /api/schema

Returns the request shapes for the service.

Example curl:

curl -s https://skillmd-doctor.vercel.app/api/schema

Example response:

{
  "service": "SkillMD Doctor",
  "endpoints": [
    { "method": "POST", "path": "/api/analyze" },
    { "method": "POST", "path": "/api/probe" }
  ]
}

POST /api/analyze

Analyzes a SKILL.md body for title, base URL, endpoint declarations, curl examples, example responses, and numbered usage steps. Set probe to true to test up to eight GET/HEAD endpoints found in the skill.

Example curl:

curl -s https://skillmd-doctor.vercel.app/api/analyze \
  -H "content-type: application/json" \
  -d '{"skill_md":"# Demo\n\nBase URL:\nhttps://example.com\n\n## GET /api/health\n\nExample curl:\n\n```bash\ncurl -s https://example.com/api/health\n```\n\nExample response:\n\n```json\n{\"ok\":true}\n```\n\n1. Call the health endpoint before using the service.","endpoints":["GET https://example.com/api/health"],"probe":false}'

Example response:

{
  "ok": true,
  "analysis": {
    "score": 100,
    "verdict": "ready",
    "warnings": []
  },
  "probes": [],
  "advice": "The skill file is concrete enough for an agent to try."
}

POST /api/probe

Probes live GET/HEAD endpoints. POST/PUT/PATCH/DELETE endpoints are reported as skipped to avoid side effects.

Example curl:

curl -s https://skillmd-doctor.vercel.app/api/probe \
  -H "content-type: application/json" \
  -d '{"endpoints":["GET https://skillmd-doctor.vercel.app/api/health"]}'

Example response:

{
  "ok": true,
  "checked": 1,
  "all_reachable": true,
  "results": [
    {
      "method": "GET",
      "url": "https://skillmd-doctor.vercel.app/api/health",
      "ok": true,
      "status": 200
    }
  ]
}

How an agent should use this service

1. Read a candidate SKILL.md and send its Markdown text to POST /api/analyze.
2. If the verdict is not-ready or needs-polish, report the warnings before trying to use the candidate service.
3. If the verdict is ready, call POST /api/probe with every GET or HEAD endpoint the agent plans to depend on.
4. Treat a failed probe as a deployment problem and ask the user to resubmit or warm the service.
5. After the skill passes analysis and probes, use the candidate service normally.