Otto Skills Writing Guide

> **Version**: 1.0.0 > **Last Updated**: 2025-11-04 > **Audience**: Skill authors, Otto contributors, domain experts

Version: 1.0.0
Last Updated: 2025-11-04
Audience: Skill authors, Otto contributors, domain experts

Introduction
What Are Skills?
When to Create a Skill
Skill Architecture
File Structure
Frontmatter Reference
Content Structure
Writing Effective Descriptions
Step-by-Step Creation Guide
Complete Skill Examples
Tool Integration
Testing Your Skill
Best Practices
Common Mistakes
Troubleshooting
Publishing & Sharing

Introduction

This guide teaches you how to create effective skills for Otto, an AI agent platform. Skills are markdown files that provide Otto with specialized knowledge, workflows, and best practices for specific domains or tasks.

What You'll Learn

How to structure skill files
Writing descriptions that match user intent
Creating actionable instructions
Integrating with Otto's tools
Testing and debugging skills
Best practices for skill authorship

Prerequisites

Basic understanding of Otto's architecture
Familiarity with Markdown syntax
YAML knowledge for frontmatter
Understanding of your skill's domain

What Are Skills?

Definition

Skills are modular knowledge packages that enhance Otto's capabilities in specific domains. They provide:

Structured workflows - Step-by-step processes
Best practices - DO/DON'T guidelines
Domain expertise - Specialized knowledge
Tool integration - How to use specific tools
Templates - Reusable patterns

How Skills Work

User Input: "Debug the API authentication error"
    ↓
┌─────────────────────────────────┐
│   Semantic Matching              │
│   - Embed user input             │
│   - Compare to skill descriptions│
│   - Rank by similarity           │
└─────────────────────────────────┘
    ↓
┌─────────────────────────────────┐
│   Skill Selection                │
│   "Systematic Debugging"         │
│   (similarity: 0.82)             │
└─────────────────────────────────┘
    ↓
┌─────────────────────────────────┐
│   Context Injection              │
│   - Load skill content           │
│   - Add to agent prompt          │
│   - Apply tool restrictions      │
└─────────────────────────────────┘
    ↓
Enhanced Agent Execution

Key Characteristics

Semantic Matching - Found automatically via embeddings
Context Injection - Added to agent's prompt
Tool Awareness - Can restrict available tools
Modular - One skill = one capability
Reusable - Applied across multiple tasks

When to Create a Skill

Good Candidates for Skills

✅ Structured Processes

Multi-step workflows
Methodologies (Agile, TDD, etc.)
Review processes
Troubleshooting procedures

✅ Domain Expertise

Industry-specific knowledge
Technical standards
Compliance requirements
Best practices

✅ Common Patterns

Recurring task types
Standard formats
Communication templates
Analysis frameworks

✅ Quality Gates

Code review criteria
Security checklists
Testing strategies
Documentation standards

Poor Candidates for Skills

❌ Simple Actions

Single tool calls
Basic file operations
Simple queries

❌ Overly General Knowledge

"How to use computers"
"General productivity tips"
Too broad to be actionable

❌ Constantly Changing Information

Real-time data
Current events
Version-specific details (unless versioned skills)

❌ Personal Preferences Without Rationale

"I like it this way"
No documented benefit
Arbitrary style choices

Decision Matrix

Scenario	Create Skill?	Why
4-phase debugging process	✅ Yes	Structured, reusable workflow
Professional email templates	✅ Yes	Common pattern with best practices
API design best practices	✅ Yes	Domain expertise, quality gates
"Send an email"	❌ No	Simple tool call
"Be nice"	❌ No	Too general, not actionable
Today's stock prices	❌ No	Real-time data, use tools instead

Skill Architecture

Directory Structure

skills/
├── category-name/
│   └── skill-name/
│       ├── SKILL.md           # Main skill file (required)
│       ├── templates/          # Optional templates
│       │   ├── template1.md
│       │   └── template2.md
│       ├── examples/           # Optional examples
│       │   └── example1.md
│       └── scripts/            # Optional helper scripts
│           └── helper.py

Skill Discovery Paths

Otto searches for skills in three locations (priority order):

Project Skills: skills/ (team-shared, in repo)
Global Skills: ~/.otto/skills/ (user-wide)
Plugin Skills: Via marketplace (future)

Recommendation:

Use project skills for team-specific workflows
Use global skills for personal productivity patterns

Category Organization

Organize skills into logical categories:

skills/
├── core/                    # Essential for all tasks
│   ├── task-planning/
│   └── context-gathering/
├── debugging/               # Troubleshooting
│   ├── systematic-debugging/
│   ├── performance-analysis/
│   └── security-testing/
├── communication/           # Writing and messaging
│   ├── email-writing/
│   ├── documentation/
│   └── meeting-facilitation/
├── data-analysis/           # Working with data
│   ├── report-generation/
│   ├── statistical-analysis/
│   └── visualization/
├── development/             # Software development
│   ├── code-review/
│   ├── test-writing/
│   └── refactoring/
└── project-management/      # Coordination
    ├── sprint-planning/
    ├── stakeholder-updates/
    └── risk-assessment/

File Structure

Anatomy of a Skill File

---
# YAML Frontmatter (Metadata)
name: Skill Name
description: When to use - critical for matching
category: category-name
version: 1.0.0
author: Author Name
tags:
  - keyword1
  - keyword2
allowed-tools:  # Optional
  - tool_name1
  - tool_name2
---
 
# Skill Title
 
## Overview
Brief introduction to the skill
 
## When to Use
Specific triggers and scenarios
 
## Core Content
Main instructions, workflows, templates
 
## Best Practices
DO/DON'T guidelines
 
## Integration with Tools
How to use Otto's tools with this skill
 
## Examples
Concrete demonstrations
 
## Remember
Key takeaways

Required Sections

Every skill MUST include:

Frontmatter - Metadata for matching and organization
Title - Clear, descriptive heading
When to Use - Explicit trigger conditions
Core Content - Main instructions/workflow
Best Practices - DO/DON'T guidelines

Recommended Sections

Enhance your skill with:

Overview - Brief introduction
Examples - Concrete demonstrations
Integration with Tools - Tool usage guidance
Remember - Key takeaways
Common Pitfalls - What to avoid
Further Reading - References

Frontmatter Reference

Required Fields

`name`

Type: String
Purpose: Display name for the skill
Guidelines:

Clear and descriptive
2-5 words ideal
Use title case
Unique within category

Examples:

name: Systematic Debugging
name: Professional Email Writing
name: API Security Review

`description`

Type: String
Purpose: CRITICAL - Used for semantic matching
Guidelines:

Be VERY specific with keywords
Include common user phrases
Mention trigger scenarios
Include technical terms
20-50 words ideal

Examples:

✅ Good:

description: Use when debugging issues, investigating errors, troubleshooting problems, or analyzing bugs. Provides a structured 4-phase approach to root cause analysis.

❌ Bad:

description: For debugging

Why the difference?

Good: Contains user phrases ("debugging issues", "investigating errors")
Good: Specific trigger words ("troubleshooting", "root cause analysis")
Bad: Too short, generic, won't match user queries

Optional Fields

`category`

Type: String
Purpose: Organization and filtering
Common Categories:

debugging
communication
data-analysis
development
project-management
security
testing

Example:

category: debugging

`version`

Type: String (Semantic Versioning)
Purpose: Track skill evolution
Format: MAJOR.MINOR.PATCH

Example:

version: 1.0.0
version: 2.1.3

When to increment:

MAJOR: Breaking changes (workflow restructure)
MINOR: New sections or features
PATCH: Fixes, typos, clarifications

`author`

Type: String
Purpose: Credit and contact

Examples:

author: Otto Team
author: Jane Smith
author: Security Team <security@company.com>

`tags`

Type: List of strings
Purpose: Additional keywords for discovery
Guidelines:

3-10 tags
Include synonyms
Technical terms
Related concepts

Example:

tags:
  - debugging
  - troubleshooting
  - root-cause
  - investigation
  - error-analysis
  - bug-fixing

`allowed-tools`

Type: List of tool names
Purpose: Restrict available tools when skill is active
Use Cases:

Read-only operations
Security-constrained tasks
Focused workflows

Example:

allowed-tools:
  - read_file
  - list_directory
  - ask_human

How it works:

If specified: ONLY these tools available
If omitted: All tools available (default)
Multiple skills: UNION (additive)

When to use:

✅ Code review (read-only)
✅ Security audit (no file writes)
✅ Analysis tasks (no modifications)
❌ Most skills (let Otto choose tools)

Complete Frontmatter Example

---
name: API Security Review
description: Use when reviewing API endpoints for security vulnerabilities, authentication issues, authorization problems, or security best practices. Provides comprehensive security checklist and common vulnerability patterns.
category: security
version: 1.2.0
author: Security Team <security@company.com>
tags:
  - security
  - api
  - authentication
  - authorization
  - vulnerabilities
  - OWASP
  - security-review
  - penetration-testing
allowed-tools:
  - read_file
  - list_directory
  - ask_human
---

Content Structure

Writing Principles

Be Specific - Concrete steps over abstract concepts
Be Actionable - Tell Otto what to DO
Be Complete - Include all necessary steps
Be Structured - Use headings, lists, emphasis
Be Clear - Simple language, short sentences

Markdown Formatting

Use Headers for Structure

# Skill Title (H1 - only once)
 
## Major Section (H2)
 
### Subsection (H3)
 
#### Detail Level (H4 - sparingly)

Use Lists for Steps

Numbered lists for sequential steps:

1. First step
2. Second step
3. Third step

Bullet lists for non-sequential items:

- Important point
- Another point
- Yet another point

Emphasize Key Information

**Bold** for important terms
*Italic* for emphasis
`code` for tool names, variables, technical terms

Use Code Blocks

```python
# For code examples
def example():
    return "formatted code"


#### Use Tables for Comparisons

```markdown
| Scenario | Action | Tool |
|----------|--------|------|
| Read file | Use read_file | `read_file` |
| Write file | Use write_file | `write_file` |

Use Blockquotes for Important Notes

> **Important**: Always check for X before doing Y

Section Templates

Overview Section

Purpose: Brief introduction (2-3 sentences)

## Overview
This skill provides [what it does]. Use this when [primary use case]. 
It helps by [key benefit].

Example:

## Overview
This skill provides a structured approach to debugging using a 4-phase methodology. 
Use this when investigating bugs, errors, or unexpected behavior. It prevents random 
trial-and-error by ensuring systematic root cause analysis.

When to Use Section

Purpose: Explicit trigger conditions

## When to Use
- [Specific scenario 1]
- [Specific scenario 2]
- [Specific scenario 3]
- [User phrase variant 1]
- [User phrase variant 2]

Example:

## When to Use
- Investigating bugs or errors
- Troubleshooting system issues
- Root cause analysis
- Post-incident investigation
- Performance problems
- Unexpected behavior

Guidelines:

5-10 specific triggers
Use user language ("debugging" not "defect remediation")
Include synonyms and variations
Be concrete, not abstract

Core Content (Main Instructions)

Purpose: The skill's primary content

For Workflows - Use numbered phases/steps:

## The [N]-Phase Process
 
### Phase 1: [Phase Name]
**Goal:** [What this phase accomplishes]
 
1. **[Step name]**
   - Specific action
   - Details
   - Examples
 
2. **[Next step]**
   - Actions
   - Details

For Guidelines - Use categorized lists:

## Guidelines
 
### Structure
- Guideline 1
- Guideline 2
 
### Style
- Guideline 3
- Guideline 4

For Templates - Show actual examples:

## Email Template
 
```markdown
Subject: [Clear specific subject]
 
Hi [Name],
 
[Purpose in first sentence]
 
[Details]
 
[Next steps]
 
Best,
[Your name]


---

#### Best Practices Section

**Purpose**: DO/DON'T guidelines

```markdown
## Best Practices

### DO:
- ✅ [Positive practice 1]
- ✅ [Positive practice 2]
- ✅ [Positive practice 3]

### DON'T:
- ❌ [Anti-pattern 1]
- ❌ [Anti-pattern 2]
- ❌ [Anti-pattern 3]

Example:

## Best Practices
 
### DO:
- ✅ Document everything as you investigate
- ✅ Test one hypothesis at a time
- ✅ Start with simple explanations
- ✅ Use version control for test changes
 
### DON'T:
- ❌ Skip phases (they build on each other)
- ❌ Make multiple changes at once
- ❌ Assume without testing
- ❌ Rush to conclusions

Integration with Tools Section

Purpose: Show how to use Otto's tools with this skill

## Integration with Tools
 
When [doing task], use appropriate tools:
- `tool_name` - [When and how to use]
- `tool_name` - [When and how to use]
- `tool_name` - [When and how to use]

Example:

## Integration with Tools
 
When debugging, use appropriate tools:
- `read_file` - Check code, logs, configuration files
- `list_directory` - Find relevant files in the codebase
- `ask_human` - Get clarification from team members (only when truly stuck)

Guidelines:

List relevant tools
Explain WHEN to use each
Explain HOW to use each
Use backticks for tool names

Examples Section

Purpose: Concrete demonstrations

## Examples
 
### Example 1: [Scenario]
**Situation:** [Context]
 
**Approach:**
1. [Step taken]
2. [Next step]
3. [Final step]
 
**Outcome:** [Result]
 
### Example 2: [Another scenario]
...

Example:

## Examples
 
### Example 1: Authentication Error
 
**Situation:** Users unable to log in, getting "401 Unauthorized"
 
**Approach:**
1. **Phase 1**: Gathered error logs, recent deployments
2. **Phase 2**: Noticed pattern - only users with long sessions
3. **Phase 3**: Tested hypothesis - token expiration issue
4. **Phase 4**: Updated token refresh logic, added test
 
**Outcome:** Authentication restored, regression prevented

Remember Section

Purpose: Key takeaways (2-5 points)

## Remember
 
Key principles:
1. [Main takeaway 1]
2. [Main takeaway 2]
3. [Main takeaway 3]
 
[Optional closing thought or quote]

Example:

## Remember
 
The systematic approach saves time by preventing:
- Random trial-and-error
- Fixing symptoms instead of root causes
- Breaking things further
- Repeating the same tests
 
Always complete all 4 phases, even if you think you found the issue early.

Writing Effective Descriptions

The description field is THE MOST CRITICAL part of your skill. It determines whether Otto will find and use your skill.

How Matching Works

User input embedded using the configured embedding model (Gemini, OpenAI, or Ollama)
Skill descriptions embedded (cached)
Cosine similarity computed
Top-K skills above threshold selected

Implication: Your description must semantically match user queries.

Description Formula

Use when [user phrases] [doing action], [variations], or [scenarios]. 
Provides [what skill offers] for [outcome/benefit].

Components:

User phrases - How users actually talk
Action variations - Synonyms and related terms
Scenarios - When they'd use it
Value proposition - What they get

Examples Analyzed

Example 1: Systematic Debugging

description: Use when debugging issues, investigating errors, troubleshooting problems, or analyzing bugs. Provides a structured 4-phase approach to root cause analysis.

What makes this good:

✅ "debugging issues" - exact user phrase
✅ "investigating errors" - synonym
✅ "troubleshooting problems" - another synonym
✅ "analyzing bugs" - yet another variant
✅ "4-phase approach" - specific method
✅ "root cause analysis" - technical term users know

Matches queries like:

"Debug the API error"
"Investigate authentication issue"
"Troubleshoot performance problem"
"Analyze production bug"

Example 2: Professional Email Writing

description: Use when composing emails to team members, clients, or stakeholders. Provides templates and guidelines for professional communication, email etiquette, and effective messaging.

What makes this good:

✅ "composing emails" - user action
✅ "team members, clients, stakeholders" - recipients
✅ "templates and guidelines" - what it provides
✅ "professional communication" - quality aspect
✅ "email etiquette" - specific domain
✅ "effective messaging" - outcome

Matches queries like:

"Write an email to the client"
"Compose professional message"
"Send update to stakeholders"

Example 3: API Security Review (fictional)

description: Use when reviewing API endpoints for security vulnerabilities, authentication issues, authorization problems, or security best practices. Provides comprehensive security checklist and common vulnerability patterns.

What makes this good:

✅ "reviewing API endpoints" - action + context
✅ "security vulnerabilities" - concern
✅ "authentication issues" - specific problem
✅ "authorization problems" - related problem
✅ "security best practices" - broader scope
✅ "comprehensive security checklist" - deliverable
✅ "common vulnerability patterns" - expertise

Matches queries like:

"Review API security"
"Check for authentication vulnerabilities"
"Audit endpoint authorization"
"Security best practices for API"

Common Description Mistakes

Mistake 1: Too Vague

❌ Bad:

description: For debugging

Problems:

Only 2 words
No variations or synonyms
No context or specifics
Won't match real queries

✅ Good:

description: Use when debugging issues, investigating errors, troubleshooting problems, or analyzing bugs. Provides a structured 4-phase approach to root cause analysis.

Mistake 2: Too Technical

❌ Bad:

description: Implements the PDCA cycle methodology for defect remediation utilizing root cause analysis taxonomies per ISO 9001 standards

Problems:

Users don't say "PDCA cycle" or "defect remediation"
Overly formal language
No common user phrases
Won't match natural queries

✅ Good:

description: Use when debugging issues or fixing bugs. Provides a systematic plan-do-check-act approach for root cause analysis and prevention.

Mistake 3: Too General

❌ Bad:

description: Helps with various programming tasks and software development activities

Problems:

"Various" and "activities" are too vague
Could match EVERYTHING
No specific triggers
No clear use case

✅ Good:

description: Use when reviewing code for bugs, security issues, or style violations. Provides code review checklist covering functionality, security, performance, and maintainability.

Mistake 4: Missing Variations

❌ Bad:

description: Use when composing emails

Problems:

Only one phrase
Misses "writing", "sending", "drafting"
Misses different email types
Limited matching potential

✅ Good:

description: Use when composing emails, writing messages, or sending communications to team members, clients, or stakeholders. Provides templates for professional correspondence.

Description Checklist

Use this checklist when writing descriptions:

Testing Your Description

Before publishing, test if your description would match target queries:

# Test queries that SHOULD match
test_queries = [
    "Debug the API error",
    "Investigate authentication problem",
    "Troubleshoot the bug",
    "Analyze production issue"
]
 
# Your description
description = "Use when debugging issues, investigating errors, troubleshooting problems, or analyzing bugs"
 
# Does description contain words from queries?
for query in test_queries:
    # Check for shared keywords
    # If no overlap, description needs work

Quick test: Read each test query. Does your description contain words from it?

Step-by-Step Creation Guide

Let's create a complete skill from scratch: "Code Review Checklist"

Step 1: Define the Skill Purpose

Questions to answer:

What problem does this solve?
When would someone use it?
What outcome do they want?

Our answers:

Problem: Inconsistent code reviews, missed issues
When: Reviewing pull requests, code changes
Outcome: Thorough, consistent review coverage

Step 2: Identify User Phrases

How will users ask for this?

Brainstorm:

"Review this code"
"Check the pull request"
"Code review for PR #123"
"Look at these changes"
"Review this function"
"Check for bugs"

Extract keywords:

review, check, look at
code, pull request, PR, changes, function
bugs, issues, problems

Step 3: Create the Directory Structure

mkdir -p skills/development/code-review-checklist
cd skills/development/code-review-checklist
touch SKILL.md

Step 4: Write the Frontmatter

---
name: Code Review Checklist
description: Use when reviewing code, checking pull requests, or analyzing code changes for bugs, security issues, style violations, or maintainability problems. Provides comprehensive review checklist covering functionality, security, performance, and code quality.
category: development
version: 1.0.0
author: Development Team
tags:
  - code-review
  - pull-request
  - quality
  - security
  - best-practices
  - bugs
allowed-tools:
  - read_file
  - list_directory
  - ask_human
---

Why these choices:

description: Contains user phrases + variations + specifics
category: "development" fits the domain
tags: Keywords for additional matching
allowed-tools: Read-only review (no modifications)

Step 5: Write the Content

# Code Review Checklist
 
## Overview
This skill provides a comprehensive checklist for reviewing code changes. Use this when reviewing pull requests, code changes, or investigating code quality issues. It ensures consistent, thorough reviews covering functionality, security, performance, and maintainability.
 
## When to Use
- Reviewing pull requests
- Code change analysis
- Pre-merge quality checks
- Security audits
- Refactoring reviews
- Mentoring junior developers
 
## Review Process
 
### 1. Understand the Context
 
Before reviewing code:
 
1. **Read the PR description**
   - What problem does it solve?
   - What approach was taken?
   - Are there any special considerations?
 
2. **Check the ticket/issue**
   - What were the requirements?
   - Are there edge cases mentioned?
   - Is there test data?
 
3. **Review related code**
   - What files are affected?
   - What are the dependencies?
   - Is there existing documentation?
 
### 2. Functionality Review
 
**Does the code work correctly?**
 
- [ ] Code solves the stated problem
- [ ] Handles edge cases appropriately
- [ ] Error handling is comprehensive
- [ ] No obvious bugs or logic errors
- [ ] Algorithm is correct and efficient
- [ ] Input validation is present
 
### 3. Security Review
 
**Is the code secure?**
 
- [ ] No SQL injection vulnerabilities
- [ ] No XSS vulnerabilities
- [ ] No hardcoded secrets or credentials
- [ ] User input is validated and sanitized
- [ ] Authentication/authorization checks present
- [ ] Sensitive data is encrypted
- [ ] No information leakage in errors
 
### 4. Performance Review
 
**Will this code perform well?**
 
- [ ] No N+1 query problems
- [ ] Appropriate use of indexes
- [ ] No unnecessary loops or recursion
- [ ] Database queries are optimized
- [ ] No memory leaks
- [ ] Caching used where appropriate
- [ ] Async operations where beneficial
 
### 5. Code Quality Review
 
**Is the code maintainable?**
 
- [ ] Code follows project style guide
- [ ] Variable names are clear and descriptive
- [ ] Functions are small and focused
- [ ] No code duplication
- [ ] Comments explain "why" not "what"
- [ ] Complex logic is documented
- [ ] No "magic numbers" or strings
 
### 6. Test Coverage Review
 
**Is the code adequately tested?**
 
- [ ] Unit tests cover main functionality
- [ ] Edge cases are tested
- [ ] Error conditions are tested
- [ ] Integration tests if needed
- [ ] Tests are clear and maintainable
- [ ] Test coverage is adequate (>80%)
- [ ] No flaky tests
 
### 7. Documentation Review
 
**Is the code documented?**
 
- [ ] Public APIs have documentation
- [ ] README updated if needed
- [ ] Inline comments for complex logic
- [ ] Examples provided if helpful
- [ ] Breaking changes documented
- [ ] Migration guide if needed
 
## Review Feedback Guidelines
 
### Providing Feedback
 
**Use constructive language**:
- ✅ "Consider using X here because..."
- ✅ "This could be improved by..."
- ✅ "Question: Why did you choose X over Y?"
- ❌ "This is wrong"
- ❌ "You should know better"
- ❌ "This is terrible"
 
**Categorize feedback**:
- **Critical** - Must be fixed (security, bugs)
- **Important** - Should be fixed (performance, maintainability)
- **Suggestion** - Nice to have (style preferences)
 
**Provide examples**:
```markdown
**Suggestion**: This loop could be more readable
 
Current:
```python
for i in range(len(items)):
    process(items[i])

Suggested:

for item in items:
    process(item)


## Best Practices

### DO:
- ✅ Review in multiple passes (functionality, then security, then style)
- ✅ Test the code locally if possible
- ✅ Ask questions when something is unclear
- ✅ Acknowledge good work ("Nice solution!")
- ✅ Focus on the code, not the person
- ✅ Provide specific, actionable feedback

### DON'T:
- ❌ Approve without actually reviewing
- ❌ Nitpick on style if auto-formatting exists
- ❌ Block on personal preferences
- ❌ Make it personal
- ❌ Overwhelm with too many comments
- ❌ Review when tired or rushed

## Integration with Tools

When reviewing code:
- `list_directory` - See what files were changed
- `read_file` - Read the changed files
- `ask_human` - Ask author for clarification if needed

## Common Issues to Watch For

### Security
- Hardcoded credentials
- Missing authentication checks
- SQL injection vectors
- XSS vulnerabilities

### Performance
- N+1 queries
- Missing database indexes
- Inefficient algorithms
- Memory leaks

### Quality
- Code duplication
- Overly complex functions
- Poor naming
- Missing error handling

## Remember

Code review is about:
1. **Catching bugs early** - Cheaper to fix now
2. **Knowledge sharing** - Everyone learns
3. **Maintaining quality** - Preventing technical debt
4. **Collaboration** - Building better software together

The goal is not perfection, but continuous improvement.

Step 6: Save and Test

Save the file as SKILL.md in your skill directory:

skills/development/code-review-checklist/SKILL.md

Step 7: Test Semantic Matching

Create a test script or use the API:

# Test matching
curl -X POST http://localhost:8000/api/skills/match \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Review this pull request",
    "threshold": 0.6,
    "max_skills": 3
  }'

Expected result: Your skill should appear in results with similarity > 0.6

Step 8: Test in Practice

Create a test task:

curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{
    "human_input": "Review the code in src/api/auth.py",
    "creator_id": "user-123"
  }'

Verify:

Skill was matched (check logs)
Skill context was injected (check LangSmith trace)
Otto followed the checklist (check task output)

Step 9: Iterate and Improve

Based on usage:

Did it match when expected?
- If no → improve description
Did Otto follow the guidance?
- If no → make instructions clearer
Did it provide value?
- If no → revise content

Update version number with each change:

1.0.0 → 1.0.1 (minor fix)
1.0.1 → 1.1.0 (added section)
1.1.0 → 2.0.0 (major restructure)

Complete Skill Examples

Example 1: Data Analysis Skill

---
name: Data Analysis Report
description: Use when analyzing data, generating reports, creating visualizations, or interpreting datasets. Provides structured approach for data exploration, statistical analysis, and insight generation.
category: data-analysis
version: 1.0.0
author: Data Team
tags:
  - analysis
  - reporting
  - statistics
  - visualization
  - insights
---
 
# Data Analysis Report
 
## Overview
This skill provides a structured approach to data analysis and report generation. Use when analyzing datasets, generating insights, or creating data-driven reports.
 
## When to Use
- Analyzing datasets
- Generating reports
- Creating visualizations
- Statistical analysis
- Trend identification
- Performance metrics analysis
 
## Analysis Process
 
### Phase 1: Data Understanding
 
1. **Examine the data source**
   - What data is available?
   - What format is it in?
   - What time period does it cover?
 
2. **Identify key metrics**
   - What are we measuring?
   - What are the KPIs?
   - What dimensions matter?
 
3. **Check data quality**
   - Any missing values?
   - Any outliers or anomalies?
   - Is the data complete?
 
### Phase 2: Exploratory Analysis
 
1. **Calculate summary statistics**
   - Mean, median, mode
   - Min, max, range
   - Standard deviation
   - Percentiles
 
2. **Identify patterns**
   - Trends over time
   - Correlations
   - Seasonality
   - Anomalies
 
3. **Segment the data**
   - By category
   - By time period
   - By demographic
   - By behavior
 
### Phase 3: Deep Dive Analysis
 
1. **Test hypotheses**
   - Why did X happen?
   - Is Y related to Z?
   - What caused the change?
 
2. **Compare segments**
   - Which segments perform best?
   - How do they differ?
   - What drives the differences?
 
3. **Calculate derived metrics**
   - Growth rates
   - Conversion rates
   - Ratios and percentages
 
### Phase 4: Report Generation
 
1. **Structure the report**
   - Executive summary
   - Key findings
   - Detailed analysis
   - Recommendations
 
2. **Create visualizations**
   - Choose appropriate chart types
   - Clear labels and titles
   - Consistent styling
 
3. **Write insights**
   - What did we learn?
   - Why does it matter?
   - What should we do?
 
## Report Structure Template
 
```markdown
# [Report Title]
 
## Executive Summary
[2-3 sentences highlighting key findings]
 
## Key Findings
1. [Finding 1 with supporting data]
2. [Finding 2 with supporting data]
3. [Finding 3 with supporting data]
 
## Data Overview
- **Dataset**: [Source and description]
- **Time Period**: [Date range]
- **Sample Size**: [N observations]
- **Key Metrics**: [List of metrics]
 
## Analysis
 
### [Section 1: Topic]
[Detailed analysis with visualizations]
 
**Key Insight**: [Main takeaway]
 
### [Section 2: Topic]
[Detailed analysis with visualizations]
 
**Key Insight**: [Main takeaway]
 
## Recommendations
1. [Action 1] - [Expected impact]
2. [Action 2] - [Expected impact]
3. [Action 3] - [Expected impact]
 
## Methodology
[How the analysis was conducted]
 
## Appendix
[Additional details, full datasets, technical notes]

Visualization Guidelines

Chart Type Selection

Data Type	Use Chart	Example
Trends over time	Line chart	Sales by month
Categories comparison	Bar chart	Revenue by region
Part-to-whole	Pie chart	Market share
Correlation	Scatter plot	Price vs demand
Distribution	Histogram	Customer ages

Chart Best Practices

✅ Clear, descriptive titles
✅ Labeled axes with units
✅ Legend when needed
✅ Consistent color scheme
✅ Remove chart junk
❌ 3D charts (misleading)
❌ Too many data series
❌ Unlabeled axes

Best Practices

DO:

✅ Start with questions, not data
✅ Document your assumptions
✅ Check for data quality issues
✅ Validate findings with multiple approaches
✅ Focus on actionable insights

DON'T:

❌ Cherry-pick data to support preconceptions
❌ Ignore outliers without investigation
❌ Confuse correlation with causation
❌ Over-complicate visualizations
❌ Present data without context

Integration with Tools

For data analysis:

read_file - Load datasets (CSV, JSON)
write_file - Save analysis results
convert_markdown_to_docx - Create report documents
attach_file - Attach reports for delivery to the user

Remember

Good analysis:

Answers specific questions
Provides actionable insights
Is backed by data
Considers context
Acknowledges limitations

The goal is insight, not just numbers.


---

### Example 2: Meeting Facilitation Skill

```yaml
---
name: Meeting Facilitation
description: Use when preparing for meetings, facilitating discussions, running workshops, or coordinating team sessions. Provides agenda templates, facilitation techniques, and best practices for productive meetings.
category: project-management
version: 1.0.0
author: PM Team
tags:
  - meetings
  - facilitation
  - workshops
  - agenda
  - coordination
  - communication
---

# Meeting Facilitation

## Overview
This skill provides guidelines and templates for effective meeting facilitation. Use when planning, preparing for, or running team meetings, workshops, or discussions.

## When to Use
- Planning meetings
- Creating agendas
- Facilitating discussions
- Running workshops
- Team coordination sessions
- Stakeholder presentations

## Meeting Preparation

### 1. Define the Purpose

**Answer these questions**:
- Why are we meeting?
- What decision needs to be made?
- What outcome do we want?
- Is a meeting necessary? (Could it be an email?)

### 2. Identify Participants

**Invite only who's needed**:
- Decision makers
- Subject matter experts
- Key stakeholders
- Anyone who needs to know

**Don't invite**:
- People who can read notes after
- "Just in case" attendees
- Large groups (max 8 for decisions)

### 3. Create the Agenda

**Agenda Template**:

```markdown
# [Meeting Title]

**Date**: [Date and time]
**Duration**: [Estimated length]
**Location**: [Room/Link]
**Attendees**: [Names and roles]

## Objective
[What we're trying to accomplish]

## Agenda

| Time | Topic | Owner | Type |
|------|-------|-------|------|
| 5min | Welcome & Context | [Name] | Info |
| 15min | [Topic 1] | [Name] | Discussion |
| 20min | [Topic 2] | [Name] | Decision |
| 10min | Next Steps | [Name] | Planning |

## Pre-Read Materials
- [Document 1] - [Purpose]
- [Document 2] - [Purpose]

## Expected Outcomes
- [ ] Decision on [topic]
- [ ] Plan for [next step]
- [ ] Action items assigned

4. Send Pre-Read Materials

24 hours before the meeting:

Send agenda
Share relevant documents
Include questions to consider
Set expectations

During the Meeting

Opening (5 minutes)

Welcome everyone
State the objective - Why we're here
Review the agenda - What we'll cover
Set ground rules:
- Start and end on time
- One conversation at a time
- Everyone participates
- Decisions are final

Facilitation Techniques

For Discussions:

Round robin - Everyone speaks once before anyone speaks twice
Parking lot - Table off-topic items for later
Dot voting - Quick consensus on multiple options
Silent brainstorming - Write ideas before sharing

For Decisions:

RACI clarity - Who decides? Who consults? Who is informed?
Thumbs vote - Quick temperature check (up/side/down)
Two-way doors - Reversible decisions need less debate
Disagree and commit - Not consensus, but alignment

For Participation:

Direct questions - "Alex, what do you think?"
Build on ideas - "Yes, and..." not "Yes, but..."
Summarize often - "What I'm hearing is..."
Track action items - Document in real-time

Handling Challenges

If discussion goes off-track:

"That's important, but let's parking lot it. Back to [topic]..."

If someone dominates:

"Thanks, Sarah. Let's hear from others. Kim, your thoughts?"

If energy is low:

"Let's take a 5-minute break and reconvene."

If conflict arises:

"I hear two different perspectives. Let's understand both..."

Closing (5 minutes)

Summarize decisions made
Review action items:
- What will be done?
- Who is responsible?
- By when?
Next steps and follow-ups
Thank everyone

After the Meeting

Send Meeting Notes (Within 24 hours)

# [Meeting Title] - Notes
 
**Date**: [Date]
**Attendees**: [Names]
 
## Decisions Made
1. [Decision 1] - [Context/rationale]
2. [Decision 2] - [Context/rationale]
 
## Action Items
| Action | Owner | Due Date | Status |
|--------|-------|----------|--------|
| [Action 1] | [Name] | [Date] | In Progress |
| [Action 2] | [Name] | [Date] | Not Started |
 
## Key Discussion Points
- [Point 1]
- [Point 2]
 
## Next Meeting
- **Date**: [Date]
- **Objective**: [Purpose]
 
## Parking Lot (For Future Discussion)
- [Topic 1]
- [Topic 2]

Meeting Types & Templates

1. Status Update Meeting

Purpose: Share progress, identify blockers Frequency: Weekly Duration: 30 minutes Structure:

Wins this week
Progress on goals
Blockers and risks
Priorities for next week

2. Decision-Making Meeting

Purpose: Make a specific decision Frequency: As needed Duration: 45-60 minutes Structure:

Context and background
Options with pros/cons
Discussion and questions
Decision and next steps

3. Brainstorming Session

Purpose: Generate ideas Frequency: As needed Duration: 60 minutes Structure:

Problem definition
Silent idea generation
Idea sharing (no judgment)
Grouping and prioritization

4. Retrospective

Purpose: Reflect and improve Frequency: End of sprint/project Duration: 60 minutes Structure:

What went well
What could improve
Action items for next time

Best Practices

DO:

✅ Start and end on time
✅ Have a clear agenda
✅ Document decisions and actions
✅ Assign owners to action items
✅ Follow up on commitments
✅ Limit meeting to 60 minutes max

DON'T:

❌ Schedule back-to-back meetings
❌ Multi-task during meetings
❌ Let discussions spiral
❌ Make decisions without key people
❌ Skip sending notes
❌ Have recurring meetings without reviewing value

Integration with Tools

For meetings:

write_file - Create agenda and notes
send_email - Send invites and follow-ups
ask_human - Get input from participants
convert_markdown_to_docx - Format meeting documents

Remember

Good meetings:

Have a clear purpose
Include the right people
Start and end on time
Result in decisions or actions
Are followed up with documentation

If a meeting has no purpose, it shouldn't happen.


---

## Tool Integration

### Understanding Otto's Tools

Otto provides 13 built-in tools that skills can reference. See the [Built-in Tools Reference](/docs/integrations/tools) for full details.

| Tool | Purpose | When Skills Use It |
|------|---------|-------------------|
| `ask_human` | Get human input | Clarification, approval, coordination |
| `send_email` | Send email | External communication |
| `read_file` | Read file contents | Reviewing code, checking configuration, analyzing logs |
| `write_file` | Create/update files | Saving analysis, creating drafts, storing results |
| `list_directory` | List files | Finding relevant files, checking what exists |
| `attach_file` | Mark file for delivery | Sending files to users on task completion |
| `read_document` | Read PDF/DOCX | Analyzing uploaded documents |
| `convert_markdown_to_docx` | MD to Word | Generating formal reports, documentation |
| `memory_search` | Search memory | Recalling past decisions, context, and knowledge |
| `memory_save` | Save to memory | Storing important facts for future retrieval |
| `dispatch_subagent` | Delegate subtasks | Breaking work into parallel subtasks |
| `run_skill_script` | Run skill scripts | Executing scripts bundled with skills |
| `wait` | Pause execution | Waiting for external processes or rate limits |

### How to Reference Tools in Skills

#### Pattern 1: Integration Section

```markdown
## Integration with Tools

When [doing task], use appropriate tools:
- `tool_name` - [When to use] - [How to use]
- `tool_name` - [When to use] - [How to use]

Example:

## Integration with Tools
 
When debugging:
- `read_file` - Check code, logs, or configuration files for clues
- `list_directory` - Find relevant files in the project structure
- `ask_human` - Get clarification from the code author (only when stuck)

Pattern 2: Inline Tool References

Use backticks when mentioning tools in instructions:

1. **Gather logs**
   - Use `read_file` to check application logs
   - Use `list_directory` to find log files

Pattern 3: Tool Workflows

Show complete tool usage sequences:

### Creating a Report
 
1. **Gather data**

list_directory("data/") # Find data files read_file("data/sales.csv") # Read the data


2. **Write report**

write_file("report.md", markdown_content) # Save as markdown


3. **Convert to Word**

convert_markdown_to_docx(markdown_content, "report.docx")


4. **Send to stakeholders**

send_email( recipients="stakeholder@company.com", subject="Q4 Sales Report", body="Please find attached...", attachments="report.docx" )

Tool Restrictions with `allowed-tools`

Restrict tools when skill requires limited scope:

allowed-tools:
  - read_file
  - list_directory
  - ask_human

Use cases:

Read-Only Analysis:

---
name: Code Review Checklist
allowed-tools:
  - read_file
  - list_directory
  - ask_human
---

Documentation Tasks:

---
name: Documentation Writing
allowed-tools:
  - read_file
  - write_file
  - list_directory
  - convert_markdown_to_docx
---

Communication Only:

---
name: Status Updates
allowed-tools:
  - ask_human
  - send_email
---

Best Practices for Tool Integration

DO:

✅ Mention tools explicitly by name using backticks
✅ Explain WHEN to use each tool
✅ Explain HOW to use each tool
✅ Show complete workflows
✅ Use allowed-tools for read-only or constrained tasks

DON'T:

❌ Assume Otto knows when to use tools
❌ Reference tools without context
❌ Use allowed-tools unnecessarily
❌ Forget that tools are asynchronous

# Check YAML is valid
cd skills/category/skill-name
head -20 SKILL.md
 
# Should see valid frontmatter

Test 2: Reload Skills

# Force Otto to reload skills
curl -X POST http://localhost:8000/api/skills/reload

Expected: Success response with skill count

Test 3: List Skills

# Verify skill appears
curl http://localhost:8000/api/skills/ | jq '.[] | select(.name=="Your Skill Name")'

Expected: Your skill in the list

Test 4: Test Matching

# Test semantic matching
curl -X POST http://localhost:8000/api/skills/match \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Your test query",
    "threshold": 0.6,
    "max_skills": 5
  }'

Expected: Your skill in results with decent similarity score (>0.6)

If not matching:

Description needs more keywords
Description too vague
Query not representative

Test 5: End-to-End Task Test

# Create a task that should match your skill
curl -X POST http://localhost:8000/api/task \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Your test task description",
    "creator_id": "test-user"
  }'

Verify in logs/LangSmith:

Skill was matched
Skill context was injected into prompt
Otto followed the skill guidance
Task outcome aligns with skill

Debugging Matching Issues

Issue: Skill doesn't match expected queries

Debug steps:

Check similarity scores:

curl -X GET "http://localhost:8000/api/skills/debug/similarity/your%20test%20query"

Look at your skill's score. If < 0.6, description needs work.

Compare descriptions:
- What words are in the query?
- Are those words in your description?
- Are there synonyms you're missing?
Test with exact description words:

curl -X POST http://localhost:8000/api/skills/match \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Words directly from your description",
    "threshold": 0.5
  }'

If THIS doesn't match, frontmatter might be invalid.

Check for YAML errors:

import yaml
 
with open('skills/category/skill/SKILL.md') as f:
    content = f.read()
    # Extract frontmatter between ---
    parts = content.split('---')
    frontmatter = parts[1]
    
try:
    data = yaml.safe_load(frontmatter)
    print("Valid YAML:", data)
except yaml.YAMLError as e:
    print("Invalid YAML:", e)

Issue: Skill matches wrong queries (false positives)

Solution: Make description MORE specific

Before (too general):

description: Use when working with data

After (more specific):

description: Use when analyzing CSV datasets for statistical trends, generating data reports, or creating visualizations for quarterly business reviews

Issue: Otto doesn't follow skill guidance

Possible causes:

Instructions too vague
Steps not actionable
Missing tool references
Content too long (LLM attention)

Solutions:

Make instructions more explicit
Use numbered steps, not paragraphs
Explicitly mention tools with backticks
Keep skill under 500 lines

A/B Testing Different Descriptions

Test multiple description variations:

# Version A (current)
description: Use when debugging issues or investigating errors
 
# Version B (more keywords)
description: Use when debugging issues, investigating errors, troubleshooting problems, analyzing bugs, or finding root causes of failures
 
# Version C (more context)
description: Use when debugging software issues, investigating production errors, troubleshooting application problems, or performing root cause analysis on bugs and failures. Provides systematic 4-phase approach.

Test each:

Update description
Reload skills
Test same queries
Compare similarity scores
Keep best performer

- Check the code
- Make improvements
- Consider quality

✅ Specific:

- Read the changed files using `read_file`
- Check for security vulnerabilities: SQL injection, XSS, hardcoded credentials
- Verify error handling covers all edge cases

2. Use Clear Structure

❌ Unstructured:

When reviewing code you should check for bugs and also look at performance and make sure security is good and tests exist and documentation is updated and style is consistent...

✅ Structured:

## Review Checklist
 
### 1. Functionality
- [ ] Code solves the problem
- [ ] Handles edge cases
- [ ] Error handling is present
 
### 2. Security
- [ ] No SQL injection vulnerabilities
- [ ] No hardcoded credentials
- [ ] Input validation present
 
### 3. Performance
- [ ] No N+1 queries
- [ ] Efficient algorithms
- [ ] Proper indexing

3. Provide Examples

❌ Abstract:

Use descriptive variable names

✅ Concrete:

Use descriptive variable names:
- ✅ `user_email` not `e`
- ✅ `total_price` not `tp`
- ✅ `is_authenticated` not `auth`

4. Balance Detail and Brevity

❌ Too short:

## Debug Process
1. Find bug
2. Fix it
3. Test

❌ Too long:

## Debug Process
 
The debugging process begins with a comprehensive analysis of all available data sources including but not limited to application logs (which should be examined at the DEBUG, INFO, WARN, and ERROR levels), system logs (particularly focusing on kernel messages, system daemon output, and hardware status indicators), database query logs (with particular attention to slow query logs and deadlock detection logs), network traces (capturing both inbound and outbound traffic at the packet level), and user reports (which should be carefully analyzed for patterns and commonalities)...

✅ Just right:

## Debug Process
 
### Phase 1: Gather Information
1. **Collect logs**
   - Application logs (all levels)
   - System logs (errors and warnings)
   - Database logs (slow queries)
   
2. **Reproduce the issue**
   - Document exact steps
   - Note environment details
   - Identify conditions that trigger it

Skill Organization

1. One Skill = One Capability

❌ Too broad:

name: Software Development Complete Guide
description: Everything about software development

✅ Focused:

# Separate skills:
name: Code Review Checklist
name: Test-Driven Development
name: Refactoring Patterns

2. Logical Category Structure

skills/
├── debugging/           # All debugging-related
│   ├── systematic-debugging/
│   ├── performance-profiling/
│   └── memory-leak-detection/
├── testing/             # All testing-related
│   ├── unit-testing/
│   ├── integration-testing/
│   └── test-data-generation/

3. Reference, Don't Duplicate

❌ Duplicate content:

# In skill A
## Email Best Practices
[Full email writing guide]
 
# In skill B
## Email Best Practices
[Same full email writing guide]

✅ Reference:

# In skill A
## Communication
For email best practices, see the "Professional Email Writing" skill.
 
# In skill B (dedicated skill)
# Professional Email Writing
[Full guide here]

Maintenance

1. Version Your Skills

version: 1.0.0  # Initial release
version: 1.0.1  # Fixed typo, added example
version: 1.1.0  # Added new section
version: 2.0.0  # Major restructure

2. Track Changes

Add a changelog at the bottom:

## Changelog
 
### 2.0.0 (2025-11-04)
- Restructured into 4-phase approach
- Added integration with tools section
- Updated examples
 
### 1.1.0 (2025-10-15)
- Added best practices section
- Added security checklist
 
### 1.0.0 (2025-10-01)
- Initial release

3. Review and Update Regularly

Monthly: Check if skill is being used (logs/metrics)
Quarterly: Update examples and references
Annually: Major review and restructure if needed

Common Mistakes

Mistake 1: Generic Descriptions

❌ Problem:

description: Helps with debugging

Why it's bad:

Only 3 words
No variations
Won't match real queries

✅ Fix:

description: Use when debugging software issues, investigating production errors, troubleshooting application problems, or performing root cause analysis on bugs and system failures. Provides structured 4-phase debugging methodology.

Mistake 2: No Clear Structure

❌ Problem:

# My Skill
 
Here's some information about the skill and how to use it and some best practices and examples and...

Why it's bad:

Wall of text
Hard to scan
Otto can't extract structured steps

✅ Fix:

# My Skill
 
## When to Use
- Scenario 1
- Scenario 2
 
## Process
 
### Step 1
Instructions...
 
### Step 2
Instructions...
 
## Best Practices
- DO this
- DON'T do that

Mistake 3: Missing "When to Use"

❌ Problem:

# Code Review
 
Here's how to review code...
[No "When to Use" section]

Why it's bad:

Not clear when skill applies
Harder for Otto to know context
Reduces matching confidence

✅ Fix:

# Code Review
 
## When to Use
- Reviewing pull requests
- Code change analysis
- Pre-merge quality checks
- Security audits

Mistake 4: Vague Instructions

❌ Problem:

1. Check the code
2. Look for problems
3. Fix issues

Why it's bad:

Not actionable
No specifics
Otto doesn't know what "problems" means

✅ Fix:

1. **Check functionality**
   - Read the changed files using `read_file`
   - Verify the code solves the stated problem
   - Test edge cases: empty input, null values, max limits
 
2. **Look for security issues**
   - Check for SQL injection: raw queries with user input
   - Check for XSS: unescaped user content in HTML
   - Check for hardcoded credentials: search for "password", "api_key"
 
3. **Fix critical issues**
   - Comment on the PR with specific line numbers
   - Provide example fix: "Change X to Y"
   - Mark as "Request Changes" if critical issues found

Mistake 5: Tool Restrictions Without Reason

❌ Problem:

allowed-tools:
  - read_file

Why it's bad:

Might need other tools
No flexibility
Breaks workflows

✅ Fix:

Option A - Remove restriction (let Otto choose):

# No allowed-tools field

Option B - Only restrict for good reason:

# For read-only code review
allowed-tools:
  - read_file
  - list_directory
  - ask_human

Mistake 6: Too Much Content

❌ Problem:

# My Skill
 
[3000 lines of detailed content]

Why it's bad:

LLM attention limits
Otto loses focus
Context window overflow

✅ Fix:

Option A - Split into multiple skills:

# Debugging (Core)
[300 lines - main workflow]
 
# Debugging (Security)
[300 lines - security focus]
 
# Debugging (Performance)
[300 lines - performance focus]

Option B - Use templates directory:

# Main skill
[300 lines - core content]
 
## Templates
See [templates/checklist.md](/docs/features/templates/checklist) for detailed checklist.

Mistake 7: No Examples

❌ Problem:

## Process
Follow the 4-phase methodology for systematic analysis.

Why it's bad:

Abstract
Hard to understand
Not actionable

✅ Fix:

## Process
 
### Example: Authentication Bug
 
**Phase 1**: Gathered error logs, noticed "401 Unauthorized" errors
**Phase 2**: Pattern - only affects users with >24h sessions
**Phase 3**: Tested token expiration hypothesis - confirmed
**Phase 4**: Updated token refresh logic, added test
 
**Outcome**: Bug fixed, regression prevented

Troubleshooting

Problem: Skill Not Loading

Symptoms:

Skill doesn't appear in /api/skills/
Reload doesn't help

Diagnosis:

Check file location:

ls -la skills/category/skill-name/SKILL.md

Must be exactly SKILL.md (case-sensitive).

Check YAML validity:

import yaml
with open('SKILL.md') as f:
    content = f.read()
    parts = content.split('---')
    if len(parts) < 3:
        print("Error: Frontmatter malformed")
    else:
        try:
            yaml.safe_load(parts[1])
            print("YAML valid")
        except Exception as e:
            print(f"YAML error: {e}")

Check file encoding:

file SKILL.md
# Should say: UTF-8 Unicode text

Check Otto logs:

docker logs otto-backend | grep -i "skill"

Look for parsing errors.

Solutions:

Fix YAML syntax errors
Ensure UTF-8 encoding
Check required fields present
Verify file named exactly SKILL.md

Problem: Skill Not Matching

Symptoms:

Skill appears in list
Doesn't match expected queries
Low similarity scores

Diagnosis:

# Check what scores your skill gets
curl -X GET "http://localhost:8000/api/skills/debug/similarity/your%20test%20query"

Solutions based on score:

Score < 0.3: Description completely wrong

Rewrite description with keywords from query
Add synonyms and variations
Include user phrases

Score 0.3-0.6: Close but not enough

Add more trigger keywords
Include technical terms
Add common user phrases

Score > 0.6 but still not matching: Threshold too high

Lower OTTO_SKILL_THRESHOLD (default 0.35)
Or improve description to get higher scores

Problem: False Positives

Symptoms:

Skill matches unrelated queries
Applied in wrong contexts
Too generic

Solution: Make description MORE specific

Before:

description: Use when working with code

After:

description: Use when reviewing pull requests for code quality, checking for bugs, security vulnerabilities, or performance issues in changed files. Not for writing new code.

Problem: Otto Doesn't Follow Skill

Symptoms:

Skill matched (confirmed in logs)
Context injected (confirmed in LangSmith)
Otto ignores guidance

Possible causes:

Instructions too vague - Make more specific
Too much content - LLM attention limit
No tool references - Otto doesn't know how to act
Conflicting with base prompt - Skill conflicts with Otto's core behavior

Solutions:

Make instructions explicit:

❌ "Check the code"
✅ "Use `read_file('src/api/auth.py')` to read the authentication code"

Reduce content length:

Remove fluff
Keep core instructions
Move details to templates

Add tool references:

When reviewing:
- Use `read_file` to check each changed file
- Use `ask_human` if logic is unclear

Avoid conflicts:

Don't contradict Otto's core behavior
Don't override fundamental instructions
Provide additive guidance

Project skills (skills/):

Committed to git repository
Shared automatically with team
Version controlled
Team can review changes

Setup:

# In your project repo
mkdir -p skills/your-category/your-skill
# Create SKILL.md
git add skills/
git commit -m "Add skill: your-skill"
git push

Team members get it:

git pull
# Otto auto-discovers on next task

Global skills (~/.otto/skills/):

Personal productivity patterns
Not project-specific
User-specific workflows

Setup:

mkdir -p ~/.otto/skills/your-category/your-skill
# Create SKILL.md

Share with others:

# Package skill
tar -czf my-skill.tar.gz ~/.otto/skills/your-category/your-skill/
 
# Share file (email, Slack, etc.)

Others install:

cd ~/.otto/skills/
tar -xzf my-skill.tar.gz

Contributing to Otto Marketplace (Future)

When marketplace is available:

Prepare skill:
- Ensure quality (test thoroughly)
- Add comprehensive documentation
- Include examples
- Add license (MIT, Apache, etc.)
Submit:
- Fork Otto skills repository
- Add skill to marketplace/ directory
- Create pull request
- Await review
Maintain:
- Respond to issues
- Update for new Otto versions
- Improve based on feedback

Skill Distribution Best Practices

1. Documentation

Include a README in skill directory:

# Skill Name
 
## Description
What this skill does
 
## Installation
How to install
 
## Usage
Example queries that match
 
## Author
Contact information
 
## License
MIT/Apache/etc.

2. Licensing

Add LICENSE file:

MIT License

Copyright (c) 2025 Your Name

Permission is hereby granted...

3. Examples

Include example tasks in README:

## Example Usage
 
**Query**: "Review this pull request"
 
**Expected behavior**:
- Skill matched
- Runs code review checklist
- Provides structured feedback

4. Version Information

Document versions and changes:

## Versions
 
### 2.0.0 (2025-11-04)
- Major restructure
- Added security checklist
 
### 1.0.0 (2025-10-01)
- Initial release

Match user intent semantically
Provide actionable guidance
Reference tools explicitly
Include concrete examples
Are focused and maintainable

The formula:

Description = User phrases + Variations + Specific triggers
Content = Clear structure + Actionable steps + Examples
Tools = Explicit references + When to use + How to use

Next Steps

Identify a domain or workflow you know well
Create your first skill using this guide
Test thoroughly with real queries and tasks
Iterate based on performance
Share with your team or community

Resources

Examples: skills/ in Otto repository
API Docs: http://localhost:8000/docs
LangSmith: https://smith.langchain.com for tracing
Support: Open issues on GitHub

Version: 1.0.0
Last Updated: 2025-11-04
License: MIT
Questions?: Open an issue or discussion on GitHub

Happy skill writing! 🎯