AI Chat and Skills

Add AI chat to your app and teach it what to do with skills.

Overview

Myco apps include a built-in AI chat system. Users interact with a chat interface, and the AI agent can perform actions using skills — instructions you write that tell the agent how to behave and which tools it can use.

The ChatPage component

The SDK provides a ready-to-use chat page:


import { ChatPage } from "@myco-dev/sdk/chat";
import { useAuth } from "@myco-dev/sdk/auth";
import { myco } from "@/lib/myco";
 
function MyChatPage() {
  const { user } = useAuth();
 
  return (
    <ChatPage
      myco={myco}
      session={user ? { user: { id: user.id, name: user.name, email: user.email } } : null}
      conversationStarters={[
        { label: "Draft an email", message: "Help me draft an outreach email" },
        { label: "Search contacts", message: "Find all contacts at Acme Corp" },
      ]}
    />
  );
}

Props

Prop	Type	Description
`myco`	`MycoSDK`	SDK instance
`session`	`{ user: { id, name, email } } \| null`	Current user session
`chatId`	`string \| null`	Load an existing chat
`setChatId`	`(id: string) => void`	Callback when a new chat is created
`conversationStarters`	`Array<{ label, message }>`	Suggested prompts shown in empty state
`components`	`ChatComponents`	Custom component overrides
`beforeComposer`	`ReactNode`	Content rendered above the input
`composerPlaceholder`	`string`	Input placeholder text
`onError`	`(error: Error) => void`	Error handler
`className`	`string`	CSS class

Creating skills

Skills are SKILL.md files that define what the AI agent can do. They live in the skills/ directory:


skills/
  email-outreach/
    SKILL.md
  lead-qualification/
    SKILL.md

SKILL.md format

Each file has YAML frontmatter + markdown instructions:


---
name: email-outreach
description: Draft and send personalized outreach emails to leads and contacts.
allowed-tools: send-gmail-draft search-contacts
---
 
# Email Outreach
 
You help the user draft and send outreach emails.
 
When the user asks you to email someone:
1. Use `search-contacts` to find the contact
2. Draft a personalized email based on context
3. Use `send-gmail-draft` to create the draft

Frontmatter fields

Field	Required	Description
`name`	Yes	Unique identifier (kebab-case)
`description`	Yes	Short description for semantic matching
`allowed-tools`	No	Space-separated tool names this skill can use

Writing good descriptions

The description field is used for semantic matching — when a user sends a message, Myco compares it against skill descriptions to decide which skills to load. Write clear, specific descriptions:


# Good — specific and action-oriented
description: Draft and send personalized outreach emails to leads and contacts.
 
# Bad — too vague
description: Handle emails.

Discovering tools

Use the CLI to find available tools for your skills:


# List all toolkits
myco toolkit list
 
# View a toolkit's tools
myco toolkit get crm
 
# View a specific tool's parameters
myco toolkit tool crm search-contacts

Use tool names from these commands in the allowed-tools field.

Deploying skills

Skills deploy automatically with myco app deploy. To deploy skills independently:


myco skills deploy

Force redeploy

To regenerate embeddings for all skills:


myco skills deploy --force

Verify deployment


myco app get

This shows all deployed skills alongside app details.

How skill matching works

When a user sends a chat message:

The message is converted to an embedding
It’s compared against all skill description embeddings using cosine similarity
Skills above the similarity threshold (0.35) are loaded, up to 3 per turn
Loaded skills’ instructions and tools are available to the agent

This means the agent only has access to relevant skills for each message, keeping responses focused.