> For the complete documentation index, see [llms.txt](https://docs.gemach.io/gemach-dao/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gemach.io/gemach-dao/products/agent-skills/skill-format.md). # SKILL.md Format Reference A `SKILL.md` file is the single source of truth for a skill. It tells the agent what the skill is for, when to use it, and exactly which SDK methods or API endpoints to call. This page documents the format used by the [`GemachDAO/gdex-skill`](https://github.com/GemachDAO/gdex-skill) package. ## Package Layout The gdex-skill repository follows a **multi-skill** layout: each skill is its own directory under `skills/`, and a top-level `skill.json` describes the machine-readable action manifest consumed by [skills.sh](https://skills.sh) and the MCP server. ``` gdex-skill/ ├── skill.json # skills.sh action manifest (name, auth, base_url, actions[]) ├── skills.sh.json # grouping/ordering of skills for the skills.sh CLI ├── skills/ │ ├── gdex-onboarding/ │ │ └── SKILL.md # one skill = one directory + one SKILL.md │ ├── gdex-spot-trading/ │ │ └── SKILL.md │ └── … # 27 skills total ├── src/ # the @gdexsdk/gdex-skill TypeScript SDK └── mcp-server/ # the 116-tool MCP server ``` The directory name becomes the skill's identifier (e.g. `gdex-spot-trading`) and must match the `name` field in the `SKILL.md` front matter. ## SKILL.md Front Matter Every `SKILL.md` opens with a minimal YAML front-matter block — just two fields: ```yaml --- name: gdex-spot-trading description: Buy and sell tokens on Solana, Sui, and EVM chains with automatic DEX routing, slippage control, and percentage-based sells --- ``` | Field | Required | Purpose | | ------------- | -------- | ---------------------------------------------------------------------------------------------- | | `name` | ✅ | kebab-case identifier; must match the parent directory name exactly | | `description` | ✅ | One sentence shown in skill listings; agents read this to decide whether the skill is relevant | {% hint style="info" %} The `description` is the most important line in the file. The agent uses it to route a user request to the correct skill, so it should clearly state *what* the skill does and *when* to reach for it. {% endhint %} ## SKILL.md Body After the front matter, the body is plain markdown written **for the agent**. GDEX skills follow a consistent structure: ````markdown # GDEX: Spot Trading Buy and sell tokens across Solana, Sui, and 12+ EVM chains. The SDK routes through the best available DEX automatically, or you can specify one. ## When to Use - Buying a token with native currency (SOL, ETH, etc.) - Selling a token (absolute amount or percentage of holdings) - Executing managed-custody spot trades with encrypted payloads ## Prerequisites - `@gdexsdk/gdex-skill` installed - Authenticated via `loginWithApiKey()` or managed-custody sign-in - See **gdex-authentication** for auth setup ## Buy a Token ```typescript const trade = await skill.buyToken({ chain: 'solana', tokenAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', amount: '0.1', // 0.1 SOL slippage: 1, // 1% max slippage }); // Returns: { jobId, status, inputAmount, outputAmount, txHash?, error? } ``` ### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chain` | string \| ChainId | Yes | `'solana'`, `'sui'`, or a ChainId number | | `tokenAddress` | string | Yes | Contract address of the token | | `amount` | string | Yes | Native token input amount | | `slippage` | number | No | Max slippage % (default: 1) | > **Critical:** notes that prevent common mistakes go in blockquotes. ```` ### Recommended sections | Section | Purpose | | ----------------------------- | ------------------------------------------------------------------------------------------------------ | | **Title + intro** | One-line `# GDEX: ` heading plus a short paragraph | | **When to Use** | Bullet list of the scenarios that should trigger the skill | | **Prerequisites** | Required install/auth state and cross-references to sibling skills | | **Method sections** | One per operation, each with a TypeScript example and a parameter table | | **Warnings / Critical notes** | Blockquotes that flag footguns (e.g. the Solana chainId, deterministic AES, delete-vs-toggle behavior) | Skills cross-reference each other by **name** in bold (e.g. *see **gdex-authentication***) so the agent knows which sibling skill to load next. ## The `skill.json` Action Manifest Alongside the human-readable `SKILL.md` files, the package ships a machine-readable `skill.json` that the skills.sh CLI and MCP server use to expose callable actions. Each action declares a JSON-Schema parameter spec: ```json { "name": "@gdexsdk/gdex-skill", "version": "1.0.0", "description": "Cross-chain DeFi trading skill for AI agents…", "homepage": "https://github.com/GemachDAO/gdex-skill", "categories": ["finance", "trading", "defi", "crypto"], "auth": { "type": "computed_data", "encryption": "AES-256-CBC", "session_signing": "secp256k1" }, "base_url": "https://trade-api.gemach.io/v1", "actions": [ { "name": "buy_token", "description": "Buy a token on any supported chain using the best DEX route.", "parameters": { "type": "object", "required": ["chain", "tokenAddress", "amount"], "properties": { "chain": { "type": ["string", "number"], "description": "Chain name or ChainId" }, "tokenAddress": { "type": "string", "description": "Token contract address" }, "amount": { "type": "string", "description": "Native token input amount" }, "slippage": { "type": "number", "description": "Max slippage % (default 1)" } } } } ] } ``` ## Skill Grouping — `skills.sh.json` The `skills.sh.json` file controls how the skills are grouped and ordered when an agent browses or installs them: ```json { "$schema": "https://skills.sh/schemas/skills.sh.schema.json", "groupings": [ { "title": "Trading", "description": "Spot swaps, HyperLiquid perpetual futures, funding, and limit orders.", "skills": ["gdex-spot-trading", "gdex-perp-trading", "gdex-perp-funding", "gdex-limit-orders"] } ] } ``` ## Naming Conventions | Rule | Example | | --------------------------------------------- | ----------------------------------------------------------------- | | Directory and `name` field must match exactly | `gdex-spot-trading` / `name: gdex-spot-trading` | | Use `kebab-case` for all identifiers | `gdex-limit-orders`, not `gdexLimitOrders` | | Prefix GDEX skills with `gdex-` | `gdex-bridge`, `gdex-perp-trading` | | Prefix UI skills with `gdex-ui-` | `gdex-ui-trading-components` | | Keep names short and descriptive | `gdex-portfolio`, not `gdex-cross-chain-portfolio-balance-viewer` | ## Best Practices **Write for the agent, not for humans.** The body is loaded directly into the agent's working context. Prefer concrete TypeScript examples and parameter tables over prose. **Show the exact method signature.** Every method section should include a runnable `skill.()` example and the shape of the returned object. **Flag the footguns.** Use blockquotes for the non-obvious constraints that cause silent failures — the Solana chainId (`622112261`), deterministic AES (no random IV), and the fact that copy-trade `isDelete`/`isChangeStatus` both permanently delete. **Keep one skill focused.** A `buy_token` and a `sell_token` action are better than a single `trade` action with a `direction` flag — this is why GDEX splits capability across 27 small skills. *** **See also:** * [✏️ Creating Custom Skills](/gemach-dao/products/agent-skills/creating-custom-skills.md) — build or extend a skill step by step * [🧩 Agent Skills Overview](/gemach-dao/products/agent-skills.md) — the full catalog and install options --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.gemach.io/gemach-dao/products/agent-skills/skill-format.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.