adk-style-guide

name	adk-style-guide
description	ADK-TS brand voice, terminology, and writing conventions. Use when writing any documentation, READMEs, changelogs, blog posts, or technical content for the ADK-TS project. Also use when reviewing content for brand and style consistency.

ADK-TS Style Guide

Overview

This skill enforces ADK-TS brand identity, terminology, voice, and formatting conventions across all written content in the monorepo. It applies to documentation pages, READMEs, changelogs, code comments, and any developer-facing text.

When to Use

• Writing or editing any .md or .mdx file in the repo
• Creating changelogs or release notes
• Writing code comments or docstrings that reference ADK-TS
• Reviewing content for consistency

---

Brand Identity & Positioning

Naming Rules (Critical)

Rule	Correct	Incorrect
Framework name	ADK-TS	ADK, adk-ts, ADK TS, Adk-Ts
Never expand the acronym	ADK-TS	Agent Development Kit, Agent Development Kit for TypeScript
CLI references	ADK-TS CLI	adk CLI, the CLI, ADK CLI
Package names in code	@iqai/adk, @iqai/adk-cli	These are acceptable as-is (they are npm identifiers)

Tagline & Description

• Tagline: "The TypeScript-Native AI Agent Framework"
• Short description: "An open-source framework for building production-ready AI agents in TypeScript"
• People do not need to know what ADK-TS stands for. Just reference it as ADK-TS.

SEO-Aligned Language

Use these terms naturally in content:

• "TypeScript AI agents"
• "TypeScript agent framework"
• "build AI agents in TypeScript"
• "AI agent orchestration in TypeScript"

Avoid leading with these (they pull into Google's ADK space):

• "Agent Development Kit"
• "ADK" alone

---

Terminology

Always use these exact terms:

Correct Term	Avoid
agent	bot (unless literally a bot template like Telegram/Discord)
tool	function (when referring to agent capabilities)
session	conversation (for the persistence layer)
runner	executor (for the agent runner)
MCP server	MCP plugin, MCP integration
AgentBuilder	agent builder (lowercase, when referring to the class)
LlmAgent	LLM agent (lowercase, when referring to the class)

---

Voice & Tone

• Professional but approachable — not stiff, not casual
• Developer-centric — assume TypeScript fluency
• Action-oriented — use imperative verbs: "Create", "Install", "Run", "Build"
• Concise — lead with the answer, skip filler words
• Encouraging — end sections with "Ready to build?" or "Ready to contribute?"

---

Formatting Conventions

Headings

• H1 (#) for page title only — one per file
• H2 (##) for major sections
• H3 (###) for subsections
• Use emoji prefix for README section headings (e.g., ## 🚀 Quick Start)
• No emoji in docs site MDX headings (Fumadocs handles styling)

Code Blocks

• Always specify language: ```typescript or ```bash
• Never use ```js — always ```typescript

Feature Lists

Use this pattern in READMEs:

- **🤖 Multi-Provider LLM Support** - Seamlessly integrate OpenAI, Anthropic, Google, and other providers
- **🛠️ Extensible Tool System** - Define custom tools with declarative schemas

Configuration Tables

Use this column structure:

| Property | Type     | Required | Description              |
| -------- | -------- | -------- | ------------------------ |
| `name`   | `string` | Yes      | The agent's display name |

---

Code Example Conventions

• Always TypeScript (never JavaScript)
• Import from @iqai/adk (never relative paths in documentation)
• Use AgentBuilder for simple/introductory examples
• Use new LlmAgent({...}) for advanced configuration examples
• Include dotenv setup when environment variables are needed
• Default model: gemini-2.5-flash (Gemini is the default LLM — use it in most examples). Other supported: gpt-4.1, claude-sonnet-4-5

Simple Example Pattern

import { AgentBuilder } from "@iqai/adk";

const response = await AgentBuilder.withModel("gemini-2.5-flash").ask(
  "What is the primary function of an AI agent?",
);

Advanced Example Pattern

import { LlmAgent } from "@iqai/adk";

const agent = new LlmAgent({
  name: "my-agent",
  model: "gemini-2.5-flash",
  instruction: "You are a helpful assistant",
  tools: [myTool],
});

---

Canonical URLs

Use these exact URLs everywhere — no variations:

Resource	URL
GitHub repo	https://github.com/IQAIcom/adk-ts
GitHub Discussions	https://github.com/IQAIcom/adk-ts/discussions
Telegram (ADK-TS / IQ Builders)	https://t.me/+Z37x8uf6DLE3ZTQ8
Telegram (IQ AI company)	https://t.me/IQAICOM
Documentation site	https://adk.iqai.com/
NPM package	https://www.npmjs.com/package/@iqai/adk
Sample projects	https://github.com/IQAIcom/adk-ts-samples
Logo image	https://files.catbox.moe/vumztw.png

Telegram link usage: Use the ADK-TS / IQ Builders link (+Z37x8uf6DLE3ZTQ8) in framework docs, READMEs, and developer-facing content. Use the IQ AI company link (IQAICOM) only for company-level references (e.g., SECURITY.md).

GitHub org casing: Always IQAIcom (NOT IQAICOM or iqaicom)

Internal Doc Links

• Framework docs: /docs/framework/...
• CLI docs: /docs/cli/...
• MCP docs: /docs/mcp-servers/...

---

Constants

• Node.js version requirement: >=22.0 (not 18+ — this is the monorepo standard)
• Package manager: pnpm (always mention pnpm first in multi-manager examples)
• License: MIT

---

Checklist for Content Review

When reviewing any content, verify:

• Uses "ADK-TS" not bare "ADK"
• Never expands to "Agent Development Kit"
• CLI referenced as "ADK-TS CLI"
• GitHub URLs use IQAIcom casing
• Node.js version is >=22.0
• Code examples use TypeScript with @iqai/adk imports
• Model names are current (not deprecated)
• Canonical URLs are correct
• Tone is professional but approachable
• Headings follow hierarchy (H1 → H2 → H3)