{% extends "docs/base.html" %}

{% block docs_content %}
  <div class="alert alert-info mb-4" role="note">
    Learn when and where to publish instructions in the <a href="/docs/guides/hosted-skills">Server-hosted skills guide</a>.
  </div>
  <div class="d-flex flex-wrap align-items-center justify-content-between gap-2 mb-4">
    <div>
      <h1 class="h3 mb-1">Skills API</h1>
      <p class="text-muted mb-0">Owner-qualified CRUD for canonical <code>SKILL.md</code> documents.</p>
    </div>
    <a class="btn btn-sm btn-outline-secondary" href="/api/v1/openapi.json">OpenAPI JSON</a>
  </div>

  <div class="card shadow-sm mb-4">
    <div class="card-body">
      <h2 class="h5">Routes</h2>
      <p>Use <code>GET</code> and <code>POST</code> on each collection, then <code>GET</code>, <code>PUT</code>, and <code>DELETE</code> on <code>/{skill_slug}</code>.</p>
      <ul class="mb-0">
        <li><code>/api/v1/users/{username}/skills</code>; <code>self</code> is accepted as the username.</li>
        <li><code>/api/v1/teams/{team_slug}/skills</code></li>
        <li><code>/api/v1/users/{username}/repos/{repo_slug}/skills</code></li>
        <li><code>/api/v1/teams/{team_slug}/repos/{repo_slug}/skills</code></li>
      </ul>
    </div>
  </div>

  <div class="card shadow-sm mb-4">
    <div class="card-body">
      <h2 class="h5">Request and response</h2>
      <p>Create and update requests use one JSON field containing the complete canonical document:</p>
      <pre class="bg-light border rounded p-3"><code>{"content":"---\nname: release-notes\ndescription: Prepare release notes\n---\n\nVerify links."}</code></pre>
      <p class="mb-0">Lists are paginated and omit <code>content</code>. Detail and mutation responses include <code>content</code>. Public UUIDs, hashes, slugs, descriptions, and timestamps are returned; internal database IDs are never returned.</p>
    </div>
  </div>

  <div class="card shadow-sm">
    <div class="card-body">
      <h2 class="h5">Access</h2>
      <ul class="mb-0">
        <li>User and personal-repository skills are available to their owner.</li>
        <li>Team members can read team and team-repository skills; team owners can create, update, and delete them.</li>
        <li>Archived repository skills remain readable, while every mutation returns <code>403 Forbidden</code>.</li>
        <li>Duplicate names return <code>409 Conflict</code>; invalid canonical documents return <code>400 Bad Request</code>.</li>
      </ul>
    </div>
  </div>
{% endblock %}