Builder Agents Guide

---
# Official Fields
name: my-custom-skill # Skill identifier (kebab-case, max 64 characters)
description: > # Purpose description (50-1024 characters, 3rd person)
  Description of custom skill. What tasks it's used for, what expertise it provides,
  written in 3rd person.
allowed-tools: # Allowed tools (comma-separated or list)
  - Read
  - Grep
  - Glob
model: claude-sonnet-4-20250514 # Model to use (defaults to current model if omitted)
context: fork # Execute in subagent context
agent: general-purpose # Agent to use when context: fork
hooks: # Skill lifecycle hooks
  PreToolUse: ...
user-invocable: true # Show in slash command menu
disable-model-invocation: false # If false, Claude can also invoke directly
argument-hint: "[issue-number]" # Autocomplete hint
 
# MoAI-ADK Extended Fields
version: 1.0.0 # Semantic version (MAJOR.MINOR.PATCH)
category: domain # One of 8 categories
modularized: false # Whether to use modules/ directory
status: active # active | experimental | deprecated
updated: "2025-01-28" # Last modified date
tags: # Array of tags for discovery
  - graphql
  - api
related-skills: # Related skills
  - moai-domain-backend
  - moai-lang-typescript
context7-libraries: # MCP Context7 library IDs
  - graphql
aliases: # Alternative names
  - graphql-expert
author: YourName # Author
---

.claude/skills/my-skills/
└── my-graphql-patterns/
    ├── SKILL.md            # Main skill document (under 500 lines)
    ├── modules/            # In-depth documentation (unlimited)
    │   ├── schema-design.md
    │   └── resolver-patterns.md
    ├── examples.md         # Real-world examples
    └── reference.md        # External references

---
# YAML
---
 
# Project Information
 
Project name: !basename $(pwd)
Git branch: !git branch --show-current

# Invoke builder-skill in Claude Code
> Create a custom skill for GraphQL API design patterns

---
name: my-graphql-patterns
description: >
  GraphQL API design expert. Provides schema design, resolver patterns, N+1 problem
  resolution, DataLoader patterns. Use when developing GraphQL APIs.
version: 1.0.0
category: domain
status: active
triggers:
  keywords: ["graphql", "schema", "resolver", "dataloader"]
  agents: ["expert-backend"]
allowed-tools: ["Read", "Grep", "Glob"]
---
 
# GraphQL API Design Expert
 
## Quick Reference
 
- Schema-first design
- DataLoader essential for preventing N+1 problems
- Use Relay Cursor pagination
 
## Implementation Guide
 
(Detailed implementation guide)
 
## Advanced Patterns
 
(Advanced patterns)
 
## Works Well With
 
- moai-domain-backend
- moai-lang-typescript

---
name: my-data-analyst
description: >
  Data analysis expert. Responsible for data pipeline design, ETL processes,
  analytics query optimization. PROACTIVELY use for automatic delegation
  during data analysis tasks.
tools: Read, Write, Edit, Grep, Glob, Bash, TodoWrite
disallowedTools: Task, Skill # Optional: tools to exclude
model: sonnet # sonnet | opus | haiku | inherit
permissionMode: default # Permission mode
skills: # Skills to preload
  - moai-lang-python
  - moai-domain-database
hooks: # Agent lifecycle hooks
  PostToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: "echo 'File modified'"
---
 
You are a data analysis expert.
 
## Primary Mission
 
Provide data-driven insights through data pipeline design and implementation.
 
## Core Capabilities
 
- Data pipeline design and implementation
- ETL process automation
- Analytics query optimization
- Data visualization
 
## Scope Boundaries
 
IN SCOPE:
- Data analysis and visualization
- ETL process design
- Query performance optimization
 
OUT OF SCOPE:
- ML model development (delegate to expert-data-science)
- Infrastructure configuration (delegate to expert-devops)
 
## Delegation Protocol
 
- For ML model needs: expert-data-science
- For infrastructure setup: expert-devops
 
## Quality Standards
 
- Follow TRUST 5 framework
- Verify data integrity
- Optimize query performance

my-plugin/
├── .claude-plugin/
│   └── plugin.json         # Plugin manifest
├── commands/               # Slash commands (root level!)
│   └── analyze.md
├── agents/                 # Agent definitions (root level!)
│   └── data-expert.md
├── skills/                 # Skill definitions (root level!)
│   └── my-skill/
│       └── SKILL.md
├── hooks/                  # Hooks configuration (root level!)
│   └── hooks.json
├── .mcp.json               # MCP server configuration
├── .lsp.json               # LSP server configuration
├── LICENSE
├── CHANGELOG.md
└── README.md

{
  "name": "my-data-plugin",
  "version": "1.0.0",
  "description": "Comprehensive plugin for data analysis tasks",
  "author": {
    "name": "My Team",
    "email": "[email protected]",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/docs",
  "repository": {
    "type": "git",
    "url": "https://github.com/owner/repo"
  },
  "license": "MIT",
  "keywords": ["data", "analytics", "etl"],
  "commands": ["./commands/"],
  "agents": ["./agents/"],
  "skills": ["./skills/"],
  "hooks": "./hooks/hooks.json",
  "mcpServers": "./.mcp.json",
  "lspServers": "./.lsp.json",
  "outputStyles": "./output-styles/"
}

{
  "name": "my-marketplace",
  "owner": {
    "name": "My Organization",
    "email": "[email protected]"
  },
  "plugins": [
    {
      "name": "plugin-one",
      "source": "./plugins/plugin-one"
    },
    {
      "name": "plugin-two",
      "source": {
        "type": "github",
        "repo": "owner/repo"
      }
    }
  ]
}

# Install plugin from GitHub
$ /plugin install owner/repo
 
# Validate local plugin
$ /plugin validate .
 
# Enable plugin
$ /plugin enable my-data-plugin
 
# Add marketplace
$ /plugin marketplace add ./path/to/marketplace
 
# List installed plugins
$ /plugin list

# Plugin creation request
> Create a data analysis plugin.
> Include skills, agents, and commands.

# Create skill
> @"builder-skill (agent)" Create a custom skill for GraphQL patterns
 
# Create agent
> @"builder-agent (agent)" Create a data analysis expert agent
 
# Create plugin
> @"builder-plugin (agent)" Create a comprehensive data analysis plugin