API Reference

SkillShield exposes JSON APIs under /api. The application does not provide built-in authentication, so production deployments should place sensitive endpoints behind an appropriate access-control layer.

POST /api/validate

Validate a set of skill files and store the resulting report.

Request

{
  "files": [
    {
      "path": "SKILL.md",
      "content": "---\nname: my-skill\n---\n\n# Instructions"
    }
  ],
  "source": {
    "type": "paste"
  }
}

The endpoint accepts up to 30 files, 3 MB per file, and 15 MB for the complete request.

Response

Returns a stored ValidationResult containing:

• id and timestamp
• skillName
• overallScore and riskLevel
• summary, axes, and findings
• compatibility and tokenAnalysis
• skillPreview
• optional source metadata

If the overall score is below 70, the server attempts to create a pending approval record. Failure to create that record does not fail the validation request.

GET /api/validate

Retrieve a stored validation result.

POST /api/github

Import a skill from GitHub and audit repository-level installation and execution surfaces before validation.

Request

{
  "owner": "user",
  "repo": "my-skills",
  "path": "skills/my-skill",
  "branch": "main",
  "sha": "abc123def456",
  "includeExtensions": [".md", ".yaml"],
  "ignorePaths": ["node_modules", ".git"]
}

branch, sha, extension filters, and ignore paths are optional. When a repository root contains multiple skills and no path is supplied, the endpoint returns requiresSkillSelection: true with the discovered skill paths.

Response

{
  "files": [{ "path": "SKILL.md", "content": "..." }],
  "owner": "user",
  "repo": "my-skills",
  "branch": "main",
  "path": "skills/my-skill",
  "truncated": false,
  "repositoryMeta": {
    "fullName": "user/my-skills",
    "stars": 12,
    "forks": 1,
    "openIssues": 0,
    "archived": false,
    "license": "MIT"
  },
  "repositoryAudit": {
    "riskLevel": "medium",
    "summary": {
      "totalFiles": 14,
      "workflowCount": 1,
      "installScriptCount": 1,
      "installSurfaceCount": 3,
      "truncated": false
    },
    "surfaces": [],
    "findings": []
  }
}

repositoryAudit covers install and execution surfaces. repositoryMeta provides repository trust signals for the report UI. Configure GITHUB_TOKEN to improve API limits and scan private repositories accessible to that token.

GET /api/report

Export a stored scan report.

The pdf format returns print-friendly HTML for the browser's save-to-PDF workflow; it does not return a binary PDF.

POST /api/ai-review

Run provider-backed analysis on an existing set of findings.

{
  "findings": [
    {
      "id": "finding-1",
      "severity": "high",
      "category": "command-injection",
      "title": "Pipe to shell",
      "message": "A downloaded script is executed directly."
    }
  ],
  "skillName": "my-skill",
  "provider": "openai"
}

Supported request providers are openai, anthropic, opencode-go, and opencode-zen. Configure the matching OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENCODE_GO_API_KEY, or OPENCODE_ZEN_API_KEY environment variable. When provider is omitted, SkillShield uses the first configured provider in that order. OpenCode model selection can be overridden with OPENCODE_GO_MODEL or OPENCODE_ZEN_MODEL; both default to kimi-k2.7-code. Finding snippets are redacted for common secret formats before they are sent to the provider.

Approvals

GET /api/approvals

List approval records or retrieve the record for one scan.

POST /api/approvals

Approve or reject a scan.

{
  "scanId": "scan_123",
  "action": "approve",
  "reviewer": "admin",
  "notes": "Reviewed the install surfaces and findings."
}

Audit logs

GET /api/audit

Webhooks

• GET /api/webhooks lists registered webhooks.
• POST /api/webhooks registers a webhook.
• DELETE /api/webhooks deletes a webhook by id.

Example registration request:

{
  "url": "https://hooks.example.com/skillshield",
  "events": ["scan.completed"],
  "secret": "whs_xxx"
}

Policy evaluation

POST /api/policy

Evaluate existing findings and a score against a supplied policy object.

{
  "score": 82,
  "findings": [],
  "policy": {
    "mode": "default",
    "failOn": "high",
    "blockSecrets": true,
    "blockDestructiveCommands": true,
    "requirePermissionManifest": false,
    "allowExternalDomains": [],
    "blockedCommands": [],
    "maxFileSizeMB": 10,
    "maxFiles": 100
  }
}

Additional endpoints