Teach-Agent Skill

Synopsis

Empowers agents to autonomously acquire new skills by following a structured self-teaching loop. When faced with an unfamiliar technology, protocol, or capability, an agent should be able to teach itself what it needs to complete the work.

Trigger

• Agent encounters a task requiring unknown tools, APIs, or integrations
• Agent needs to connect to a service (e.g., Discord, Slack, external API)
• Agent lacks required knowledge for a task
• Explicit request to "teach yourself" or "learn how to"

Self-Teaching Loop

┌─────────────────────────────────────────────────────────────┐
│  1. RESEARCH    →   2. UNDERSTAND   →   3. IMPLEMENT      │
│         ↑                                    │              │
│         └──────── 5. VALIDATE  ←────────────┘              │
│                      ↓                                      │
│              4. DOCUMENT                                     │
└─────────────────────────────────────────────────────────────┘

Step 1: Research

Use these tools to gather information:

• WebSearch

  : Find documentation, tutorials, official resources
  • Query: "[technology name] documentation", "[API name] getting started", "[protocol] tutorial"
  • Example:

    WebSearch

    query for Discord → "Discord API documentation bot development"

• WebFetch

  : Read official docs directly
  • Fetch the official documentation page for the technology
  • Extract key concepts, authentication patterns, API structure

• mcp__zread__search_doc

  : Search GitHub repos for code examples
  • Search: "discord.js bot example", "discord API python wrapper"
  • Find real code patterns used by the community

Step 2: Understand

After research, the agent should be able to explain:

1. What is it? - A one-paragraph description
2. How does authentication work? - API keys, OAuth, tokens, etc.
3. What are the core concepts? - Objects, events, methods
4. What's the typical implementation pattern? - Initialization → configuration → usage
5. What tools/MCPs are available? - Any existing MCP servers for this service?

Step 3: Implement

Create the solution:

1. If a Skill is needed: Create a new

   .claude/skills/[skill-name]/SKILL.md

2. If code is needed: Write the implementation following patterns found in research
3. Follow existing conventions: Use the codebase's established patterns

Step 4: Document

Save the learned knowledge:

.claude/skills/[skill-name]/
├── SKILL.md          # What the skill does, trigger, usage
├── README.md         # How-to guide with examples
└── [implementation]  # Any supporting files

Step 5: Validate

• If it's a skill: Use the skill to verify it triggers correctly
• If it's code: Verify the implementation makes sense structurally
• Check that the skill/code follows project conventions

Example: Teaching Yourself Discord

Research Phase

User: "Connect this agent to Discord so it can send messages to a channel"

Agent:
1. WebSearch("Discord API bot development documentation")
2. WebSearch("Discord bot Python discord.py library")
3. WebFetch("https://discord.com/developers/docs/introduction")
4. mcp__zread__search_doc("discord.py bot example", repo_name="Rapptz/discord.py")

Understanding Phase

After research, the agent understands:

• Discord bots use Bot tokens via HTTP Bearer auth or WS gateway
• Bot must be added to server with specific permissions
• Messages sent via HTTP POST to channel webhooks or bot API
• Python libraries:

  discord.py

  (async),

  nextcord

  ,

  py-cord

Implementation Phase

The agent would create a skill like:

---
name: discord-notify
description: This skill should be used when the user asks to "send a message to Discord", "notify Discord channel", "Discord webhook", or "Discord bot message". Sends notifications to Discord channels via webhooks or bot API.
version: 1.0.0
tags: [discord, webhook, notifications, bot]
authors: [agent]
inputs:
  message: "Message content to send"
  channel_id: "Target Discord channel ID"
outputs:
  result: "Success/failure status of the notification"
---

# Discord-Notify Skill

## Synopsis
Sends notifications to Discord channels via webhooks or bot API.

## Trigger
- Task requires sending messages to Discord
- "Send a message to Discord", "Notify Discord channel"

## Implementation
[Created based on research]

Validation Phase

• Verify the skill file is valid markdown
• Verify the skill has YAML frontmatter with

  name

  ,

  description

  , and

  version

• Verify the description uses third person ("This skill should be used when...")
• Verify the skill has required sections (synopsis, trigger, implementation)
• Verify the implementation follows the codebase patterns

Key Principles

1. Start with WebSearch - Official docs and tutorials are the fastest path
2. Look for patterns - Find existing similar skills/code in the codebase
3. Create skills for reusable knowledge - If you'll need it again, make it a skill
4. Follow conventions - Match the style and structure of existing skills
5. Validate before finishing - Ensure the skill actually works

Skill File Template

---
name: [skill-name]
description: This skill should be used when the user asks to "[trigger phrase 1]", "[trigger phrase 2]", "[trigger phrase 3]". [What this skill enables - one clear sentence].
version: 1.0.0
tags: [tag1, tag2, tag3]
authors: [author-name]
inputs:
  input_name: "Description of expected input"
outputs:
  output_name: "Description of expected output"
---

# [Skill-Name]

## Synopsis
[What this skill enables - one clear sentence]

## Trigger
- [When this skill should be invoked]
- [Alternative trigger phrases]

## Implementation
[How the skill works - code, steps, or references]

## Examples
[Usage examples showing input/output]

Frontmatter Requirements:

• name

  (required): The skill identifier, kebab-case (e.g.,

  discord-bot

  )

• description

  (required): Third-person description with specific trigger phrases. Use "This skill should be used when the user asks to..."

• version

  (required): Semantic version (e.g.,

  1.0.0

  )

• tags

  (optional): Keywords for categorization

• authors

  (optional): List of authors

• inputs

  /

  outputs

  (optional): Define expected inputs and outputs

Related Skills

• plugin-dev:skill-development

  - For creating skills properly

• plugin-dev:plugin-structure

  - For understanding skill directory structure