Initial commit
This commit is contained in:
Zhongwei Li
941
skills/documentation/SKILL.md
Normal file
941
skills/documentation/SKILL.md
Normal file
@@ -0,0 +1,941 @@
|
||||
---
|
||||
name: field-agent-documentation
|
||||
description: Comprehensive template and guidelines for documenting Field Agents including technical specifications, system prompts, tool specifications, user interactions, and standardized documentation structure
|
||||
---
|
||||
|
||||
# Field Agent Documentation Standards
|
||||
|
||||
This skill provides a complete template and best practices for creating professional, comprehensive documentation for Field Agents. Following these standards ensures consistency, clarity, and ease of use across all agent documentation.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when you need to:
|
||||
- Create documentation for a new Field Agent
|
||||
- Standardize existing Field Agent documentation
|
||||
- Write system prompts with best practices
|
||||
- Define tool specifications and naming conventions
|
||||
- Structure user prompts and interaction patterns
|
||||
- Document agent architecture and technical details
|
||||
|
||||
## Documentation Structure Overview
|
||||
|
||||
Complete Field Agent documentation should include these sections in order:
|
||||
|
||||
```markdown
|
||||
1. Basic Information (metadata, links, status)
|
||||
2. Team Structure (owners, contributors)
|
||||
3. Purpose & Functionality (description, value, users)
|
||||
4. Usage Scenarios (use cases, examples)
|
||||
5. Technical Specifications (model, settings, parameters)
|
||||
6. Dependencies & Integration (requirements, data sources)
|
||||
7. Agent/Sub-Agent Details (per-agent specifications)
|
||||
8. System Prompt (detailed agent instructions)
|
||||
9. Tools (function specifications and schemas)
|
||||
10. Input/Output Format (data structures, formats)
|
||||
11. User Prompts (interaction patterns, guided flows)
|
||||
12. Development Roadmap (milestones, phases)
|
||||
13. Demo (examples, videos, recordings)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section 1: Basic Information
|
||||
|
||||
This section provides essential metadata about the agent.
|
||||
|
||||
### Template
|
||||
|
||||
```markdown
|
||||
# [Agent Name]
|
||||
|
||||
## Basic Information
|
||||
|
||||
| Item | Details |
|
||||
|------|---------|
|
||||
| **Project Name** | [Clean, self-explanatory, immutable name] |
|
||||
| **Type** | Field Agent |
|
||||
| **Interface Type** | TD Workflow / Chat / Slack / API |
|
||||
| **GitHub Repo Link** | [Repository URL] |
|
||||
| **Status** | Development / Staging / Production |
|
||||
| **Version** | [Semantic version: MAJOR.MINOR.PATCH] |
|
||||
| **Last Updated** | [YYYY-MM-DD] |
|
||||
| **Agent Instance** | [Cloud provider: instance ID] |
|
||||
| **Agent Link** | [Direct link to agent] |
|
||||
| **One-Pager Slide** | [Link to overview presentation] |
|
||||
| **Demo Video** | [Link to demonstration recording] |
|
||||
| **Demo Talk-Track** | [Link to demo script] |
|
||||
```
|
||||
|
||||
### Best Practices
|
||||
- **Project Name**: Choose a clear, descriptive name that won't change
|
||||
- **Status**: Keep status current (Development → Staging → Production)
|
||||
- **Version**: Use semantic versioning (1.0.0, 1.1.0, 2.0.0)
|
||||
- **Links**: Ensure all links are accessible to target audience
|
||||
|
||||
---
|
||||
|
||||
## Section 2: Team Structure
|
||||
|
||||
Document who is responsible for the agent.
|
||||
|
||||
### Template
|
||||
|
||||
```markdown
|
||||
## Team Structure
|
||||
|
||||
| Role | Assignee |
|
||||
|------|----------|
|
||||
| **Product Owner / Main Architect** | [Name, Email] |
|
||||
| **Additional Contributors** | [Names, Roles] |
|
||||
| **Support Contact** | [Team/Channel] |
|
||||
```
|
||||
|
||||
### Best Practices
|
||||
- Include contact information for support
|
||||
- List all contributors for accountability
|
||||
- Update when team changes occur
|
||||
|
||||
---
|
||||
|
||||
## Section 3: Purpose & Functionality
|
||||
|
||||
Explain what the agent does and why it matters.
|
||||
|
||||
### Template
|
||||
|
||||
```markdown
|
||||
## Purpose & Functionality
|
||||
|
||||
### Description
|
||||
[Brief 2-3 sentence description of what the agent performs and its core functionality]
|
||||
|
||||
### Key Capabilities
|
||||
- **Integration 1**: [What it integrates with and how]
|
||||
- **Integration 2**: [What it integrates with and how]
|
||||
- **Core Feature**: [Primary capability description]
|
||||
|
||||
### Business Value
|
||||
[Explain the business value this agent delivers. What problems does it solve? What ROI does it provide?]
|
||||
|
||||
### Target Users
|
||||
- **Primary**: [Job roles/personas who will use this most]
|
||||
- **Secondary**: [Additional users who may benefit]
|
||||
|
||||
### Potential Applications
|
||||
[Detailed description of who will use this agent and in what contexts]
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
```markdown
|
||||
## Purpose & Functionality
|
||||
|
||||
### Description
|
||||
Customer Segmentation Agent analyzes customer data to automatically identify behavioral segments using RFM (Recency, Frequency, Monetary) analysis and predictive modeling.
|
||||
|
||||
### Key Capabilities
|
||||
- **Database Integration**: Connects to Treasure Data customer databases
|
||||
- **Segmentation Algorithms**: RFM, K-means clustering, behavioral scoring
|
||||
- **Visualization**: Generates interactive Plotly charts and segment distributions
|
||||
|
||||
### Business Value
|
||||
Enables marketing teams to identify high-value customer segments 10x faster than manual analysis, improving campaign targeting accuracy by 35% and increasing ROI on marketing spend.
|
||||
|
||||
### Target Users
|
||||
- **Primary**: Marketing Managers, CRM Analysts, Customer Success Teams
|
||||
- **Secondary**: Data Analysts, Business Intelligence Teams
|
||||
|
||||
### Potential Applications
|
||||
Marketing teams use this agent to create targeted campaigns, CRM teams identify at-risk customers for retention programs, and analysts explore customer lifetime value patterns.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section 4: Usage Scenarios
|
||||
|
||||
Provide concrete examples of how the agent is used.
|
||||
|
||||
### Template
|
||||
|
||||
```markdown
|
||||
## Usage Scenarios
|
||||
|
||||
### Primary Use Case
|
||||
[Describe the most common use case with a step-by-step example]
|
||||
|
||||
**Example:**
|
||||
1. User asks: "[Sample user query]"
|
||||
2. Agent performs: "[What the agent does]"
|
||||
3. Agent returns: "[What the user receives]"
|
||||
|
||||
### Additional Use Cases
|
||||
1. **Use Case Name**: [Description and benefit]
|
||||
2. **Use Case Name**: [Description and benefit]
|
||||
3. **Use Case Name**: [Description and benefit]
|
||||
|
||||
### Example Scenarios
|
||||
|
||||
#### Scenario 1: [Name]
|
||||
**Context**: [When this scenario applies]
|
||||
**User Input**: "[Example user query]"
|
||||
**Agent Output**: [What the agent provides]
|
||||
**Outcome**: [Business result]
|
||||
|
||||
#### Scenario 2: [Name]
|
||||
[Follow same structure]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section 5: Technical Specifications
|
||||
|
||||
Define the technical configuration of the agent.
|
||||
|
||||
### Template
|
||||
|
||||
```markdown
|
||||
## Technical Specifications
|
||||
|
||||
| Item | Details |
|
||||
|------|---------|
|
||||
| **Agent Name** | [Name - use `[Sub]` prefix for sub-agents] |
|
||||
| **Model Name** | Claude 4 Sonnet ⭐ (Recommended) / Claude 3.5 Sonnet / Claude 3 Haiku |
|
||||
| **Max Tool Iterations** | [Number - controls resource consumption] |
|
||||
| **Temperature** | [0-1, where 0 = deterministic, 1 = creative] ⭐ Recommended: 0 |
|
||||
| **Max Tokens** | [Output token limit] |
|
||||
| **Timeout** | [Execution timeout in seconds] |
|
||||
```
|
||||
|
||||
### Model Selection Guide
|
||||
|
||||
**Claude 4 Sonnet (Recommended)** ⭐
|
||||
- Best for: Most production Field Agents
|
||||
- Benefits: Highest performance, more output tokens, better reasoning
|
||||
- Use when: You need reliability and comprehensive outputs
|
||||
|
||||
**Claude 3.5 Sonnet**
|
||||
- Best for: Alternative to Claude 4, similar capabilities
|
||||
- Benefits: Strong performance, widely tested
|
||||
- Use when: Claude 4 not available or testing compatibility
|
||||
|
||||
**Claude 3 Haiku**
|
||||
- Best for: Lightweight, fast-response tasks
|
||||
- Benefits: Lower cost, faster execution
|
||||
- Use when: Simple queries, real-time requirements, budget constraints
|
||||
|
||||
### Temperature Guide
|
||||
|
||||
| Temperature | Behavior | Best For |
|
||||
|-------------|----------|----------|
|
||||
| **0** ⭐ | Deterministic, consistent answers | Most Field Agents, production use |
|
||||
| **0.3** | Slight variation, mostly consistent | Agents needing minor creative variation |
|
||||
| **0.7** | Balanced creativity and consistency | Content generation with some flexibility |
|
||||
| **1.0** | Maximum creativity, varied outputs | Creative writing, brainstorming agents |
|
||||
|
||||
**Recommended**: Use temperature **0** for Field Agents to ensure consistent, reliable outputs.
|
||||
|
||||
### Max Tool Iterations
|
||||
|
||||
Controls how many times the agent can execute tools before stopping.
|
||||
|
||||
```markdown
|
||||
- **Low (5-10)**: Simple agents with few tool calls
|
||||
- **Medium (15-20)**: Most Field Agents with moderate complexity
|
||||
- **High (25-30)**: Complex agents requiring multiple data sources and iterations
|
||||
```
|
||||
|
||||
**Best Practice**: Start with 15-20, increase only if agent needs more steps.
|
||||
|
||||
---
|
||||
|
||||
## Section 6: Dependencies & Integration
|
||||
|
||||
Document all external requirements and integrations.
|
||||
|
||||
### Template
|
||||
|
||||
```markdown
|
||||
## Dependencies & Integration
|
||||
|
||||
### Required Data Sources
|
||||
| Data Source | Purpose | Access Requirements |
|
||||
|-------------|---------|---------------------|
|
||||
| [Database/Table] | [What data is used] | [Permissions needed] |
|
||||
|
||||
### Integration Points
|
||||
| Integration | Type | Purpose |
|
||||
|-------------|------|---------|
|
||||
| [System/API] | [REST/GraphQL/SDK] | [What it's used for] |
|
||||
|
||||
### Prerequisites
|
||||
- [ ] Access to [database/system]
|
||||
- [ ] Permissions: [specific permissions]
|
||||
- [ ] API keys configured: [which APIs]
|
||||
- [ ] Dependencies installed: [libraries/tools]
|
||||
|
||||
### Dependencies on Other Systems
|
||||
- [None] OR [List dependent workflows, features, product permissions]
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
```markdown
|
||||
## Dependencies & Integration
|
||||
|
||||
### Required Data Sources
|
||||
| Data Source | Purpose | Access Requirements |
|
||||
|-------------|---------|---------------------|
|
||||
| `customer_db.transactions` | Transaction history for RFM analysis | Read access to customer_db |
|
||||
| `customer_db.profiles` | Customer demographic data | Read access to customer_db |
|
||||
|
||||
### Integration Points
|
||||
| Integration | Type | Purpose |
|
||||
|-------------|------|---------|
|
||||
| Treasure Data Trino | SQL Query | Data extraction and analysis |
|
||||
| Plotly | Visualization Library | Chart generation |
|
||||
|
||||
### Prerequisites
|
||||
- [ ] Access to `customer_db` database
|
||||
- [ ] Permissions: Read access on customer tables
|
||||
- [ ] API keys configured: None required
|
||||
- [ ] Dependencies installed: Plotly for visualizations
|
||||
|
||||
### Dependencies on Other Systems
|
||||
- Requires Treasure Data instance with Trino query engine
|
||||
- No dependencies on external workflows
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section 7: Agent/Sub-Agent Details
|
||||
|
||||
Provide detailed specifications for each agent and sub-agent.
|
||||
|
||||
### Template
|
||||
|
||||
```markdown
|
||||
## Agent Details: [Agent Name]
|
||||
|
||||
| Item | Details |
|
||||
|------|---------|
|
||||
| **Agent Name** | [Name] or **[Sub] [Name]** for sub-agents |
|
||||
| **Model Name** | Claude 4 Sonnet ⭐ |
|
||||
| **Max Tool Iterations** | [Number] |
|
||||
| **Temperature** | 0 ⭐ |
|
||||
| **Purpose** | [What this specific agent does] |
|
||||
| **Invocation** | [How this agent is called] |
|
||||
|
||||
### Sub-Agents
|
||||
If this agent uses sub-agents, list them:
|
||||
|
||||
- **[Sub] Sub-Agent Name**: [Purpose and when it's invoked]
|
||||
```
|
||||
|
||||
### Best Practices
|
||||
- Use `[Sub]` prefix for sub-agents to distinguish from main agents
|
||||
- Document invocation patterns (how/when sub-agents are called)
|
||||
- Specify different configurations if sub-agents use different models
|
||||
|
||||
---
|
||||
|
||||
## Section 8: System Prompt
|
||||
|
||||
The system prompt is the most critical element - it defines agent behavior.
|
||||
|
||||
### System Prompt Structure Template
|
||||
|
||||
```markdown
|
||||
## System Prompt: [Agent Name]
|
||||
|
||||
# [Agent Name]
|
||||
|
||||
[Brief one-line description of agent role and purpose]
|
||||
|
||||
# Role
|
||||
|
||||
The agent's role and responsibilities:
|
||||
- [Responsibility 1]
|
||||
- [Responsibility 2]
|
||||
- [Responsibility 3]
|
||||
|
||||
# Goal
|
||||
|
||||
[Detailed description of what the user receives when the agent is executed and what the agent aims to achieve]
|
||||
|
||||
## Basic Principles
|
||||
|
||||
High-level workflow:
|
||||
1. [Step 1: What happens first]
|
||||
2. [Step 2: What happens next]
|
||||
3. [Step 3: Final steps]
|
||||
4. [Step 4: Output delivery]
|
||||
|
||||
## Available Tools
|
||||
|
||||
### [Tool Category/Purpose]
|
||||
|
||||
**Tool**: `tool_name_in_snake_case`
|
||||
**Purpose**: [Brief purpose of this tool]
|
||||
**Input**: [What inputs the tool consumes]
|
||||
**Output**: [What outputs the tool returns]
|
||||
|
||||
### [Next Tool Category]
|
||||
|
||||
**Tool**: `another_tool_name`
|
||||
**Purpose**: [Brief purpose]
|
||||
**Input**: [Input parameters]
|
||||
**Output**: [Return values]
|
||||
|
||||
## Task Flow
|
||||
|
||||
### Task 1: [Tool Name] [required = true, mandatory_start = true]
|
||||
|
||||
**Execution**:
|
||||
call_<tool_name>[required = true, mandatory_start = true]
|
||||
|
||||
**Steps** [sequential=true]:
|
||||
1. [Detailed step-by-step pseudo-logic]
|
||||
2. [What the tool should do]
|
||||
3. [How to handle results]
|
||||
4. [Error handling]
|
||||
|
||||
**Output Format**:
|
||||
[Describe or show sample output format]
|
||||
|
||||
### Task 2: [Next Tool] [required = false]
|
||||
|
||||
[Follow same structure]
|
||||
|
||||
## Checklist (Optional)
|
||||
|
||||
If applicable, provide a validation checklist:
|
||||
- [ ] [Validation item 1]
|
||||
- [ ] [Validation item 2]
|
||||
- [ ] [Validation item 3]
|
||||
```
|
||||
|
||||
### System Prompt Best Practices
|
||||
|
||||
#### 1. Tool Naming Conventions ⭐
|
||||
|
||||
**Use snake_case with descriptive names:**
|
||||
|
||||
✅ **Good Examples:**
|
||||
```
|
||||
verify_database_access
|
||||
list_columns_customer_db
|
||||
query_sales_data
|
||||
calculate_rfm_scores
|
||||
generate_segment_visualization
|
||||
fetch_customer_transactions
|
||||
```
|
||||
|
||||
❌ **Bad Examples:**
|
||||
```
|
||||
verify # Too vague
|
||||
list # What are we listing?
|
||||
query # Query what?
|
||||
verifydbaccess # Hard to read, no separators
|
||||
listColumns # Should be snake_case
|
||||
```
|
||||
|
||||
**Naming Pattern**: `[action]_[object]_[context]`
|
||||
- **Action**: verify, list, query, calculate, generate, fetch, create, update
|
||||
- **Object**: database, columns, data, scores, visualization
|
||||
- **Context**: customer_db, sales, rfm, etc.
|
||||
|
||||
#### 2. Reduce Hallucination with Detailed Logic
|
||||
|
||||
Provide explicit pseudo-logic instead of general instructions:
|
||||
|
||||
✅ **Good - Explicit Logic:**
|
||||
```markdown
|
||||
### Task 1: Query Customer Data
|
||||
|
||||
**Steps** [sequential=true]:
|
||||
1. Call `verify_database_access` with database name
|
||||
2. If access is denied, return error message: "Database access denied. Please check permissions."
|
||||
3. If access is granted, call `list_columns_customer_db` to retrieve schema
|
||||
4. Validate that required columns exist: ['customer_id', 'revenue', 'last_purchase_date']
|
||||
5. If columns missing, return error: "Required columns not found: [list missing columns]"
|
||||
6. If columns exist, call `query_sales_data` with filters:
|
||||
- WHERE last_purchase_date >= DATE_SUB(CURRENT_DATE, INTERVAL 365 DAY)
|
||||
- AND revenue > 0
|
||||
7. Return result set in JSON format
|
||||
```
|
||||
|
||||
❌ **Bad - Vague Instructions:**
|
||||
```markdown
|
||||
### Task 1: Query Customer Data
|
||||
|
||||
Query the customer database and get the data we need.
|
||||
```
|
||||
|
||||
#### 3. Specify Sequential vs. Parallel Execution
|
||||
|
||||
```markdown
|
||||
**Steps** [sequential=true]:
|
||||
# Tasks must execute in order - each depends on previous
|
||||
|
||||
**Steps** [parallel=true]:
|
||||
# Tasks can execute simultaneously - no dependencies
|
||||
```
|
||||
|
||||
#### 4. Include Sample Output Formats
|
||||
|
||||
```markdown
|
||||
**Output Format**:
|
||||
\```json
|
||||
{
|
||||
"status": "success",
|
||||
"segments": [
|
||||
{
|
||||
"segment_name": "Champions",
|
||||
"customer_count": 1250,
|
||||
"avg_revenue": 5200.00,
|
||||
"characteristics": {
|
||||
"recency_score": 5,
|
||||
"frequency_score": 5,
|
||||
"monetary_score": 5
|
||||
}
|
||||
}
|
||||
],
|
||||
"total_customers_analyzed": 5000,
|
||||
"execution_time_ms": 2341
|
||||
}
|
||||
\```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section 9: Tools
|
||||
|
||||
Document each tool/function specification.
|
||||
|
||||
### Template
|
||||
|
||||
```markdown
|
||||
## Tools
|
||||
|
||||
### Tool: `tool_name_in_snake_case`
|
||||
|
||||
| Item | Details |
|
||||
|------|---------|
|
||||
| **Function Name** | `tool_name_in_snake_case` |
|
||||
| **Function Description** | [Brief description of what this function does] |
|
||||
| **Target** | Knowledge Base / Agent / External API |
|
||||
| **Target Function** | List Columns / Query Data / Search Schema / Custom |
|
||||
|
||||
#### Input Format
|
||||
\```json
|
||||
{
|
||||
"parameter1": "value1",
|
||||
"parameter2": "value2"
|
||||
}
|
||||
\```
|
||||
|
||||
#### Output Format
|
||||
\```json
|
||||
{
|
||||
"result": "data",
|
||||
"status": "success"
|
||||
}
|
||||
\```
|
||||
|
||||
#### Example Usage
|
||||
\```
|
||||
User: "Get customer segments"
|
||||
Tool Call: query_customer_segments({"min_revenue": 1000})
|
||||
Tool Response: {"segments": [...], "total": 5}
|
||||
\```
|
||||
|
||||
### Tool: `next_tool_name`
|
||||
|
||||
[Follow same structure for each tool]
|
||||
```
|
||||
|
||||
### Tool Target Types
|
||||
|
||||
**Knowledge Base Tools:**
|
||||
- **List Columns**: Retrieve schema information
|
||||
- **Query Data (Trino SQL)**: Execute SQL queries
|
||||
- **Search Schema**: Find tables/columns (avoid if possible - can be slow)
|
||||
|
||||
**Agent Tools:**
|
||||
- **Sub-Agent Call**: Invoke another agent and return results
|
||||
- **Custom Function**: Execute custom Python/JavaScript code
|
||||
|
||||
### Best Practices for Tool Documentation
|
||||
1. **Match names** between system prompt and tool specification exactly
|
||||
2. **Use snake_case** consistently
|
||||
3. **Provide examples** of inputs and outputs
|
||||
4. **Document errors** and how the tool handles them
|
||||
5. **Specify data types** for all parameters
|
||||
|
||||
---
|
||||
|
||||
## Section 10: Input/Output Format
|
||||
|
||||
Define how users interact with the agent and what they receive.
|
||||
|
||||
### Template
|
||||
|
||||
```markdown
|
||||
## Input/Output Format
|
||||
|
||||
### Input Format
|
||||
|
||||
**Language Request**: [Natural language or structured format]
|
||||
|
||||
**Sample Dialogue**:
|
||||
\```
|
||||
User: "[Example user query]"
|
||||
Agent: "[Agent's clarifying question if needed]"
|
||||
User: "[User's response]"
|
||||
\```
|
||||
|
||||
**Optional Parameters**:
|
||||
- `parameter_name`: [Description, constraints, default value]
|
||||
- `another_parameter`: [Description, constraints, default value]
|
||||
|
||||
### Output Format
|
||||
|
||||
**Output Type**: HTML / Plotly Graph / Markdown / JSON / Summarized Text
|
||||
|
||||
**Sample Output**:
|
||||
[Show representative example of what the user receives]
|
||||
|
||||
### Sample Conversation Flow
|
||||
|
||||
\```
|
||||
User: "Analyze my customer segments for Q4 2024"
|
||||
|
||||
Agent: "I'll analyze your customer segments. I can use RFM analysis, behavioral clustering, or both. Which would you prefer?"
|
||||
|
||||
User: "Both"
|
||||
|
||||
Agent: [Executes analysis]
|
||||
|
||||
Agent Output:
|
||||
# Customer Segmentation Analysis - Q4 2024
|
||||
|
||||
## RFM Segments
|
||||
[Table showing segments]
|
||||
|
||||
## Behavioral Clusters
|
||||
[Visualization showing clusters]
|
||||
|
||||
## Key Insights
|
||||
- [Insight 1]
|
||||
- [Insight 2]
|
||||
\```
|
||||
```
|
||||
|
||||
### Output Format Options
|
||||
|
||||
| Format | Best For | Example |
|
||||
|--------|----------|---------|
|
||||
| **HTML** | Structured presentation with formatting | Reports, dashboards, formatted tables |
|
||||
| **Plotly Graph** | Data visualizations | Charts, graphs, interactive visualizations |
|
||||
| **Markdown** | Text-heavy content with structure | Analysis summaries, documentation |
|
||||
| **JSON** | Programmatic consumption | API responses, data pipelines |
|
||||
| **Summarized Text** | Quick insights | Executive summaries, key findings |
|
||||
|
||||
---
|
||||
|
||||
## Section 11: User Prompts
|
||||
|
||||
User prompts guide the conversation and capture necessary information.
|
||||
|
||||
### Template
|
||||
|
||||
```markdown
|
||||
## User Prompt: [Prompt Name]
|
||||
|
||||
| Item | Details |
|
||||
|------|---------|
|
||||
| **User Prompt Name** | [Descriptive name indicating purpose] |
|
||||
| **Purpose** | [What this prompt accomplishes] |
|
||||
|
||||
### User Prompt Text
|
||||
|
||||
\```
|
||||
Step 1: [First question or instruction]
|
||||
- Option A: [Description]
|
||||
- Option B: [Description]
|
||||
- Option C: [Description]
|
||||
|
||||
Step 2: [Next question based on previous answer]
|
||||
[Continue step-by-step flow]
|
||||
|
||||
Step 3: [Final configuration]
|
||||
[Gather remaining details]
|
||||
\```
|
||||
|
||||
### Advanced Settings
|
||||
|
||||
**Pre-Configuration Checklist**:
|
||||
- [ ] [Configuration item 1]
|
||||
- [ ] [Configuration item 2]
|
||||
- [ ] [Configuration item 3]
|
||||
|
||||
**System Prompt Override** (if applicable):
|
||||
[Explain if/when system prompt can be customized by users]
|
||||
|
||||
### Sample Conversation
|
||||
|
||||
\```
|
||||
Agent: "Welcome! I can help you with customer segmentation. What would you like to do?
|
||||
1. Analyze existing segments
|
||||
2. Create new segments
|
||||
3. Compare segment performance"
|
||||
|
||||
User: "Analyze existing segments"
|
||||
|
||||
Agent: "Great! Which time period should I analyze?
|
||||
- Last 30 days
|
||||
- Last quarter
|
||||
- Last year
|
||||
- Custom date range"
|
||||
|
||||
User: "Last quarter"
|
||||
|
||||
Agent: "Analyzing your customer segments for Q3 2024..."
|
||||
[Proceeds with analysis]
|
||||
\```
|
||||
```
|
||||
|
||||
### User Prompt Best Practices
|
||||
|
||||
1. **Step-by-step flow**: Guide users through complex tasks incrementally
|
||||
2. **Clear options**: Provide specific choices rather than open-ended questions
|
||||
3. **Context**: Explain what each option does and why they'd choose it
|
||||
4. **Validation**: Include checks to ensure user input is valid
|
||||
5. **Defaults**: Suggest sensible defaults for common use cases
|
||||
|
||||
---
|
||||
|
||||
## Section 12: Development Roadmap
|
||||
|
||||
Track the agent's development milestones and future plans.
|
||||
|
||||
### Template
|
||||
|
||||
```markdown
|
||||
## Development Roadmap
|
||||
|
||||
### Milestones
|
||||
|
||||
| Phase | Date | Deliverables | Status |
|
||||
|-------|------|--------------|--------|
|
||||
| **Planning** | [Date] | Requirements, architecture design, team formation | ✅ Complete |
|
||||
| **Development** | [Date] | Core functionality, tools, system prompt | ✅ Complete |
|
||||
| **Testing** | [Date] | Unit tests, integration tests, user testing | ✅ Complete |
|
||||
| **Deployment** | [Date] | Production deployment, documentation, training | 🔄 In Progress |
|
||||
| **Enhancement** | [Date] | Feature additions, optimizations, feedback integration | 📅 Planned |
|
||||
|
||||
### Future Enhancements
|
||||
- [ ] [Planned feature 1]
|
||||
- [ ] [Planned feature 2]
|
||||
- [ ] [Planned feature 3]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section 13: Demo
|
||||
|
||||
Provide examples and demonstrations of the agent in action.
|
||||
|
||||
### Template
|
||||
|
||||
```markdown
|
||||
## Demo
|
||||
|
||||
### Input Example
|
||||
|
||||
\```
|
||||
User Query: "[Realistic example user input]"
|
||||
|
||||
Context:
|
||||
- [Relevant context or prerequisites]
|
||||
\```
|
||||
|
||||
### Output Example
|
||||
|
||||
\```
|
||||
[Show exactly what the agent returns]
|
||||
|
||||
[Include visualizations, formatted output, or screenshots]
|
||||
\```
|
||||
|
||||
### Video Recording
|
||||
|
||||
**Demo Video**: [Link to recording]
|
||||
**Duration**: [Length]
|
||||
**Covers**: [What the demo shows]
|
||||
|
||||
### Live Demo Access
|
||||
|
||||
**Demo Environment**: [Link if available]
|
||||
**Test Credentials**: [If applicable]
|
||||
**Sample Data**: [Link to sample data for testing]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Complete Documentation Example
|
||||
|
||||
Here's a concise example applying all the templates:
|
||||
|
||||
```markdown
|
||||
# Customer RFM Segmentation Agent
|
||||
|
||||
## Basic Information
|
||||
|
||||
| Item | Details |
|
||||
|------|---------|
|
||||
| **Project Name** | Customer RFM Segmentation Agent |
|
||||
| **Type** | Field Agent |
|
||||
| **Interface Type** | Chat |
|
||||
| **Status** | Production |
|
||||
| **Version** | 1.2.0 |
|
||||
| **Model** | Claude 4 Sonnet |
|
||||
| **Temperature** | 0 |
|
||||
|
||||
## Purpose & Functionality
|
||||
|
||||
### Description
|
||||
Automatically segments customers using RFM (Recency, Frequency, Monetary) analysis to identify high-value segments and at-risk customers.
|
||||
|
||||
### Business Value
|
||||
Enables 10x faster customer segmentation, improving campaign targeting by 35% and increasing marketing ROI.
|
||||
|
||||
## System Prompt: RFM Agent
|
||||
|
||||
# Customer RFM Segmentation Agent
|
||||
|
||||
Analyzes customer transaction data to create actionable segments.
|
||||
|
||||
# Role
|
||||
- Query customer transaction databases
|
||||
- Calculate RFM scores for each customer
|
||||
- Assign customers to segments based on scores
|
||||
- Generate visualizations and insights
|
||||
|
||||
# Goal
|
||||
Provide marketers with clear customer segments and actionable insights for targeted campaigns.
|
||||
|
||||
## Available Tools
|
||||
|
||||
### Database Access
|
||||
**Tool**: `verify_database_access`
|
||||
**Purpose**: Verify user has access to customer database
|
||||
**Input**: Database name
|
||||
**Output**: Access status (granted/denied)
|
||||
|
||||
### Data Retrieval
|
||||
**Tool**: `query_customer_transactions`
|
||||
**Purpose**: Retrieve customer transaction history
|
||||
**Input**: Database, table, date range
|
||||
**Output**: Transaction records with customer_id, date, amount
|
||||
|
||||
### RFM Calculation
|
||||
**Tool**: `calculate_rfm_scores`
|
||||
**Purpose**: Calculate Recency, Frequency, Monetary scores
|
||||
**Input**: Transaction data
|
||||
**Output**: RFM scores per customer
|
||||
|
||||
### Visualization
|
||||
**Tool**: `generate_segment_chart`
|
||||
**Purpose**: Create Plotly visualization of segments
|
||||
**Input**: Segment data
|
||||
**Output**: Plotly JSON chart specification
|
||||
|
||||
## Task Flow
|
||||
|
||||
### Task 1: Verify Access [required = true, mandatory_start = true]
|
||||
|
||||
**Steps** [sequential=true]:
|
||||
1. Call `verify_database_access` with customer database name
|
||||
2. If access denied, return error and stop
|
||||
3. If access granted, proceed to Task 2
|
||||
|
||||
### Task 2: Retrieve Transaction Data [required = true]
|
||||
|
||||
**Steps** [sequential=true]:
|
||||
1. Call `query_customer_transactions` with date range (default: last 365 days)
|
||||
2. Validate minimum 100 records returned
|
||||
3. If insufficient data, warn user and ask to expand date range
|
||||
4. Proceed to Task 3
|
||||
|
||||
### Task 3: Calculate RFM [required = true]
|
||||
|
||||
**Steps** [sequential=true]:
|
||||
1. Call `calculate_rfm_scores` with transaction data
|
||||
2. Assign scores 1-5 for Recency (days since last purchase)
|
||||
3. Assign scores 1-5 for Frequency (number of purchases)
|
||||
4. Assign scores 1-5 for Monetary (total revenue)
|
||||
5. Create segments based on score combinations:
|
||||
- Champions: RFM 5-5-5
|
||||
- Loyal: RFM 4-5-4 or 5-4-5
|
||||
- At Risk: RFM 2-3-3 or 3-2-3
|
||||
- Lost: RFM 1-1-1
|
||||
6. Proceed to Task 4
|
||||
|
||||
### Task 4: Generate Output [required = true]
|
||||
|
||||
**Steps** [parallel=true]:
|
||||
1. Call `generate_segment_chart` to create visualization
|
||||
2. Format summary statistics
|
||||
3. Compile key insights
|
||||
|
||||
**Output Format**:
|
||||
\```json
|
||||
{
|
||||
"segments": [
|
||||
{"name": "Champions", "count": 1250, "avg_revenue": 5200},
|
||||
{"name": "Loyal", "count": 2100, "avg_revenue": 3100}
|
||||
],
|
||||
"chart": { "plotly_json": "..." },
|
||||
"insights": ["45% of revenue from Champions (25% of customers)"]
|
||||
}
|
||||
\```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices Summary
|
||||
|
||||
### Documentation Do's ✅
|
||||
- Use clear, descriptive tool names in snake_case
|
||||
- Provide detailed pseudo-logic in system prompts
|
||||
- Include sample inputs and outputs for every tool
|
||||
- Keep documentation updated with code changes
|
||||
- Use semantic versioning
|
||||
- Include visual examples and demos
|
||||
- Document error handling explicitly
|
||||
|
||||
### Documentation Don'ts ❌
|
||||
- Don't use vague tool names (verify, list, query)
|
||||
- Don't write generic system prompts without details
|
||||
- Don't skip example conversations
|
||||
- Don't forget to update version numbers
|
||||
- Don't leave links broken or outdated
|
||||
- Don't omit dependencies or prerequisites
|
||||
- Don't publish without demo/video
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference: Tool Naming
|
||||
|
||||
| Purpose | Good Name | Bad Name |
|
||||
|---------|-----------|----------|
|
||||
| Verify database access | `verify_database_access` | `verify` |
|
||||
| List columns from customer DB | `list_columns_customer_db` | `listColumns` |
|
||||
| Query sales data | `query_sales_data` | `query` |
|
||||
| Calculate RFM scores | `calculate_rfm_scores` | `calcRFM` |
|
||||
| Generate visualization | `generate_segment_chart` | `makeChart` |
|
||||
|
||||
---
|
||||
|
||||
By following this comprehensive documentation template, your Field Agent documentation will be clear, consistent, and professional, making it easy for users to understand, deploy, and use your agents effectively.
|
||||
Reference in New Issue
Block a user