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

{% block docs_content %}
  <div class="d-flex flex-wrap align-items-center justify-content-between gap-2 mb-4">
    <div>
      <h1 class="h3 mb-1">Skills documentation</h1>
      <p class="text-muted mb-0">Discover hosted instruction documents and the downloadable Pearing workflow skill.</p>
    </div>
    <div class="d-flex gap-2">
      <a class="btn btn-sm btn-outline-secondary" href="/docs/api/skills">Skills API</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/cli/skills">Skills CLI</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/mcp/skills">Skills MCP</a>
    </div>
  </div>

  <div class="alert alert-info mb-4" role="note">
    New to reusable instructions? Read the <a href="/docs/guides/hosted-skills">Server-hosted skills guide</a>.
    For durable collaboration and code review, read <a href="/docs/guides/threads-and-pulls">Threads, replies, and pulls</a>
    or follow the <a href="/docs/guides/feature-delivery">complete feature-delivery guide</a>.
  </div>

  <div class="card shadow-sm mb-4">
    <div class="card-body">
      <h2 class="h5 mb-2" id="stored-skills"><a class="link-body-emphasis text-decoration-none" href="#stored-skills">Stored skills</a></h2>
      <p class="mb-2">
        Signed-in users can manage reusable instruction documents from <a href="/profile/skills">Profile &gt; Skills</a>.
        Skills may belong to a user, team, or repository; team and repository settings expose matching
        <strong>Skills</strong> tabs.
      </p>
      <p class="mb-2">
        Each record is one canonical <code>SKILL.md</code>. Its required frontmatter contains a lowercase
        kebab-case <code>name</code> and a <code>description</code>; indexed metadata is derived from that document.
        List responses contain metadata only, while detail responses include canonical content.
      </p>
      <ul class="mb-2">
        <li>User skills are private to that user.</li>
        <li>Team members can read team and team-repository skills; team owners can change them.</li>
        <li>Personal-repository skills follow repository-owner access.</li>
        <li>Archived repositories keep skills readable but reject changes; deleted repositories do not expose skills.</li>
      </ul>
      <p class="text-muted mb-0">
        Deleting a skill is permanent. Skill text is instruction content, not trusted executable code;
        clients and agents must still apply their normal review, permission, and execution safeguards.
      </p>
    </div>
  </div>

  <div class="row g-3 mb-4">
    <div class="col-12 col-lg-4"><div class="card h-100"><div class="card-body"><h2 class="h5">Website</h2><p class="mb-0 text-muted">Create, inspect, preview, download, and update scoped skills interactively.</p></div></div></div>
    <div class="col-12 col-lg-4"><div class="card h-100"><div class="card-body"><h2 class="h5">CLI and API</h2><p class="mb-0 text-muted">Publish canonical files from local review flows or custom integrations.</p></div></div></div>
    <div class="col-12 col-lg-4"><div class="card h-100"><div class="card-body"><h2 class="h5">MCP</h2><p class="mb-0 text-muted">Let agents discover metadata and fetch current content through typed tools.</p></div></div></div>
  </div>

  <div class="card shadow-sm">
    <div class="card-body">
      <div class="d-flex flex-column flex-md-row align-items-start justify-content-between gap-3">
        <div>
          <h2 class="h5 mb-2" id="workflow-skill"><a class="link-body-emphasis text-decoration-none" href="#workflow-skill">Pearing workflow skill</a></h2>
          <p class="mb-0">
            The published workflow <code>SKILL.md</code> is a bootstrap and compatibility entry point for agents.
            The Guides hold the human-readable concepts and complete scenarios; the skill keeps concise operating rules.
          </p>
        </div>
        <a class="btn btn-primary" href="/docs/skills/pearing-workflow-skill.md">Read SKILL.md</a>
      </div>
    </div>
  </div>
{% endblock %}