esa Search Skill

This skill enables you to search and retrieve information from esa.io team using the esa-cli command-line tool.

Prerequisites

Before using this skill, ensure:

1. ESA_TEAM environment variable is set with your esa team name
2. ESA_ACCESS_TOKEN environment variable is set with a valid esa access token
3. The esa-cli binary is available in PATH or installed locally

Available Commands

1. Get Team Information

Retrieve information about your esa team:

esa-cli team

Example Output:

================================================================================
Team Information
================================================================================

Name: your-team
Privacy: closed
Description: Team description here
URL: https://your-team.esa.io

================================================================================

2. Search Posts

Search for posts containing specific keywords across your team:

esa-cli search "<query>"

Options:

• --page=N: Page number (default: 1)
• --per-page=N: Number of results per page (default: 20, max: 100)
• --sort=ORDER: Sort order - updated (default), created, stars, watches, comments, best_match

Query Filters:

• category:<name>: Filter by category (e.g., category:dev/api)
• tag:<name>: Filter by tag (e.g., tag:important)
• user:<name>: Filter by user (e.g., user:username)
• kind:<type>: Filter by kind - stock or flow

Examples:

# Basic search
esa-cli search "API documentation"

# Search by category
esa-cli search "category:dev/api"

# Search by tag
esa-cli search "tag:important"

# Combined filters
esa-cli search "category:dev/api tag:important"

# Search with pagination and sort
esa-cli search "database" --page=2 --per-page=50 --sort=stars

# Search by user
esa-cli search "user:john.doe"

# Search by kind
esa-cli search "kind:stock"

3. Get Specific Post

Retrieve a specific post by its number:

esa-cli get <post-number>

Example:

# Get post #123
esa-cli get 123

Output includes:

• Post title and full name
• Category and tags
• Created and updated timestamps
• Full Markdown body content
• Post URL

4. Get Posts by Category

Retrieve all posts in a specific category:

esa-cli category "<category-name>"

Options:

• --page=N: Page number
• --per-page=N: Results per page
• --sort=ORDER: Sort order

Examples:

# Get posts in "dev/api" category
esa-cli category "dev/api"

# With pagination
esa-cli category "docs" --page=2 --per-page=30

# Sort by creation date
esa-cli category "team/meeting" --sort=created

5. Get Posts by Tag

Retrieve all posts with a specific tag:

esa-cli tag "<tag-name>"

Options:

• --page=N: Page number
• --per-page=N: Results per page
• --sort=ORDER: Sort order

Examples:

# Get posts tagged "important"
esa-cli tag "important"

# With pagination and sort
esa-cli tag "release" --page=1 --per-page=50 --sort=stars

Output Format

Search Results Format

Found N posts:
================================================================================

[1] #123 Post Title
Full Name: Category/Subcategory/Post Title
Updated: 2024-01-15T10:30:00
URL: https://your-team.esa.io/posts/123
Category: Category/Subcategory
Tags: tag1, tag2, tag3

[2] #124 Another Post
...

================================================================================
Page 1 (Total: 50 posts, 20 per page)

Post Detail Format

================================================================================
Post #123: Post Title
================================================================================

Full Name: Category/Subcategory/Post Title
Category: Category/Subcategory
Tags: tag1, tag2, tag3
Created: 2024-01-01T09:00:00
Updated: 2024-01-15T10:30:00
URL: https://your-team.esa.io/posts/123

--- Body (Markdown) ---

# Post Content

Your markdown content here...

================================================================================

Usage Guidelines

When to Use This Skill

Use this skill when you need to:

• Find specific information in your esa knowledge base
• Retrieve documentation or technical notes
• Search for posts by category or topic
• Get the latest updates in specific areas
• Access full content of specific posts
• Browse team knowledge base

Best Practices

1. Use Specific Search Terms: Use precise keywords to get relevant results
2. Leverage Categories: When you know the category, use category search for better results
3. Use Tags for Topics: Tags are great for cross-category topic searches
4. Adjust Page Size: Increase --per-page if you need more results at once
5. Sort Appropriately: Use --sort=best_match for keyword relevance, --sort=updated for recency
6. Check Post Numbers: Note post numbers from search results to fetch full content later

Common Use Cases

Finding API Documentation:

esa-cli search "API" --sort=best_match
esa-cli category "dev/api"

Checking Recent Updates:

esa-cli search "category:team/meeting" --sort=updated --per-page=10

Getting Team Guidelines:

esa-cli category "team/guidelines"

Finding Important Announcements:

esa-cli tag "important"
esa-cli tag "announcement"

Reading Specific Post:

# First, search to find the post number
esa-cli search "onboarding guide"

# Then, get the full content
esa-cli get 456

Investigating Topics:

# Search broadly
esa-cli search "database migration"

# Check specific category
esa-cli category "dev/database"

# Check related tags
esa-cli tag "migration"

Browsing Popular Posts:

esa-cli search "*" --sort=stars --per-page=20

Error Handling

Common Errors and Solutions

1. "ESA_TEAM environment variable is not set"

   • Set the environment variable: export ESA_TEAM=your-team-name

2. "ESA_ACCESS_TOKEN environment variable is not set"

   • Set the environment variable: export ESA_ACCESS_TOKEN=your-token
   • Get your token from: https://[your-team].esa.io/user/applications

3. "esa API HTTP Error"

   • Verify your access token is valid and not expired
   • Check that your team name is correct
   • Ensure the token has appropriate read permissions

4. "No posts found"

   • Try broader search terms
   • Check if the category or tag name is correct (case-sensitive)
   • Verify you have access to the content

5. Post not found (when using get)

   • Verify the post number is correct
   • Check if the post was deleted or archived
   • Ensure you have permission to view the post

Access Token Setup

Creating an Access Token

1. Visit https://[your-team].esa.io/user/applications
2. Click "Generate new token"
3. Select at minimum the following scopes:
   • read - Read posts and team information
4. Generate the token and copy it
5. Set it as an environment variable:

   export ESA_ACCESS_TOKEN=your-token-here
   

Storing Credentials Securely

Add to your shell configuration file (.bashrc, .zshrc, etc.):

export ESA_TEAM=your-team-name
export ESA_ACCESS_TOKEN=your-access-token

Or use direnv with .envrc:

export ESA_TEAM=your-team-name
export ESA_ACCESS_TOKEN=your-access-token

Limitations

• Read-Only: This CLI only supports read operations (no post creation/editing/deletion)
• Permissions: Only accesses content you have permission to read
• Rate Limits: esa API has rate limits; avoid rapid consecutive requests
• Page Size: Maximum 100 posts per page
• Search Scope: Searches are limited to your team's content

Tips for Effective Searching

1. Start with Categories: If you know the category structure, use category search
2. Use Tags for Themes: Tags often represent cross-cutting themes or projects
3. Combine Filters: Use multiple filters together for precise results
4. Sort by Relevance: Use --sort=best_match when keyword matching is crucial
5. Sort by Time: Use --sort=updated or --sort=created for chronological browsing
6. Iterate Searches: Start broad, note interesting post numbers, then fetch full content
7. Check Pagination: If you don't see what you're looking for, check the next page

Integration with Workflows

This skill works well in combination with other tasks:

• Search esa → Find relevant documentation → Summarize for current task
• Get post → Extract code examples → Apply to implementation
• Search by tag → Compile related information → Create comprehensive guide
• Browse categories → Identify knowledge gaps → Suggest new documentation
• Find team guidelines → Ensure compliance → Propose improvements

Example Workflow: Researching a Topic

# Step 1: Broad search to understand scope
esa-cli search "authentication"

# Step 2: Check specific category
esa-cli category "dev/security"

# Step 3: Look for related tags
esa-cli tag "auth"

# Step 4: Get full content of relevant posts
esa-cli get 123
esa-cli get 456

# Step 5: Check for recent updates
esa-cli search "category:dev/security" --sort=updated --per-page=5