Doc skill

src/components/Layout.jsx

@@ -166,13 +166,25 @@ export function Layout({ children, page }) {
                     </div>
                     <div className="flex flex-col items-end gap-1.5">
                       <AskAIButton pathname={page.pathname} />
-                      {page.product?.skill && <SkillBadge />}
+                      {page.agentSkill && <SkillBadge href={page.agentSkill} />}
                       {page.cli && <CLIBadge cliPath={page.cli} />}
                     </div>
                   </div>
                 </header>
               )}
-              <Prose className="break-words">{children}</Prose>
+              <Prose className="break-words">
+                {page.agentSkill && (
+                  <div className="not-prose mb-6 rounded-md border border-border bg-muted/50 px-4 py-3 text-sm text-muted-foreground">
+                    <strong className="font-semibold text-foreground">Required for AI agents:</strong>{' '}
+                    Do not answer from this page alone. First read the{' '}
+                    <Link href={page.agentSkill} className="text-primary underline underline-offset-2 hover:text-primary/80">
+                      skill file for this page
+                    </Link>
+                    {' '}— it contains required task routing, CLI/SDK workflow, and execution guidance. Return here afterwards if needed.
+                  </div>
+                )}
+                {children}
+              </Prose>
             </article>
             {!page.product.isFallbackProduct && (page.activeSection?.previousPage || page.activeSection?.nextPage) && (
             <dl className="mt-12 flex border-t border-border pt-6">

src/components/SkillBadge.jsx

@@ -51,21 +51,19 @@ function CodeRow({ label, command }) {
   )
 }
 
-export function SkillBadge() {
+export function SkillBadge({ href }) {
   const [open, setOpen] = useState(false)
   const ref = useClickOutside(() => setOpen(false))
 
   const gitClone = `git clone ${SKILL_REPO}`
   const npxAdd = `npx skills add metaplex-foundation/skill`
 
   return (
-    <div ref={ref} className="relative flex-shrink-0">
-      <button
-        type="button"
-        onClick={() => setOpen((v) => !v)}
-        className="inline-flex items-center gap-1.5 rounded-md border border-border bg-background px-2.5 py-1 text-xs font-medium text-muted-foreground shadow-sm transition-colors hover:bg-muted hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-ring"
-        aria-haspopup="true"
-        aria-expanded={open}
+    <div ref={ref} className="relative flex flex-shrink-0 items-center">
+      <Link
+        href={href}
+        className="inline-flex h-7 items-center gap-1.5 rounded-l-md border border-r-0 border-border bg-background px-2.5 text-xs font-medium text-muted-foreground shadow-sm transition-colors hover:bg-muted hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-ring"
+        title="Open the Markdown agent skill file for this page"
       >
         <svg
           viewBox="0 0 24 24"
@@ -76,38 +74,58 @@ export function SkillBadge() {
           <path d="M11.9842 0C11.2889 6.28058 6.28058 11.289 0 11.9842C6.28058 12.6795 11.289 17.6879 11.9842 23.9685C12.6795 17.688 17.6879 12.6795 23.9685 11.9842C17.688 11.289 12.6795 6.28058 11.9842 0Z" />
         </svg>
         Skill file available
-      </button>
+      </Link>
 
-      {open && (
-        <div className="absolute right-0 z-50 mt-1.5 w-96 origin-top-right rounded-md border border-border bg-background p-3 shadow-2xl ring-1 ring-white/10 dark:ring-white/10">
-          <p className="mb-2 text-xs font-medium text-foreground">Metaplex Skill File</p>
-          <p className="mb-3 text-xs text-muted-foreground">
-            This product is part of the{' '}
-            <a
-              href={SKILL_REPO}
-              target="_blank"
-              rel="noopener noreferrer"
-              className="text-primary underline underline-offset-2 hover:text-primary/80"
-            >
-              Metaplex Skill package
-            </a>
-            {' '}— a collection of skill files that give AI coding agents full knowledge of Metaplex programs, SDKs, and CLI tools.
-            {' '}Learn more in the{' '}
-            <Link
-              href="/agents/skill"
-              className="text-primary underline underline-offset-2 hover:text-primary/80"
-              onClick={() => setOpen(false)}
-            >
-              Skill docs
-            </Link>
-            .
-          </p>
-          <div className="space-y-2.5">
-            <CodeRow label="NPX Install" command={npxAdd} />
-            <CodeRow label="Git Clone Skill Repo" command={gitClone} />
+      <div className="relative">
+        <button
+          type="button"
+          onClick={() => setOpen((v) => !v)}
+          className="inline-flex h-7 items-center rounded-r-md border border-border bg-background px-1.5 text-xs font-medium text-muted-foreground shadow-sm transition-colors hover:bg-muted hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-ring"
+          aria-haspopup="true"
+          aria-expanded={open}
+          aria-label="Open skill package install options"
+        >
+          <svg
+            viewBox="0 0 20 20"
+            className="h-3 w-3"
+            fill="currentColor"
+            aria-hidden="true"
+          >
+            <path fillRule="evenodd" d="M5.22 8.22a.75.75 0 0 1 1.06 0L10 11.94l3.72-3.72a.75.75 0 1 1 1.06 1.06l-4.25 4.25a.75.75 0 0 1-1.06 0L5.22 9.28a.75.75 0 0 1 0-1.06Z" clipRule="evenodd" />
+          </svg>
+        </button>
+
+        {open && (
+          <div className="absolute right-0 z-50 mt-1.5 w-96 origin-top-right rounded-md border border-border bg-background p-3 shadow-2xl ring-1 ring-white/10 dark:ring-white/10">
+            <p className="mb-2 text-xs font-medium text-foreground">Metaplex Skill File</p>
+            <p className="mb-3 text-xs text-muted-foreground">
+              This product is part of the{' '}
+              <a
+                href={SKILL_REPO}
+                target="_blank"
+                rel="noopener noreferrer"
+                className="text-primary underline underline-offset-2 hover:text-primary/80"
+              >
+                Metaplex Skill package
+              </a>
+              {' '}— a collection of skill files that give AI coding agents full knowledge of Metaplex programs, SDKs, and CLI tools.
+              {' '}Learn more in the{' '}
+              <Link
+                href="/agents/skill"
+                className="text-primary underline underline-offset-2 hover:text-primary/80"
+                onClick={() => setOpen(false)}
+              >
+                Skill docs
+              </Link>
+              .
+            </p>
+            <div className="space-y-2.5">
+              <CodeRow label="NPX Install" command={npxAdd} />
+              <CodeRow label="Git Clone Skill Repo" command={gitClone} />
+            </div>
           </div>
-        </div>
-      )}
+        )}
+      </div>
     </div>
   )
 }

src/pages/en/agents/create-agent-token.md

@@ -2,6 +2,7 @@
 title: Create an Agent Token
 metaTitle: Create an Agent Token with Metaplex Genesis | Metaplex Agents
 description: How to launch a bonding curve token on behalf of a Metaplex agent using the Genesis SDK — including automatic creator fee routing, first buy, devnet testing, and error handling.
+agentSkill: /agents.md
 keywords:
   - agent token
   - token launch

src/pages/en/agents/index.md

@@ -2,6 +2,7 @@
 title: Agent Kit
 metaTitle: Create & Run Agents on Solana | Agent Registry | Metaplex
 description: Create, register, and run autonomous agents on Solana. Use the Metaplex Agent skills and agent registry to manage your autonomous agents.
+agentSkill: /agents.md
 tableOfContents: false
 keywords:
   - Solana agents

src/pages/en/agents/mint-agent.md

@@ -2,6 +2,7 @@
 title: Mint an Agent
 metaTitle: Mint an Agent | Metaplex
 description: Create an onchain AI agent in a single transaction using the Metaplex API and the mpl-agent-registry SDK. The hosted API stores agent metadata and returns an unsigned transaction you sign and submit.
+agentSkill: /agents.md
 keywords:
   - mint agent
   - agent registration

src/pages/en/agents/register-agent.md

@@ -2,6 +2,7 @@
 title: Register an Agent
 metaTitle: Register an Agent on Solana | Metaplex 014 Agent Registry
 description: Register an agent identity on the Metaplex 014 agent registry by binding an identity record to an MPL Core asset.
+agentSkill: /agents.md
 keywords:
   - register agent
   - agent identity

src/pages/en/agents/run-agent.md

@@ -2,6 +2,7 @@
 title: Read Agent Data
 metaTitle: Read Agent Data on Solana | Metaplex Agent Registry
 description: Verify agent registration and read agent identity data on Solana.
+agentSkill: /agents.md
 keywords:
   - read agent data
   - agent identity

src/pages/en/agents/run-an-agent.md

@@ -2,6 +2,7 @@
 title: Run an Agent
 metaTitle: Run an Agent on Solana | Metaplex Agent Registry
 description: Set up an executive profile and delegate execution to run an autonomous agent on Solana.
+agentSkill: /agents.md
 keywords:
   - run agent
   - executive profile

src/pages/en/agents/what-is-an-agent.md

@@ -2,6 +2,7 @@
 title: What Is an Agent?
 metaTitle: What Is an Agent on Solana? | Metaplex Agent Registry
 description: Autonomous agents on Solana are MPL Core assets with built-in wallets and on-chain identity records. Learn how agent identity, wallets, and execution delegation work.
+agentSkill: /agents.md
 keywords:
   - Solana agents
   - autonomous agents

src/pages/en/smart-contracts/core/burn.md

@@ -20,6 +20,7 @@ programmingLanguage:
   - TypeScript
   - Rust
 cli: /dev-tools/cli/core/burn-asset
+agentSkill: /smart-contracts/core.md
 howToSteps:
   - Install the SDK with npm install @metaplex-foundation/mpl-core
   - Fetch the Asset to verify ownership

src/pages/en/smart-contracts/core/collections.md

@@ -24,6 +24,7 @@ faqs:
     a: Yes, use the update instruction to change the Asset's collection. You need the appropriate authority on both the Asset and Collection.
   - q: What happens if I delete a Collection?
     a: Collections cannot be deleted while they contain Assets. Remove all Assets first, then the Collection account can be closed.
+agentSkill: /smart-contracts/core.md
 ---
 
 ## Summary

src/pages/en/smart-contracts/core/collections/create.md

@@ -18,6 +18,7 @@ programmingLanguage:
   - TypeScript
   - Rust
 cli: /dev-tools/cli/core/create-collection
+agentSkill: /smart-contracts/core.md
 howToSteps:
   - Install the mpl-core SDK with npm install @metaplex-foundation/mpl-core @metaplex-foundation/umi
   - Upload collection metadata JSON to get a URI

src/pages/en/smart-contracts/core/collections/fetch.md

@@ -18,6 +18,7 @@ programmingLanguage:
   - TypeScript
   - Rust
 cli: /dev-tools/cli/core/fetch
+agentSkill: /smart-contracts/core.md
 ---
 
 `fetchCollection` retrieves a [Core Collection](/smart-contracts/core/collections) account from Solana by its address and deserialises it into a typed object. {% .lead %}

src/pages/en/smart-contracts/core/collections/update.md

@@ -26,6 +26,7 @@ howToTools:
   - Node.js
   - Umi framework
   - mpl-core SDK
+agentSkill: /smart-contracts/core.md
 ---
 
 `updateCollection` and `updateCollectionPlugin` modify an existing [Core Collection's](/smart-contracts/core/collections) metadata and plugin configuration. {% .lead %}

src/pages/en/smart-contracts/core/create-asset.md

@@ -19,6 +19,7 @@ programmingLanguage:
   - TypeScript
   - Rust
 cli: /dev-tools/cli/core/create-asset
+agentSkill: /smart-contracts/core.md
 howToSteps:
   - Install SDK with npm install @metaplex-foundation/mpl-core @metaplex-foundation/umi
   - Upload metadata JSON to Arweave or IPFS to get a URI

src/pages/en/smart-contracts/core/deserialization.md

@@ -17,6 +17,7 @@ programmingLanguage:
   - JavaScript
   - TypeScript
   - Rust
+agentSkill: /smart-contracts/core.md
 ---
 Digital assets on Core are composed of exactly **one onchain account** that contains both the base asset data and the plugin.
 That means that if we want to read that data we need to learn how to deserialize it.

src/pages/en/smart-contracts/core/ecosystem-support.md

@@ -13,6 +13,7 @@ about:
   - Wallet compatibility
   - Ecosystem integrations
 proficiencyLevel: Beginner
+agentSkill: /smart-contracts/core.md
 ---
 The table below includes the Core integration status of many of the major marketplaces, wallets, explorers, RPC providers, and other dapps across the ecosystem.
 Metaplex also offers a free, open-source UI for creating, transferring and viewing Core digital assets at [core.metaplex.com](https://core.metaplex.com/).

src/pages/en/smart-contracts/core/execute-asset-signing.md

@@ -17,6 +17,7 @@ programmingLanguage:
   - Rust
   - JavaScript
 cli: /dev-tools/cli/core/execute
+agentSkill: /smart-contracts/core.md
 ---
 The MPL Core Execute instruction introduces the concept of **Asset Signers** to
 MPL Core Assets.

src/pages/en/smart-contracts/core/external-plugins/adding-external-plugins.md

@@ -24,6 +24,7 @@ faqs:
     a: Yes. The Oracle account must exist before adding an Oracle plugin adapter.
   - q: What's the difference between adding at creation vs adding later?
     a: No functional difference. Adding at creation is more efficient (one transaction). Adding later requires a separate transaction.
+agentSkill: /smart-contracts/core.md
 ---
 This guide shows how to **add External Plugins** (Oracle, AppData) to Core Assets and Collections. Add at creation time or to existing Assets/Collections. {% .lead %}
 {% callout title="What You'll Learn" %}

src/pages/en/smart-contracts/core/external-plugins/app-data.md

@@ -28,6 +28,7 @@ faqs:
     a: Yes. JSON and MsgPack schemas are automatically deserialized and indexed. Binary is stored as base64.
   - q: What is LinkedAppData?
     a: LinkedAppData is added to a Collection and allows the Data Authority to write to any Asset in that Collection without adding AppData to each Asset individually.
+agentSkill: /smart-contracts/core.md
 ---
 The **AppData Plugin** provides secure, partitioned data storage on Core Assets. Third-party applications can store and read arbitrary data (JSON, MsgPack, or binary) with exclusive write access controlled by a Data Authority. {% .lead %}
 {% callout title="What You'll Learn" %}

src/pages/en/smart-contracts/core/external-plugins/oracle.md

@@ -28,6 +28,7 @@ faqs:
     a: Freeze Delegate is built-in and binary (frozen/unfrozen). Oracle allows custom logic - time-based, price-based, or any condition you implement.
   - q: Do I need to write a Solana program for Oracle?
     a: Yes. The Oracle account must be a Solana account with the correct structure. You can use Anchor or native Rust.
+agentSkill: /smart-contracts/core.md
 ---
 The **Oracle Plugin** connects Core Assets to external Oracle accounts for custom validation logic. Reject transfers, burns, or updates based on time, price, ownership, or any custom rule you implement. {% .lead %}
 {% callout title="What You'll Learn" %}

src/pages/en/smart-contracts/core/external-plugins/overview.md

@@ -28,6 +28,7 @@ faqs:
     a: Yes. You can add multiple Oracle or AppData plugins to a single Asset, each with different configurations and authorities.
   - q: Are External Plugins indexed by DAS?
     a: Yes. AppData with JSON or MsgPack schemas is automatically indexed by DAS for easy querying.
+agentSkill: /smart-contracts/core.md
 ---
 **External Plugins** connect Core Assets to external programs for advanced functionality. Use Oracle plugins for custom validation logic and AppData plugins for storing arbitrary data that third-party apps can read and write. {% .lead %}
 {% callout title="What You'll Learn" %}

src/pages/en/smart-contracts/core/external-plugins/removing-external-plugins.md

@@ -23,6 +23,7 @@ faqs:
     a: Yes. Read the AppData using fetchAsset() before removing the plugin if you need to preserve the data.
   - q: What happens to the rent?
     a: The rent from the plugin adapter is recovered and returned to the transaction payer.
+agentSkill: /smart-contracts/core.md
 ---
 This guide shows how to **remove External Plugins** from Core Assets and Collections. Remove Oracle or AppData plugins when they're no longer needed. {% .lead %}
 {% callout title="What You'll Learn" %}

src/pages/en/smart-contracts/core/faq.md

@@ -25,6 +25,7 @@ faqs:
     a: Core is cheaper (~80% lower costs), requires fewer accounts (1 vs 3+), uses less compute units, and has a flexible plugin system instead of scattered delegates.
   - q: Does Core Support Editions?
     a: Yes, using the Edition and Master Edition plugins. See the Print Editions guide for details.
+agentSkill: /smart-contracts/core.md
 ---
 ## Why does the Core Asset and Collection accounts have both onchain and off-chain data?
 The Core Asset and Collection accounts both contain onchain data, yet both also include a `URI` attribute that points to an off-chain JSON file which provides additional data. Why is that? Can't we just store everything onchain? Well, there are several issues with storing data onchain:

src/pages/en/smart-contracts/core/fetch.md

@@ -19,6 +19,7 @@ programmingLanguage:
   - TypeScript
   - Rust
 cli: /dev-tools/cli/core/fetch
+agentSkill: /smart-contracts/core.md
 howToSteps:
   - Install SDK with npm install @metaplex-foundation/mpl-core @metaplex-foundation/umi
   - Configure Umi with your RPC endpoint

src/pages/en/smart-contracts/core/guides/anchor/anchor-staking-example.md

@@ -24,6 +24,7 @@ howToTools:
   - Anchor framework
   - mpl-core Rust crate
   - Solana CLI
+agentSkill: /smart-contracts/core.md
 ---
 This developer guide demonstrates how to create a staking program for your collection using Anchor leveraging the `Attribute` and `Freeze Delegate` plugins. This approach uses a smart contract for all the logic behind staking like time calculation and management of the state of the asset (staking/unstaking), but the data will not be saved in a PDA, like the standard before Core, but it will be saved on the asset itself. {% .lead %}
 ## Starting off: Understanding the Logic behind the program

src/pages/en/smart-contracts/core/guides/anchor/how-to-create-a-core-collection-with-anchor.md

@@ -25,6 +25,7 @@ howToTools:
   - Anchor framework
   - mpl-core Rust crate
   - Solana CLI
+agentSkill: /smart-contracts/core.md
 ---
 This guide will demonstrate the use of the `mpl-core` Rust SDK crate to create a **Core NFT Collection** via CPI using the **Anchor** framework in a **Solana** program.
 {% callout title="What is Core?" %}

src/pages/en/smart-contracts/core/guides/anchor/how-to-create-a-core-nft-asset-with-anchor.md

@@ -25,6 +25,7 @@ howToTools:
   - Anchor framework
   - mpl-core Rust crate
   - Solana CLI
+agentSkill: /smart-contracts/core.md
 ---
 This guide will demonstrate the use of the `mpl-core` Rust SDK crate to create a **Core NFT Asset** via CPI using the **Anchor** framework in a **Solana** program.
 {% callout title="What is Core?" %}

src/pages/en/smart-contracts/core/guides/create-soulbound-nft-asset.md

@@ -25,6 +25,7 @@ howToTools:
   - Node.js
   - Umi framework
   - mpl-core SDK
+agentSkill: /smart-contracts/core.md
 ---
 Soulbound NFTs are non-fungible tokens that are permanently bound to a specific wallet address and cannot be transferred to another owner. They are useful for representing achievements, credentials, or memberships that should remain tied to a specific identity.  {% .lead %}
 ## Overview

src/pages/en/smart-contracts/core/guides/immutability.md

@@ -17,6 +17,7 @@ programmingLanguage:
   - JavaScript
   - TypeScript
   - Rust
+agentSkill: /smart-contracts/core.md
 ---
 ## What is Immutability?
 In the general context of Digital Assets immutability is often used referring to the metadata of a Token or NFT. In the past this was asked for by communities to make sure that a purchased Asset can not be changed in the future. With the additional functionality MPL Core offers it can make sense to add additional immutability features. This guide aims to provide information about those different options and how they can be used to tailor the immutability of a digital Asset to the needs of a project.

src/pages/en/smart-contracts/core/guides/index.md

@@ -13,6 +13,7 @@ about:
   - Implementation guides
   - Code examples
 proficiencyLevel: Intermediate
+agentSkill: /smart-contracts/core.md
 ---
 The following Guides for MPL Core are currently available:
 {% quick-links %}

src/pages/en/smart-contracts/core/guides/javascript/how-to-create-a-core-collection-with-javascript.md

@@ -28,6 +28,7 @@ howToTools:
   - Umi framework
   - mpl-core SDK
   - Irys or IPFS for storage
+agentSkill: /smart-contracts/core.md
 ---
 This guide will demonstrate the use of the  `@metaplex-foundation/mpl-core` Javascript sdk package to create a **Core Collection** using the Metaplex Core onchain program.
 {% callout title="What is Core?" %}

src/pages/en/smart-contracts/core/guides/javascript/how-to-create-a-core-nft-asset-with-javascript.md

@@ -28,6 +28,7 @@ howToTools:
   - Umi framework
   - mpl-core SDK
   - Irys or IPFS for storage
+agentSkill: /smart-contracts/core.md
 ---
 This guide will demonstrate the use of the  `@metaplex-foundation/mpl-core` Javascript SDK package to create a **Core NFT Asset** using the Metaplex Core onchain program.
 {% callout title="What is Core?" %}