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:

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

Available Commands

1. Get Team Information

Retrieve information about your esa team:

bash

esa-cli team

Example Output:

code

================================================================================
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:

bash

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:

bash

# 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:

bash

esa-cli get <post-number>

Example:

bash

# 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:

bash

esa-cli category "<category-name>"

Options:

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

Examples:

bash

# 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:

bash

esa-cli tag "<tag-name>"

Options:

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

Examples:

bash

# 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

code

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

code

================================================================================
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

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

Common Use Cases

Finding API Documentation:

bash

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

Checking Recent Updates:

bash

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

Getting Team Guidelines:

bash

esa-cli category "team/guidelines"

Finding Important Announcements:

bash

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

Reading Specific Post:

bash

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

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

Investigating Topics:

bash

# 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:

bash

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

Error Handling

Common Errors and Solutions

•
"ESA_TEAM environment variable is not set"
- •Set the environment variable: export ESA_TEAM=your-team-name
•
"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
•
"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
•
"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
•
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

•Visit https://[your-team].esa.io/user/applications
•Click "Generate new token"
•
Select at minimum the following scopes:
- •read - Read posts and team information
•Generate the token and copy it

•Set it as an environment variable:

bash

export ESA_ACCESS_TOKEN=your-token-here

Storing Credentials Securely

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

bash

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

Or use direnv with .envrc:

bash

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

•Start with Categories: If you know the category structure, use category search
•Use Tags for Themes: Tags often represent cross-cutting themes or projects
•Combine Filters: Use multiple filters together for precise results
•Sort by Relevance: Use --sort=best_match when keyword matching is crucial
•Sort by Time: Use --sort=updated or --sort=created for chronological browsing
•Iterate Searches: Start broad, note interesting post numbers, then fetch full content
•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

bash

# 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