feat(ai): agent skill

docs.json

@@ -65,6 +65,12 @@
             ]
           },
           "ecosystem/sdks",
+          {
+            "group": "AI",
+            "pages": [
+              "ecosystem/ai/agent-skill"
+            ]
+          },
           {
             "group": "APIs",
             "pages": [

ecosystem/ai/agent-skill.mdx

@@ -0,0 +1,43 @@
+---
+title: "Agent skill"
+---
+
+## Objective
+
+Install the `ton-blockchain` agent Skill so your AI coding agent follows a docs-first workflow when you work on TON-related tasks.
+
+## About Agent Skills
+
+Agent Skills are an open format for packaging instructions, scripts, and resources that skills-compatible agents can discover and apply.
+
+See [https://agentskills.io/home](https://agentskills.io/home) for an overview and links to the specification.
+
+## Prerequisites
+
+- The agent you use supports “Skills” (a `SKILL.md` file with frontmatter)
+
+## Install in Codex
+
+Run this in Codex:
+
+```
+$skill-installer --url https://github.com/ton-org/docs/tree/main/skills/ton-blockchain
+```
+
+Then restart Codex to pick up the new skill.
+
+## Install in Claude Code
+
+This installs it as a personal Skill:
+
+```bash
+mkdir -p ~/.claude/skills/ton-blockchain && \
+curl -fsSL https://raw.githubusercontent.com/ton-org/docs/main/skills/ton-blockchain/SKILL.md \
+  -o ~/.claude/skills/ton-blockchain/SKILL.md
+```
+
+Then restart Claude Code to pick up the new skill.
+
+## Install in other agents
+
+Copy `skills/ton-blockchain/SKILL.md` into your agent’s supported Skill directory (for example a project Skill folder), keeping the directory name `ton-blockchain`.

skills/ton-blockchain/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: ton-blockchain
+description: "Use when working with The Open Network (TON) blockchain, or when the user mentions TON-ecosystem terms the agent may not recognize—such as Tact, FunC, Tolk, Fift, TL-B, TVM, cells, BoC, Jettons, TEPs, TON Connect, workchains, shardchains, or liteservers. Provides a docs-first workflow for fetching and navigating TON documentation accurately, and covers smart contract development, transaction mechanics, wallet standards, token standards, Telegram Mini Apps, and infrastructure."
+---
+
+# TON Docs-first workflow
+
+Prefer primary sources from TON Docs.
+
+## 1) Read the orientation page first
+
+Fetch and skim the TON Docs “start here” page to align terminology and the docs’ structure before making assumptions:
+
+```bash
+curl -fsSL https://docs.ton.org/start-here.md
+```
+
+If the `.md` URL fails, try the HTML page:
+
+```bash
+curl -fsSL https://docs.ton.org/start-here
+```
+
+## 2) Discover available pages
+
+Fetch `llms.txt` to get the authoritative list of TON Docs pages and then search within it for relevant sections/pages:
+
+```bash
+curl -fsSL https://docs.ton.org/llms.txt
+```
+
+Practical pattern:
+
+```bash
+curl -fsSL https://docs.ton.org/llms.txt | rg -n "<topic>|<keyword>" || true
+```
+
+(Use `grep -nE` instead of `rg` if ripgrep isn’t available.)
+
+## 3) Pull only the pages you need
+
+For any relevant page path from `llms.txt`, prefer the Markdown source by appending `.md`:
+
+```bash
+curl -fsSL "https://docs.ton.org/<page-path>.md"
+```
+
+If that 404s, try the path as-is (some entries may already include `.md` or may not support source rendering):
+
+```bash
+curl -fsSL "https://docs.ton.org/<page-path>"
+```
+
+## 4) Execute the task using the docs as ground truth
+
+- Treat TON Docs as the primary reference; reconcile contradictions explicitly.
+- When answering, mention which TON Docs pages you consulted (page titles/paths).
+- If the user’s code/repo conventions conflict with TON Docs guidance, ask for clarification before proceeding.