> ## Documentation Index
> Fetch the complete documentation index at: https://learn.actionist.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Portable behavior packs your agents load at runtime. Author them locally, install from the marketplace, or pull them in from shared workspaces.

<div className="mxp-hero xc-border">
  <div className="exp-eyebrow mxp-rise">ENCODED EXPERTISE</div>

  <h2 className="mxp-hero-title mxp-rise" style={{animationDelay:'0.06s'}}>
    Teach it once. <span style={{background:'linear-gradient(90deg,#24A4FF,#9000FF,#E3008E)',WebkitBackgroundClip:'text',backgroundClip:'text',color:'transparent'}}>Every agent knows it.</span>
  </h2>

  <p className="mxp-hero-dek mxp-rise" style={{animationDelay:'0.13s'}}>
    A Skill is a tested playbook your agents load at runtime — a plain SKILL.md file with the procedure, the safety rules, and the triggers that tell an agent when to reach for it. Author it once, enable it anywhere.
  </p>
</div>

<div className="w-full py-10">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">The moment it clicks</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">Watch a skill get matched.</h2>

    <p className="text-base text-gray-600 dark:text-gray-400 max-w-3xl">
      You never invoke a skill by hand. The agent reads your request, matches it against every enabled skill's trigger phrases, and loads the winning playbook. Pick a task:
    </p>
  </div>

  <div className="mxs exp-tool-shell xc-try">
    <div className="mxp-srch-chips">
      <label htmlFor="st-a"><input className="mxp-r" type="radio" name="st" id="st-a" defaultChecked />"Summarize my unread emails"</label>
      <label htmlFor="st-b"><input className="mxp-r" type="radio" name="st" id="st-b" />"Put together a brief on Northwind"</label>
      <label htmlFor="st-c"><input className="mxp-r" type="radio" name="st" id="st-c" />"Send the weekly digest"</label>
    </div>

    <div className="mxs-tp mxs-tp-a">
      <div className="mxp-window">
        <div className="mxp-window-bar"><span className="mxp-window-dot" /><span className="mxp-window-dot" /><span className="mxp-window-dot" /><span className="mxp-window-title">chat · maya</span></div>

        <div className="mxp-window-body" style={{minHeight:'auto',padding:'14px 18px'}}>
          <div className="mxp-stream-line"><span className="mxp-stream-time">you</span><span className="mxp-stream-text">Summarize my unread emails.</span></div>
          <div style={{margin:'8px 0'}}><span className="mxp-stream-event">skill matched · email-summarise</span></div>
          <div className="mxp-stream-line"><span className="mxp-stream-time">maya</span><span className="mxp-stream-text">Loading the playbook — grouping by sender, ranking by urgency, <em>never marking as read</em>.</span></div>
        </div>
      </div>

      <div className="mxs-match">Matched trigger: <em>"when the user asks to summarize unread emails"</em> — declared in the skill's frontmatter. Specific phrasing wins; vague triggers misfire.</div>
    </div>

    <div className="mxs-tp mxs-tp-b">
      <div className="mxp-window">
        <div className="mxp-window-bar"><span className="mxp-window-dot" /><span className="mxp-window-dot" /><span className="mxp-window-dot" /><span className="mxp-window-title">chat · maya</span></div>

        <div className="mxp-window-body" style={{minHeight:'auto',padding:'14px 18px'}}>
          <div className="mxp-stream-line"><span className="mxp-stream-time">you</span><span className="mxp-stream-text">Put together a brief on Northwind.</span></div>
          <div style={{margin:'8px 0'}}><span className="mxp-stream-event">skill matched · competitor-research · context: fork</span></div>
          <div className="mxp-stream-line"><span className="mxp-stream-time">maya</span><span className="mxp-stream-text">This one runs as a <em>sub-agent with its own context budget</em> — the long research output won't crowd our conversation.</span></div>
        </div>
      </div>

      <div className="mxs-match">Matched trigger: <em>"when the user asks for a competitor brief"</em>. Because the skill declares <em>context: fork</em>, it spawns an isolated sub-agent for the heavy lifting.</div>
    </div>

    <div className="mxs-tp mxs-tp-c">
      <div className="mxp-window">
        <div className="mxp-window-bar"><span className="mxp-window-dot" /><span className="mxp-window-dot" /><span className="mxp-window-dot" /><span className="mxp-window-title">schedule · friday 16:00 · maya</span></div>

        <div className="mxp-window-body" style={{minHeight:'auto',padding:'14px 18px'}}>
          <div className="mxp-stream-line"><span className="mxp-stream-time">sched</span><span className="mxp-stream-text">Task: send the weekly digest.</span></div>
          <div style={{margin:'8px 0'}}><span className="mxp-stream-event">skill matched · weekly-digest</span></div>
          <div className="mxp-stream-line"><span className="mxp-stream-time">maya</span><span className="mxp-stream-text">Same playbook, no human in the loop — skills fire on <em>schedules and triggers</em> exactly as they do in chat.</span></div>
        </div>
      </div>

      <div className="mxs-match">Matched trigger: <em>"when asked to send the weekly digest"</em>. Skills work identically in conversation, in workflows, and on unattended scheduled runs.</div>
    </div>
  </div>

  <Columns cols={2}>
    <Card title="Without skills" icon="copy">
      You paste the same Gmail auth steps, safety rules, and output format into every agent that touches email. When the procedure changes, you update four different instruction blocks — and miss one.
    </Card>

    <Card title="With skills" icon="package-check">
      You write the procedure once in a `SKILL.md` file. Enable it on any agent. When the procedure changes, you update one file — the catalog broadcasts the refresh to every consumer automatically.
    </Card>
  </Columns>
</div>

<div className="w-full py-10 xc-rise">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">One source of truth</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">Every agent, same playbook.</h2>

    <p className="text-base text-gray-600 dark:text-gray-400 max-w-3xl">
      When the procedure changes you update one file. Every agent that has it enabled picks up the change on its next run.
    </p>
  </div>

  <div className="xc-receipt">
    <div className="xc-receipt-head">ONE SKILL · EVERY AGENT</div>
    <div className="xc-receipt-sub">weekly-digest skill · four agents · illustrative team</div>

    <div className="xc-receipt-row">
      <span>Maya · Marketing — sends to 47 recipients</span>
      <span>\~18 min/mo saved</span>
    </div>

    <div className="xc-receipt-row">
      <span>Dario · Sales — pipeline summary to 12 reps</span>
      <span>\~14 min/mo saved</span>
    </div>

    <div className="xc-receipt-row">
      <span>Priya · Support — ticket-volume digest to team lead</span>
      <span>\~14 min/mo saved</span>
    </div>

    <div className="xc-receipt-row">
      <span>Sam · Solo founder — personal inbox roundup</span>
      <span>\~10 min/mo saved</span>
    </div>

    <div className="xc-receipt-total">
      <span>One SKILL.md, zero drift</span>
      <span>\~56 min/mo</span>
    </div>

    <div className="xc-receipt-foot">ILLUSTRATIVE FIGURES</div>
  </div>

  <div className="xc-quote" style={{marginTop:'28px'}}>
    <p>Update the playbook in one file. Every agent that has it enabled learns it on the next run — no copy-paste, no version drift, no missed instruction block.</p>
    <span>— skills · catalog broadcast · single source of truth</span>
  </div>
</div>

<div className="w-full py-10 xc-rise">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">The file</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">One file. Five jobs.</h2>

    <p className="text-base text-gray-600 dark:text-gray-400 max-w-3xl">
      Everything a skill is lives in one Markdown file: YAML frontmatter on top, the playbook below. Click a zone to see what it does.
    </p>
  </div>

  <div className="mxs-anat exp-tool-shell xc-try">
    <div className="mxp-srch-chips">
      <label htmlFor="an-a"><input className="mxp-r" type="radio" name="an" id="an-a" defaultChecked />Identity</label>
      <label htmlFor="an-b"><input className="mxp-r" type="radio" name="an" id="an-b" />Triggers</label>
      <label htmlFor="an-c"><input className="mxp-r" type="radio" name="an" id="an-c" />Credentials</label>
      <label htmlFor="an-d"><input className="mxp-r" type="radio" name="an" id="an-d" />Allowed tools</label>
      <label htmlFor="an-e"><input className="mxp-r" type="radio" name="an" id="an-e" />The playbook</label>
    </div>

    <div className="mxp-window" style={{marginTop:18}}>
      <div className="mxp-window-bar"><span className="mxp-window-dot" /><span className="mxp-window-dot" /><span className="mxp-window-dot" /><span className="mxp-window-title">company/skills/email-summarise/SKILL.md</span></div>

      <div className="mxp-window-body" style={{minHeight:'auto'}}>
        <span className="lz lz-fm">---</span>
        <span className="lz lz-id">name: email-summarise</span>
        <span className="lz lz-id">description: Reads unread Gmail and returns a ranked summary.</span>
        <span className="lz lz-id">version: 1.0.0</span>
        <span className="lz lz-tr">triggers:</span>
        <span className="lz lz-tr">  - when the user asks to summarize unread emails</span>
        <span className="lz lz-tr">  - when the user wants a morning email digest</span>
        <span className="lz lz-cr">credentials:</span>
        <span className="lz lz-cr">  gmail\_token: env GMAIL\_ACCESS\_TOKEN · oauth · required</span>
        <span className="lz lz-tl">allowed-tools:</span>
        <span className="lz lz-tl">  - mcp\_gmail\_list\_messages</span>
        <span className="lz lz-tl">  - mcp\_gmail\_get\_message</span>
        <span className="lz lz-fm">---</span>
        <span className="lz lz-bd"># email-summarise</span>
        <span className="lz lz-bd">Group unread mail by sender. Rank by urgency. One-sentence</span>
        <span className="lz lz-bd">summaries. Never mark messages as read.</span>
      </div>
    </div>

    <div className="anx anx-a"><strong>Identity.</strong> `name` and `description` are the only required fields — without them the file fails validation and shows an invalid badge on its folder. The name becomes the catalog slug: lowercase, hyphens, and ideally a namespace prefix (`acme-gmail-summarise`) so it never silently shadows a bundled skill.</div>
    <div className="anx anx-b"><strong>Triggers.</strong> Natural-language phrases that tell agents when to reach for this skill. Concrete and distinct wins: "when the user asks to summarize unread emails" is strong; "for email tasks" misfires. Add at least two — the drawer warns when a skill has none.</div>
    <div className="anx anx-c"><strong>Credentials.</strong> Slot declarations, never values. Each entry maps a slot to a vault key — Actionist resolves the real secret from the encrypted vault at runtime, so nothing sensitive ever sits in the file.</div>
    <div className="anx anx-d"><strong>Allowed tools.</strong> An explicit allow-list of what the agent may call while running this skill. Omit it and the agent keeps its full toolset; specify it and an email-reading skill physically cannot write files or run terminal commands.</div>
    <div className="anx anx-e"><strong>The playbook.</strong> Free-form Markdown the agent reads and follows: the procedure, the safety rules, the output format. This is where your expertise lives — written like you'd brief a careful new hire.</div>
  </div>
</div>

<div className="w-full py-10 xc-rise">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">Where skills come from</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">Five source groups, one catalog.</h2>

    <p className="text-base text-gray-600 dark:text-gray-400 max-w-3xl">
      Every skill on the Skills page belongs to one of five groups — each marked in the list with its own accent ribbon. The group determines where the skill came from and what you can do with it.
    </p>
  </div>

  <div className="mxs-tiers">
    <div className="mxs-tier" style={{borderTopColor:'#AF35FF'}}>
      <strong>Bundled</strong><span className="tag">Ships with Actionist</span>
      <p>`web-task`, `agent-browser`, and the core integration set. `agent-browser` is always enabled and cannot be toggled off.</p>
    </div>

    <div className="mxs-tier" style={{borderTopColor:'#6EA5FF'}}>
      <strong>Custom</strong><span className="tag">Authored locally</span>
      <p>Skills you write yourself — a SKILL.md in your workspace. Full ownership, full control.</p>
    </div>

    <div className="mxs-tier" style={{borderTopColor:'#A78BFA'}}>
      <strong>Workspace</strong><span className="tag">Shared workspace</span>
      <p>Pulled from a shared workspace folder. Visible to your whole organization, never published publicly.</p>
    </div>

    <div className="mxs-tier" style={{borderTopColor:'#4ED8A7'}}>
      <strong>Marketplace</strong><span className="tag">Actionist store</span>
      <p>Community and curated skills. Automatic updates when new versions are approved.</p>
    </div>

    <div className="mxs-tier" style={{borderTopColor:'#38BDF8'}}>
      <strong>VPS</strong><span className="tag">Paired server</span>
      <p>Deployed by zip upload to a paired VPS. Visible in VPS/web mode, where the page reads "VPS Skills".</p>
    </div>
  </div>

  <div className="mxs-prec">
    name collision? precedence: <b style={{borderColor:'#AF35FF'}}>bundled</b> ▸ <b style={{borderColor:'#6EA5FF'}}>custom</b> ▸ <b style={{borderColor:'#4ED8A7'}}>marketplace</b>
  </div>

  <Note>
    Shadowing is silent — a custom skill named `gmail` quietly overrides the bundled `gws-gmail` with no error shown. Prefix your custom skills (`acme-gmail-summarise`) and the problem never occurs.
  </Note>
</div>

<hr className="xc-divider" />

<div className="w-full py-10 xc-rise">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">The page</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">The Skills page at a glance.</h2>

    <p className="text-base text-gray-600 dark:text-gray-400 max-w-3xl">
      Open <strong>Skills</strong> in the sidebar. Everything you need to discover, manage, and author skills lives here.
    </p>
  </div>

  {/* TODO(image): skills-page-overview — IMAGE SPEC: Full Skills page screenshot. Top row: four stat cards (Discovered, Enabled, Folders with 'all healthy' sub-label, Your skills with 'N custom · N from marketplace'). Left side pane: search input, Source filter pills (All / Bundled / Custom / Workspace / Marketplace / VPS), Status filter pills (All / Enabled / Disabled), Folders section with a registered folder entry, and the three-step How skills work guide. Main list: Bundled group with its colored accent ribbon and two or three example skill rows with toggle switches, then a Custom group with its own colored ribbon and an example custom skill row. — replace this CSS mock with the real screenshot */}

  <div className="m2-mock-overview">
    <div className="m2-stat-row">
      <div className="m2-stat-card"><div className="m2-stat-card-val">24</div><div className="m2-stat-card-lbl">Discovered</div></div>
      <div className="m2-stat-card"><div className="m2-stat-card-val">18</div><div className="m2-stat-card-lbl">Enabled</div></div>
      <div className="m2-stat-card"><div className="m2-stat-card-val">3</div><div className="m2-stat-card-lbl">Folders · all healthy</div></div>
      <div className="m2-stat-card"><div className="m2-stat-card-val">6</div><div className="m2-stat-card-lbl">Your skills · 4 custom · 2 marketplace</div></div>
    </div>

    <div className="m2-body-split">
      <div className="m2-side-pane">
        <div className="m2-side-heading">Source</div>
        <span className="m2-filter-pill is-active">All</span>
        <span className="m2-filter-pill" style={{borderTopColor:'#AF35FF'}}>Bundled</span>
        <span className="m2-filter-pill">Custom</span>
        <span className="m2-filter-pill">Workspace</span>
        <span className="m2-filter-pill">Marketplace</span>
        <span className="m2-filter-pill">VPS</span>
        <div className="m2-side-heading" style={{marginTop:12}}>Status</div>
        <span className="m2-filter-pill is-active">All</span>
        <span className="m2-filter-pill">Enabled</span>
        <span className="m2-filter-pill">Disabled</span>
      </div>

      <div className="py-3 px-4">
        <div className="m2-group-ribbon m2-ribbon-bundled">Bundled</div>

        <div className="m2-skill-row">
          <span className="m2-skill-name">web-task</span>
          <span className="m2-skill-badge">bundled</span>

          <div className="m2-toggle" />
        </div>

        <div className="m2-skill-row">
          <span className="m2-skill-name">agent-browser</span>
          <span className="m2-skill-badge">bundled</span>

          <div className="m2-toggle" />
        </div>

        <div className="m2-group-ribbon m2-ribbon-custom" style={{marginTop:14}}>Custom</div>

        <div className="m2-skill-row">
          <span className="m2-skill-name">email-summarise</span>
          <span className="m2-skill-badge" style={{background:'rgb(110 165 255 / 0.1)',color:'#6EA5FF',borderColor:'rgb(110 165 255 / 0.3)'}}>custom</span>

          <div className="m2-toggle" />
        </div>
      </div>
    </div>
  </div>

  <Columns cols={2}>
    <Card title="Stat cards" icon="chart-column">
      Four tiles at the top give you a live count: <strong>Discovered</strong> (total skills indexed), <strong>Enabled</strong> (ready for agents), <strong>Folders</strong> (with a health sub-label: "all healthy" or "N missing"), and <strong>Your skills</strong> (custom count + marketplace count).
    </Card>

    <Card title="Side pane" icon="layout-list">
      Use the search box to filter by Source group or by Status (All / Enabled / Disabled). The Folders section shows every registered skill directory with per-folder health badges.
    </Card>

    <Card title="Grouped list" icon="layers">
      Skills are grouped by source, each group marked with a colored accent ribbon. Within a group, skills sort alphabetically. Empty groups are hidden. Each row shows the skill name, source badge, pack name (if part of one), and a toggle switch.
    </Card>

    <Card title="Header actions" icon="mouse-pointer-click">
      On desktop: <strong>Refresh</strong>, <strong>Add folder</strong>, <strong>Explore Marketplace</strong>, and <strong>Create skill</strong>. On VPS/web runtime, "Add folder" is replaced by <strong>Upload skill</strong> for zip archive uploads.
    </Card>
  </Columns>

  <Tip>
    Search matches the skill name, description, pack name, source label, trigger text, required system binaries, and required environment variable names. If you are looking for a skill that calls a specific API, search the env var name directly.
  </Tip>
</div>

<div className="w-full py-10 xc-rise">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">First flow</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">Find a skill, read it, enable it.</h2>

    <p className="text-base text-gray-600 dark:text-gray-400 max-w-3xl">
      Bundled skills ship with Actionist and are ready to use immediately. Once you find a skill, the enablement flow is the same for every group.
    </p>
  </div>

  <Steps>
    <Step title="Open the Skills page" icon="layout-list">
      Select **Skills** in the sidebar. The page loads with the Bundled group at the top. Type a keyword in the search box — for example `gmail` or `web`.
    </Step>

    <Step title="Open the Skill Drawer" icon="panel-right-open">
      Click any skill row to open the Skill Drawer. The drawer shows the skill's description, trigger pills (the phrases that tell an agent when to invoke this skill), a Frontmatter preview, and any required environment variables or system binaries.
    </Step>

    <Step title="Enable it globally" icon="toggle-right">
      Close the drawer and click the toggle switch on the skill row. This adds the skill to the global catalog — every agent can now see it. Bundled skills use an opt-in model: toggling off records the skill to a deny list; toggling back on removes it.
    </Step>

    <Step title="Wire it to an agent" icon="user-cog">
      Open the Agent Studio and switch to the **Skills** tab. Find the skill and flip its toggle. If a Key icon appears beside the toggle, click it to open the credential binding drawer and map the vault secret this skill needs.
    </Step>

    <Step title="Run it" icon="play">
      The next time the agent encounters a phrase that matches one of the skill's triggers, it loads the playbook automatically — exactly like the demo at the top of this page.
    </Step>
  </Steps>

  {/* TODO(image): skill-drawer-triggers — IMAGE SPEC: Skill Drawer open for the web-task bundled skill. Shows: the color-coded avatar circle at the top, the skill name and source badge, a trigger pills row with two or three example trigger phrases highlighted, the Frontmatter preview block (a reconstructed YAML block with name, description, version, and triggers fields visible), and any required env chips below. The drawer footer shows the 'View source' button. — replace this CSS mock with the real screenshot */}

  <div className="m2-mock-drawer" style={{maxWidth:'480px'}}>
    <div className="m2-drawer-header">
      <div className="m2-drawer-avatar">wt</div>

      <div className="m2-drawer-title-group">
        <div className="m2-drawer-skill-name">web-task</div>
        <div className="m2-drawer-source">Bundled</div>
      </div>
    </div>

    <div className="m2-drawer-section">
      <div className="m2-drawer-section-lbl">Triggers</div>
      <span className="m2-trigger-pill">when asked to open a URL or browse a website</span>
      <span className="m2-trigger-pill">when the user needs a web search</span>
      <span className="m2-trigger-pill">for any browser automation task</span>
    </div>

    <div className="m2-drawer-section">
      <div className="m2-drawer-section-lbl">Frontmatter preview</div>

      <pre className="m2-fm-block" style={{margin:0,whiteSpace:'pre-wrap'}}>
        {`name: web-task
                description: Browser automation and web search.
                version: 2.1.0
                triggers:
                - when asked to open a URL or browse a website
                - when the user needs a web search`}
      </pre>
    </div>

    <div className="m2-drawer-footer">
      <div className="m2-view-src-btn">View source</div>

      <div className="m2-enable-toggle">
        <div className="m2-toggle" style={{marginRight:4}} />

        Enabled
      </div>
    </div>
  </div>
</div>

<div className="w-full py-10 xc-rise" id="skill-creator">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">Authoring</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">Two ways to create a custom skill.</h2>

    <p className="text-base text-gray-600 dark:text-gray-400 max-w-3xl">
      The Skill Creator turns a plain-language description into a correctly structured SKILL.md in one conversation. Or author the file yourself if you want full control from the start.
    </p>
  </div>

  <Tabs>
    <Tab title="Skill Creator (recommended)" icon="wand-sparkles">
      <p className="text-base text-gray-600 dark:text-gray-400 mb-6">A conversational AI inside Actionist writes your skill's frontmatter, trigger list, and playbook body from a plain-language description. No YAML knowledge required. Here's a whole creation, start to finish:</p>

      <div className="mxp-window">
        <div className="mxp-window-bar"><span className="mxp-window-dot" /><span className="mxp-window-dot" /><span className="mxp-window-dot" /><span className="mxp-window-title">Skill Creator</span></div>

        <div className="mxp-window-body" style={{minHeight:'220px'}}>
          <div className="mxp-stream-line mxp-s1"><span className="mxp-stream-time">you</span><span className="mxp-stream-text">A skill that reads my unread Gmail, groups by sender, and ranks the urgent stuff first. Never mark anything as read.</span></div>
          <div className="mxp-s2" style={{margin:'8px 0'}}><span className="mxp-stream-event">thinking…</span></div>
          <div className="mxp-stream-line mxp-s3"><span className="mxp-stream-time">ai</span><span className="mxp-stream-text">Got it. Should urgency favor specific senders — your team, key clients?</span></div>
          <div className="mxp-stream-line mxp-s4"><span className="mxp-stream-time">you</span><span className="mxp-stream-text">Anything from legal@ or my starred contacts is urgent.</span></div>
          <div className="mxp-s5" style={{margin:'8px 0'}}><span className="mxp-stream-event">tool · create\_skill</span></div>
          <div className="mxp-stream-line mxp-s6"><span className="mxp-stream-time">ai</span><span className="mxp-stream-text">Skill created → <em>company/skills/email-summarise/SKILL.md</em></span></div>
          <div className="mxp-stream-line mxp-s7"><span className="mxp-stream-time">ai</span><span className="mxp-stream-text">Two triggers, Gmail read tools only, urgency rules encoded. <em>View in catalog</em> or create another.<span className="mxp-caret" /></span></div>
        </div>
      </div>

      <Steps>
        <Step title="Open the Skill Creator" icon="sparkles">
          From the Skills page, click **Create skill** in the page header. The modal opens with a welcome message: "Hi — I'm your Skill Creator. Skills are reusable playbooks your agents can draw on…"
        </Step>

        <Step title="Describe what you want" icon="message-square">
          Type your description and press Enter. Be specific about what the skill should do, what tools it needs, and what output it should produce. The AI may ask a few clarifying questions before building anything.
        </Step>

        <Step title="Review the result" icon="list-checks">
          The stage indicator shows "Creating your skill…" while the playbook is written. When it finishes you see the **Skill created** kicker, the path to your new `SKILL.md`, and two buttons: **View in catalog** and **Create another**.
        </Step>

        <Step title="Find it in the Custom group" icon="folder-open">
          Your new skill appears in the **Custom** group (labeled "Authored locally"). Enable it globally with the toggle, then wire it to any agent from the Agent Studio → Skills tab.
        </Step>
      </Steps>

      <Warning>
        If you close the Skill Creator mid-conversation, a "Leave without finishing?" overlay appears. Select **Discard** to abandon the draft or **Continue editing** to return. The skill is only saved when the success screen appears.
      </Warning>
    </Tab>

    <Tab title="Author by hand" icon="file-code">
      <p className="text-base text-gray-600 dark:text-gray-400 mb-6">Create a `SKILL.md` file inside any registered folder. Actionist indexes it on the next refresh. The file is plain Markdown with a YAML frontmatter block at the top.</p>

      <CodeGroup>
        ```yaml SKILL.md (minimal) theme={null}
        ---
        name: email-summarise
        description: Reads unread Gmail messages and returns a ranked summary grouped by sender.
        version: 1.0.0
        triggers:
          - when the user asks to summarize unread emails
          - when the user wants a morning email digest
        credentials:
          gmail_token:
            env: GMAIL_ACCESS_TOKEN
            provider: google
            kind: oauth
            displayName: Gmail OAuth token
            required: true
        allowed-tools:
          - read_file
          - mcp_gmail_list_messages
          - mcp_gmail_get_message
        ---

        # email-summarise

        Read unread Gmail messages. Group by sender. Return a ranked list with the most urgent threads first. Summarize each thread in one sentence. Never mark messages as read.

        ## Output format

        Return a markdown list. Each item: **[Sender Name]** — summary sentence. Prefix urgent items with `[URGENT]`.
        ```

        ```yaml SKILL.md (with fork context) theme={null}
        ---
        name: competitor-research
        description: Researches a named competitor and produces a structured brief.
        version: 1.0.0
        context: fork
        triggers:
          - when the user asks for a competitor brief
          - when the user wants to research a company
        arguments:
          competitor_name:
            description: The company to research
            required: true
        ---

        # competitor-research

        Research {{competitor_name}}. Gather: company overview, recent news, product positioning, pricing signals, and known customer segments. Return a structured brief with one-line summaries under each heading.
        ```
      </CodeGroup>

      <Info>
        Place your `SKILL.md` inside any folder you have registered via **Add folder** on the Skills page. Actionist scans the folder tree up to 10 levels deep. Use **Refresh** in the header to pick up changes immediately.
      </Info>
    </Tab>
  </Tabs>
</div>

<div className="w-full py-10 xc-rise">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">Reference</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">Frontmatter, field by field.</h2>

    <p className="text-base text-gray-600 dark:text-gray-400 max-w-3xl">
      The anatomy explorer above shows where each field lives — here is the full detail for each one.
    </p>
  </div>

  <AccordionGroup>
    <Accordion title="name and description" icon="tag" defaultOpen={true}>
      Both fields are required. Without them, the skill fails validation and appears as an invalid badge on its folder in the side pane.

      ```yaml theme={null}
      name: email-summarise
      description: Reads unread Gmail messages and returns a ranked summary grouped by sender.
      ```

      `name` becomes the skill's catalog slug. Use lowercase letters, numbers, and hyphens. Include a namespace prefix if you manage multiple skills from the same domain — `acme-gmail-summarise`, not `gmail`.
    </Accordion>

    <Accordion title="triggers" icon="zap">
      A list of natural-language phrases that tell an agent when to invoke this skill. Without triggers, the agent must guess — leading to false positives or missed invocations.

      ```yaml theme={null}
      triggers:
        - when the user asks to summarize unread emails
        - when the user wants a morning email digest
        - on email triage requests
      ```

      Make triggers concrete and distinct. "when the user asks to summarize unread emails" is a strong trigger. "for email tasks" is too broad.

      <Tip>Add at least two triggers to every custom skill. The agent drawer shows a warning for skills with none.</Tip>
    </Accordion>

    <Accordion title="credentials" icon="key">
      Declares the API credentials this skill needs. Actionist resolves them from your vault at runtime — no keys are stored in the SKILL.md body.

      ```yaml theme={null}
      credentials:
        gmail_token:
          env: GMAIL_ACCESS_TOKEN
          provider: google
          kind: oauth
          displayName: Gmail OAuth token
          required: true
      ```

      Each entry maps a slot name to a vault key (`env: KEY_NAME`). The `provider`, `kind`, `displayName`, and `required` fields are optional but help the binding drawer surface the right vault entry.
    </Accordion>

    <Accordion title="context" icon="git-branch">
      Controls how the skill runs relative to the current conversation.

      | Value              | Behavior                                                                                                                            |
      | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
      | `inline` (default) | Runs inside the current conversation. Lightweight; shares the parent's token budget.                                                |
      | `fork`             | Spawns a sub-agent with a fresh context budget. Useful for long-running tasks whose output would crowd out the parent conversation. |

      Use `inline` for most skills. Reserve `fork` for tasks that produce large output or run long enough to exhaust the parent's context window.
    </Accordion>

    <Accordion title="allowed-tools" icon="wrench">
      An explicit list of tools this skill is permitted to call. Restricts what the agent can do while executing this skill.

      ```yaml theme={null}
      allowed-tools:
        - read_file
        - mcp_gmail_list_messages
        - mcp_gmail_get_message
      ```

      Omitting this field allows any tool the agent already has access to. Specifying it limits the blast radius — an email-reading skill that cannot write files or run terminal commands cannot cause unexpected side effects.
    </Accordion>

    <Accordion title="arguments" icon="list">
      Named variables the agent passes into the skill at invocation time. Useful for skills that handle a class of tasks where one input changes.

      ```yaml theme={null}
      arguments:
        competitor_name:
          description: The company name to research
          required: true
        depth:
          description: How deep to go — 'brief' or 'full'
          required: false
      ```

      Reference arguments in the skill body as `{{argument_name}}`.
    </Accordion>
  </AccordionGroup>
</div>

<hr className="xc-divider" />

<div className="w-full py-10 xc-rise">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">Credentials</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">One-time setup, zero per-run prompts.</h2>

    <p className="text-base text-gray-600 dark:text-gray-400 max-w-3xl">
      Skills that need API keys declare slots in frontmatter. You bind those slots to vault entries once, and every run resolves them silently:
    </p>
  </div>

  <div className="mxp-pipe">
    <div className="mxp-pipe-node"><strong>Declare</strong><span>The SKILL.md names a slot — `env: STRIPE_SECRET_KEY` — never the value.</span></div>

    <div className="mxp-pipe-link" />

    <div className="mxp-pipe-node"><strong>Vault</strong><span>The real key lives encrypted in Settings → Credentials Vault.</span></div>

    <div className="mxp-pipe-link d2" />

    <div className="mxp-pipe-node"><strong>Bind</strong><span>Per agent, the Key icon on the Skills tab maps slot → vault entry.</span></div>

    <div className="mxp-pipe-link d3" />

    <div className="mxp-pipe-node"><strong>Resolve</strong><span>At runtime the secret is injected silently. Rotate in the vault; every skill updates.</span></div>
  </div>

  <Warning>
    Never paste API keys or tokens into the skill body or into agent instructions. The SKILL.md body is readable by anyone with workspace access. Declare secrets in the `credentials:` frontmatter block and bind them from the vault.
  </Warning>

  <Steps>
    <Step title="Declare in frontmatter" icon="file-code">
      In your `SKILL.md`, add a `credentials:` block naming every secret the skill needs. This is a slot declaration — not the value itself.

      ```yaml theme={null}
      credentials:
        stripe_key:
          env: STRIPE_SECRET_KEY
          displayName: Stripe Secret Key
          required: true
      ```
    </Step>

    <Step title="Store the key in the vault" icon="lock">
      Go to **Settings → Credentials Vault** and add the key under the same variable name (`STRIPE_SECRET_KEY`). The vault encrypts values at rest.

      <Card title="Credentials vault" icon="lock" href="/Folders/credentials" horizontal>
        How to add, rotate, and scope API keys in the vault.
      </Card>
    </Step>

    <Step title="Bind per agent" icon="user-cog">
      In the Agent Studio → **Skills** tab, find the skill. If it declares credentials, a Key icon appears beside the toggle. Click it to open the binding drawer and confirm which vault entry maps to each slot.

      {/* TODO(image): agent-skills-tab-binding — IMAGE SPEC: Agent Studio Skills tab showing a vertical list of skill cards with toggle switches. One skill row (e.g. 'gmail-summarise') has its toggle flipped on and a Key icon button to the right of the toggle. The cursor hovers over the Key icon. In the background, the edge of the credential binding drawer is partially visible, showing a slot-to-vault-key mapping form with a dropdown for selecting the vault entry. — replace this CSS mock with the real screenshot */}

      <div className="m2-mock-agent-skills">
        <div className="m2-agent-tab-bar">
          <span className="m2-tab-item">Instructions</span>
          <span className="m2-tab-item is-active">Skills</span>
          <span className="m2-tab-item">Tools</span>
          <span className="m2-tab-item">Memory</span>
        </div>

        <div className="relative overflow-hidden">
          <div className="m2-agent-skill-list">
            <div className="m2-agent-skill-row">
              <div className="m2-agent-skill-info">
                <div className="m2-agent-skill-name">web-task</div>
                <div className="m2-agent-skill-desc">Browser automation and web search</div>
              </div>

              <div className="m2-toggle" />
            </div>

            <div className="m2-agent-skill-row is-enabled">
              <div className="m2-agent-skill-info">
                <div className="m2-agent-skill-name">gmail-summarise</div>
                <div className="m2-agent-skill-desc">Reads unread Gmail and returns a ranked summary</div>
              </div>

              <div className="m2-toggle" style={{marginRight:8}} />

              <div className="m2-key-icon">
                <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.2" strokeLinecap="round" strokeLinejoin="round">
                  <circle cx="8" cy="15" r="4" />

                  <path d="m21 3-7.5 7.5" />

                  <path d="m15 3 6 6" />
                </svg>
              </div>
            </div>

            <div className="m2-agent-skill-row">
              <div className="m2-agent-skill-info">
                <div className="m2-agent-skill-name">competitor-research</div>
                <div className="m2-agent-skill-desc">Researches a named competitor and produces a brief</div>
              </div>

              <div className="m2-toggle is-off" />
            </div>
          </div>

          <div className="m2-drawer-peek" />
        </div>
      </div>
    </Step>
  </Steps>
</div>

<div className="w-full py-10 xc-rise">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">Marketplace</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">A growing library you don't have to maintain.</h2>

    <p className="text-base text-gray-600 dark:text-gray-400 max-w-3xl">
      The Actionist marketplace hosts community and curated skills. Install once, receive automatic updates when new versions are approved, and uninstall cleanly when you are done.
    </p>
  </div>

  <Steps>
    <Step title="Open the marketplace" icon="store">
      On the Skills page, click **Explore Marketplace** in the header. The marketplace opens with a trending strip, category tiles, and a paginated skill grid (50 per page). Filter by category, tag, or view (All / Installed / Updates available).
    </Step>

    <Step title="Find and install a skill" icon="download">
      Browse or search for a skill. Click **Install** on its card. The skill installs to your workspace and appears in the **From the Marketplace** group on the Skills page.
    </Step>

    <Step title="Enable it per agent" icon="toggle-right">
      Newly installed marketplace skills are disabled by default. Open the Agent Studio → **Skills** tab, find the skill, and flip its toggle on.
    </Step>

    <Step title="Bind credentials if needed" icon="key">
      If the skill declares credentials, a Key icon appears beside the toggle. Click it to open the binding drawer and wire the vault entry.
    </Step>

    <Step title="Keep it current" icon="refresh-cw">
      When an update is available, the skill's drawer shows an update button. To remove the skill entirely, open the drawer and click **Uninstall** — this removes the files and ends the subscription.
    </Step>
  </Steps>

  <Note>
    Marketplace install requires the desktop app. On web runtime, the Install button is disabled with a desktop-only overlay. Install from the desktop and the skill will be available to your workspace from there.
  </Note>
</div>

<div className="w-full py-8 xc-rise">
  <AccordionGroup>
    <Accordion title="VPS: upload a skill archive" icon="server">
      On the VPS/web runtime, the page title shows **VPS Skills** and the "Add folder" header button becomes **Upload skill**. Use this to deploy a zip archive directly to your paired server.

      <Steps>
        <Step title="Prepare the archive" icon="file-archive">
          Zip your skill folder. The archive must be no larger than 50 MB and must contain a `SKILL.md` at the root or inside a subfolder.
        </Step>

        <Step title="Open the upload dialog" icon="upload">
          Click **Upload skill** in the header. The "Upload skill archive" dialog opens. Click to select your `.zip` file.
        </Step>

        <Step title="Set the slug" icon="tag">
          Enter or confirm the auto-derived **Skill slug** — lowercase letters, numbers, dashes, and underscores, starting with a letter or digit. Check **Replace existing skill of the same slug** to overwrite a prior version.
        </Step>

        <Step title="Upload and confirm" icon="check">
          Click **Upload**. The archive is sent to the paired VPS, extracted, and installed. A success toast confirms the skill was queued.
        </Step>
      </Steps>

      <Info>
        The folder for skills installed via the marketplace is protected — the trash icon in the Folders sidebar is disabled for these directories. To remove them, use **Uninstall** from the skill's drawer.
      </Info>
    </Accordion>
  </AccordionGroup>
</div>

<div className="w-full py-10 xc-rise">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">Publishing</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">Share your skill with the community.</h2>

    <p className="text-base text-gray-600 dark:text-gray-400 max-w-3xl">
      Custom skills you have tested and refined can be submitted to the Actionist marketplace for review. Once published, other users can install and benefit from your work.
    </p>
  </div>

  <Steps>
    <Step title="Open the Skill Drawer" icon="panel-right-open">
      On the Skills page, find your custom skill in the **Custom** group. Click the row to open the Skill Drawer.
    </Step>

    <Step title="Submit for review" icon="send">
      In the drawer footer, click **Publish to Marketplace**. Review the listing details in the dialog that opens, then submit. The skill row now shows a **Pending review** badge.
    </Step>

    <Step title="Wait for the decision" icon="clock">
      While review is in progress, the publish button is hidden. Once the review completes, the badge updates:

      <div className="flex flex-wrap gap-2 mt-3">
        <Badge color="yellow" size="md" shape="pill">Pending review</Badge>
        <Badge color="green" size="md" shape="pill">Published</Badge>
        <Badge color="red" size="md" shape="pill">Rejected</Badge>
      </div>

      If rejected, the drawer shows the reviewer's reason so you can address it.
    </Step>

    <Step title="Ship updates" icon="refresh-cw">
      After a decision — approval or rejection — the publish button reappears as **New version**. Click it to submit an updated version for review.
    </Step>
  </Steps>

  <Warning>
    Only publish skills that contain no internal business data, customer records, or embedded credentials. The publish flow strips token values but does not strip content from the skill body. Skills containing private process details should stay private.
  </Warning>
</div>

<hr className="xc-divider" />

<div className="w-full py-10 xc-rise">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">Best practices</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">What experienced skill authors do differently.</h2>
  </div>

  <AccordionGroup>
    <Accordion title="Add at least two triggers to every custom skill" icon="zap">
      Without trigger phrases, the agent must guess when to invoke the skill — leading to false positives (skill called when you did not want it) and missed invocations (skill not called when you did). Make triggers concrete and distinct. The Skill Drawer shows a warning badge for skills with no triggers — treat triggers as a required field.
    </Accordion>

    <Accordion title="Inspect folder health badges before enabling skills" icon="folder-check">
      A red "N invalid" badge on a folder in the side pane means some SKILL.md files were rejected during indexing. Hover the badge to see up to three filenames and their rejection reasons. The most common cause is missing `name:` or `description:` fields — both must appear inside a `---` YAML block at the very top of the file.
    </Accordion>

    <Accordion title="Name custom skills with a prefix to avoid shadowing" icon="tag">
      Source precedence means a custom skill named `gmail` silently shadows the bundled `gws-gmail` skill. No error appears — the wrong skill just runs. Use a namespace prefix: `acme-gmail-summarise`, `myteam-daily-report`.
    </Accordion>

    <Accordion title="Prefer inline context; use fork only for long-running work" icon="git-branch">
      `context: inline` (the default) runs the skill inside the current conversation — lightweight and immediate. `context: fork` spawns a sub-agent with a fresh context budget, which isolates large output from the parent conversation but costs an additional model turn. Only use `fork` for skills that generate enough output to crowd out the parent conversation, such as deep research or large-document analysis.
    </Accordion>

    <Accordion title="After installing a marketplace skill, enable it per agent" icon="toggle-right">
      New marketplace installs land in a blocked state by default. Enabling the skill globally on the Skills page makes it visible in the catalog, but it still will not run for any agent until you also enable its toggle in that agent's **Skills** tab. If a newly installed skill is not being invoked, check the agent's Skills tab first.
    </Accordion>
  </AccordionGroup>
</div>

<div className="w-full py-10 xc-rise">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">Limits</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">Limits to know.</h2>
  </div>

  <div className="mxs-limits">
    <div className="mxs-limit"><b className="xc-count" style={{"--xc-to":"256"}} data-suffix=" KB"><span className="xc-real">256 KB</span></b><span>max SKILL.md file size</span></div>
    <div className="mxs-limit"><b className="xc-count" style={{"--xc-to":"128"}} data-suffix=" KB"><span className="xc-real">128 KB</span></b><span>max resource file size</span></div>
    <div className="mxs-limit"><b className="xc-count" style={{"--xc-to":"500"}} data-suffix=""><span className="xc-real">500</span></b><span>max skills per source root</span></div>
    <div className="mxs-limit"><b className="xc-count" style={{"--xc-to":"10"}} data-suffix=""><span className="xc-real">10</span></b><span>max folder nesting levels</span></div>
    <div className="mxs-limit"><b className="xc-count" style={{"--xc-to":"50"}} data-suffix=" MB"><span className="xc-real">50 MB</span></b><span>max VPS zip upload</span></div>
    <div className="mxs-limit"><b>0</b><span>symlinks allowed — rejected unconditionally</span></div>
  </div>
</div>

<div className="w-full py-10 xc-rise">
  <div className="actionist-cta-panel xc-border">
    <div className="relative z-10 flex flex-col items-center gap-5 max-w-2xl mx-auto">
      <span className="actionist-eyebrow">Five minutes</span>

      <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-white leading-tight">
        Author your first skill today.
      </h2>

      <p className="text-base md:text-lg text-white/85">
        Click <strong>Create skill</strong> on the Skills page. Describe the task in plain language. Actionist writes the playbook — you enable it on every agent that needs it.
      </p>

      <div className="flex flex-wrap items-center justify-center gap-3 pt-2">
        <a className="actionist-cta-btn-primary" href="https://app.actionist.ai" target="_blank" rel="noreferrer">
          Open the Dashboard

          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.2" strokeLinecap="round" strokeLinejoin="round">
            <path d="M5 12h14" />

            <path d="m12 5 7 7-7 7" />
          </svg>
        </a>

        <a className="actionist-cta-btn-secondary" href="/Folders/marketplace">
          Browse the marketplace
        </a>
      </div>
    </div>
  </div>
</div>

<div className="w-full pt-2 pb-6 xc-rise">
  <p className="actionist-trust-line">
    Skills encode tested procedures, not guesses.<br />
    Vault-backed credentials · Per-agent scoping · Marketplace reviews.
  </p>
</div>

<div className="w-full pb-16 xc-rise">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">Keep going</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">Next steps.</h2>
  </div>

  <Columns cols={4}>
    <Card title="Agents" icon="users" href="/Folders/agents">
      Enable skills per agent from the Studio Skills tab, and configure credential bindings for each.
    </Card>

    <Card title="Credentials" icon="lock" href="/Folders/credentials">
      Store and rotate the API keys that skills resolve from the vault at runtime.
    </Card>

    <Card title="Marketplace" icon="store" href="/Folders/marketplace">
      Browse community skills, receive automatic updates, and publish your own.
    </Card>

    <Card title="Cloud and VPS" icon="cloud" href="/Folders/cloud">
      Deploy skill archives to a paired server and run agents without the desktop app open.
    </Card>
  </Columns>
</div>
