Build Your First Skill

Build Your First Skill

A step-by-step guide to creating and contributing a new skill to the Skene Skills Directory

This tutorial walks you through creating a simple skill from scratch. We'll build a competitor_mention_tracker skill that monitors mentions of competitors in customer conversations.

Table of Contents

• Prerequisites
• Step 1: Plan Your Skill
• Step 2: Set Up Your Environment
• Step 3: Create Skill Structure
• Step 4: Write skill.json
• Step 5: Write instructions.md
• Step 6: Run Security Analysis
• Step 7: Test Your Skill
• Step 8: Submit Your Skill
• Best Practices
• Security Checklist

Prerequisites

Required:

• Git installed
• Node.js 18+ installed
• Python 3.8+ installed (for security analysis)
• GitHub account

Helpful:

• Familiarity with JSON format
• Basic command line usage
• Understanding of the domain you're contributing to
• Understanding of what skills are and how they fit together

Step 1: Plan Your Skill

Before writing code, answer these questions:

What does your skill do?

Example: Tracks competitor mentions in customer conversations and emails

Which domain does it belong to?

Example: sales or customer_success

Available domains:

• sales - Pipeline, deals, CRM
• marketing - Campaigns, content, SEO
• customer_success - Health, churn, retention
• finops - Billing, revenue, financial
• product_ops - Roadmap, releases, features
• security - Security, compliance, auditing
• devex - Developer experience, tools
• plg - Product-led growth
• scientific - Research, data analysis
• ...and more

What are the inputs?

Example:

• conversation_id - ID of conversation to analyze
• competitors - List of competitor names to track
• time_range - Time period to analyze

What are the outputs?

Example:

• mentions_found - Number of competitor mentions
• competitor_breakdown - Mentions per competitor
• context - Surrounding text for each mention
• sentiment - Sentiment analysis (positive/negative/neutral)

What tools does it need?

Example:

• crm.conversations.read - Read conversation data
• ai.analyze_text - Analyze text for mentions
• ai.sentiment_analysis - Sentiment scoring

Step 2: Set Up Your Environment

# 1. Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/skene-cookbook.git
cd skene-cookbook

# 2. Install dependencies
npm install
pip install pyyaml jsonschema

# 3. Create a new branch
git checkout -b add-skill-competitor-mention-tracker

Step 3: Create Skill Structure

# Create skill directory
mkdir -p skills-library/sales/competitor_mention_tracker

# Navigate to it
cd skills-library/sales/competitor_mention_tracker

# Create required files
touch skill.json
touch instructions.md

Your structure should look like:

skills-library/sales/competitor_mention_tracker/
├── skill.json        # Skill definition and schema
└── instructions.md   # Execution instructions

Step 4: Write skill.json

Create skill.json with this template:

{
  "id": "sales_competitor_mention_tracker",
  "version": "1.0.0",
  "name": "Competitor Mention Tracker",
  "description": "Tracks and analyzes competitor mentions in customer conversations",
  "domain": "sales",

  "tools": [
    {
      "name": "crm.conversations.read",
      "required": true,
      "description": "Read conversation history from CRM"
    },
    {
      "name": "ai.analyze_text",
      "required": true,
      "description": "Analyze text for keyword mentions"
    },
    {
      "name": "ai.sentiment_analysis",
      "required": false,
      "description": "Analyze sentiment of mentions"
    }
  ],

  "inputSchema": {
    "type": "object",
    "required": ["conversation_id", "competitors"],
    "properties": {
      "conversation_id": {
        "type": "string",
        "description": "ID of the conversation to analyze"
      },
      "competitors": {
        "type": "array",
        "items": { "type": "string" },
        "description": "List of competitor names to track",
        "example": ["Competitor A", "Competitor B"]
      },
      "time_range": {
        "type": "string",
        "enum": ["7d", "30d", "90d", "all"],
        "default": "30d",
        "description": "Time range for analysis"
      },
      "include_sentiment": {
        "type": "boolean",
        "default": true,
        "description": "Whether to include sentiment analysis"
      }
    }
  },

  "outputSchema": {
    "type": "object",
    "properties": {
      "total_mentions": {
        "type": "integer",
        "description": "Total number of competitor mentions found"
      },
      "competitor_breakdown": {
        "type": "object",
        "description": "Mentions count per competitor",
        "additionalProperties": { "type": "integer" }
      },
      "mentions": {
        "type": "array",
        "description": "Detailed mention data",
        "items": {
          "type": "object",
          "properties": {
            "competitor": { "type": "string" },
            "context": { "type": "string" },
            "timestamp": { "type": "string", "format": "date-time" },
            "sentiment": {
              "type": "string",
              "enum": ["positive", "neutral", "negative"]
            }
          }
        }
      },
      "summary": {
        "type": "string",
        "description": "AI-generated summary of findings"
      }
    }
  },

  "exitStates": {
    "mentions_found": {
      "description": "Competitor mentions were found",
      "nextRecommendation": ["competitive_analysis", "competitive_battlecard"]
    },
    "no_mentions": {
      "description": "No competitor mentions found",
      "nextRecommendation": null
    },
    "error": {
      "description": "Error during analysis",
      "nextRecommendation": null
    }
  },

  "tags": ["sales", "competitive-intelligence", "conversation-analysis", "sentiment-analysis"],

  "jobFunctions": ["sales_ops", "competitive_intelligence", "product_marketing"],

  "platforms": {
    "claude": {
      "triggers": [
        "track competitor mentions",
        "analyze competitor mentions in conversation",
        "find competitor references"
      ]
    },
    "cursor": {
      "triggers": ["competitor_mention_tracker"]
    }
  }
}

Key Fields Explained:

• id: Unique identifier in format domain_skill_name
• tools: External tools this skill needs (CRM, AI, etc.)
• inputSchema: What data the skill expects (with validation)
• outputSchema: What data the skill returns
• exitStates: Possible outcomes and recommended next skills
• tags: Searchable keywords
• jobFunctions: Who would use this skill
• platforms: How users invoke the skill in Claude/Cursor

Step 5: Write instructions.md

Create instructions.md with clear execution steps:

# Competitor Mention Tracker

## Purpose

Automatically tracks and analyzes competitor mentions in customer conversations, providing insights into competitive dynamics and customer sentiment.

## When to Use

- **Competitive intelligence**: Track how often competitors come up
- **Deal risk assessment**: Identify deals with competitive pressure
- **Product positioning**: Understand how customers compare products
- **Win/loss analysis**: Correlate competitor mentions with outcomes

## Prerequisites

### Required Tools

- `crm.conversations.read` - Access to conversation history
- `ai.analyze_text` - Text analysis capability

### Optional Tools

- `ai.sentiment_analysis` - For sentiment scoring

### Data Access

- Read access to CRM conversation data
- List of competitor names to track

## Execution Steps

### 1. Fetch Conversation Data

- Retrieve conversation history for given `conversation_id`
- Filter by `time_range` if specified
- Pull full conversation thread (not just summary)

### 2. Analyze for Competitor Mentions

For each competitor in `competitors` list:

- Search conversation text for mentions (case-insensitive)
- Include variations (e.g., "Acme", "Acme Corp", "Acme Software")
- Extract surrounding context (±50 words)
- Record timestamp of mention

### 3. Sentiment Analysis (if enabled)

For each mention found:

- Analyze sentiment of context (positive/neutral/negative)
- Score confidence (0-1)
- Flag highly positive or negative mentions

### 4. Generate Summary

- Count total mentions
- Break down by competitor
- Identify patterns or trends
- Generate actionable summary

### 5. Return Results

Exit with appropriate state:

- `mentions_found`: If 1+ mentions detected
- `no_mentions`: If 0 mentions found
- `error`: If analysis failed

## Example Usage

### Input

\`\`\`json
{
"conversation_id": "conv_12345",
"competitors": ["Competitor A", "Competitor B"],
"time_range": "30d",
"include_sentiment": true
}
\`\`\`

### Output

\`\`\`json
{
"total_mentions": 3,
"competitor_breakdown": {
"Competitor A": 2,
"Competitor B": 1
},
"mentions": [
{
"competitor": "Competitor A",
"context": "We looked at Competitor A but their pricing was too high...",
"timestamp": "2026-01-15T10:30:00Z",
"sentiment": "negative"
},
{
"competitor": "Competitor A",
"context": "Competitor A has a nice feature for reporting...",
"timestamp": "2026-01-20T14:15:00Z",
"sentiment": "positive"
},
{
"competitor": "Competitor B",
"context": "Currently using Competitor B but not satisfied...",
"timestamp": "2026-01-25T09:00:00Z",
"sentiment": "negative"
}
],
"summary": "3 competitor mentions found. Customer evaluated Competitor A (pricing concerns) and is currently using Competitor B with dissatisfaction. Opportunity to position on price/value and switching benefits."
}
\`\`\`

## Error Handling

### Common Errors

**Error: Conversation not found**

- Cause: Invalid `conversation_id`
- Solution: Verify conversation ID exists in CRM
- Exit state: `error`

**Error: Insufficient permissions**

- Cause: Missing read access to conversations
- Solution: Grant `crm.conversations.read` permission
- Exit state: `error`

**Error: Rate limit exceeded**

- Cause: Too many API calls to CRM
- Solution: Implement rate limiting, retry with backoff
- Exit state: `error`

## Security Considerations

### Data Access

- **Scope**: Read-only access to conversation data
- **Sensitivity**: May contain customer PII and confidential discussions
- **Retention**: Do not store conversation data beyond analysis

### Risk Level

**Medium** - Accesses customer conversation data

### Required Security Controls

- ✅ Audit logging enabled
- ✅ Read-only access (no modifications)
- ⚠️ Recommend human review for sensitive accounts

### Compliance Notes

- Ensure compliance with data retention policies
- Mask PII in exported reports if required
- Log all access for audit trails

## Recommended Next Skills

If `mentions_found`:

- `competitive_battlecard` - Generate battle card for mentioned competitor
- `competitive_analysis` - Deep dive into competitive positioning
- `win_loss_analyzer` - Correlate mentions with deal outcomes

## Performance Notes

- **Typical execution time**: 2-5 seconds per conversation
- **Rate limits**: Respects CRM API limits (typically 100 req/min)
- **Scalability**: Can batch process up to 100 conversations/run

## Version History

- **v1.0.0** (2026-02-06): Initial release

Step 6: Run Security Analysis

Run the security analysis tool:

# From repository root
python scripts/analyze_skills.py --action metadata

# This generates metadata.yaml in your skill directory

Review the generated metadata.yaml:

risk_level: 'Medium'
security_requirements:
  audit_logging: true
  read_only: true
  human_in_loop_recommended: true
  data_access_scope:
    - 'customer_conversations'
    - 'crm_data'

job_function: 'sales_ops'
jtbd: 'Track competitive mentions in customer conversations'

Risk Levels:

• Low: Read-only, public data, no credentials
• Medium: Read-only, internal data, some credentials
• High: Write operations, financial data, PII access
• Critical: Destructive operations, payment processing

Step 7: Test Your Skill

Manual Testing

1. Validate JSON syntax:

   cat skill.json | python -m json.tool
   

2. Check schema compliance (future feature):

   npm run validate:skill skills-library/sales/competitor_mention_tracker/skill.json
   

3. Test with sample data:

   • Create test input matching your inputSchema
   • Verify outputs match outputSchema
   • Test error cases

Testing Checklist

• JSON is valid and well-formatted
• All required fields present
• inputSchema has examples
• outputSchema is complete
• instructions.md has clear steps
• Error handling documented
• Security considerations listed
• Exit states defined

Step 8: Submit Your Skill

1. Commit Your Changes

# Add your skill files
git add skills-library/sales/competitor_mention_tracker/

# Commit with descriptive message
git commit -m "feat: add competitor_mention_tracker skill to sales domain

- Tracks competitor mentions in conversations
- Includes sentiment analysis
- Medium risk level (read-only access to CRM data)
- Tested with sample conversations"

# Push to your fork
git push origin add-skill-competitor-mention-tracker

2. Create Pull Request

Go to GitHub and create a PR with this template:

## Skill Addition: Competitor Mention Tracker

**Domain:** sales
**Risk Level:** Medium
**Job Function:** sales_ops, competitive_intelligence

### Description

Tracks and analyzes competitor mentions in customer conversations with sentiment analysis. Helps sales teams understand competitive dynamics and position against alternatives.

### Key Features

- Searches conversation history for competitor names
- Extracts context around each mention
- Sentiment analysis (positive/neutral/negative)
- Actionable summary of findings
- Recommended next skills for follow-up

### Security Analysis

**Risk Level**: Medium

- Read-only access to customer conversation data
- No write operations
- Audit logging enabled
- PII considerations in conversation content

**Required Controls**:

- ✅ Audit logging
- ✅ Read-only access
- ⚠️ Human review recommended for sensitive accounts

### Testing

- [x] Tested standalone execution with sample data
- [x] Validated input/output schemas
- [x] Ran security analysis
- [x] Tested error handling (invalid IDs, rate limits)
- [x] Verified exit states work correctly

### Use Cases

1. **Deal Risk Assessment**: Identify deals with strong competitive pressure
2. **Win/Loss Analysis**: Correlate competitor mentions with outcomes
3. **Competitive Intelligence**: Track which competitors are most mentioned
4. **Product Positioning**: Understand how customers compare products

### Checklist

- [x] skill.json follows schema
- [x] instructions.md is complete and clear
- [x] metadata.yaml generated from security analysis
- [x] No security vulnerabilities
- [x] Examples provided
- [x] Exit states defined with recommendations
- [x] Tags and job functions assigned

3. Wait for Review

Maintainers will review your skill for:

• ✅ Schema compliance
• ✅ Security requirements
• ✅ Documentation quality
• ✅ Use case value

Typical review time: 3-5 business days

Best Practices

DO ✅

• Be atomic: One skill = one clear purpose
• Be specific: Clear inputs, outputs, and behavior
• Document thoroughly: Examples, errors, security
• Think composable: Define exit states and next skill recommendations
• Test extensively: Multiple scenarios, error cases
• Consider security: Always run security analysis

DON'T ❌

• Don't be vague: Avoid unclear descriptions
• Don't skip schemas: Always define input/output schemas
• Don't ignore security: Always complete security analysis
• Don't bypass reviews: Security checks are mandatory
• Don't copy proprietary code: Respect IP and licenses

Security Checklist

Before submitting, verify:

• Risk level assessed (Low/Medium/High/Critical)
• Data access scope documented
• Security requirements defined
• No hardcoded credentials or secrets
• Audit logging specified if needed
• Human-in-loop requirement noted if applicable
• PII handling documented
• Destructive operations flagged (if any)
• Rate limiting considered
• Error messages don't leak sensitive info

Need Help?

• Questions about skill structure: See CONTRIBUTING.md
• Security questions: See SECURITY_POLICY.md
• Technical issues: Open an issue
• Discussions: GitHub Discussions

Next Steps

After your skill is merged:

1. Test in production: Install and use your skill
2. Create skill chains: Combine with other skills
3. Share your workflow: Add to SHOWCASE.md
4. Iterate: Improve based on usage feedback

Thank you for contributing to Skene Skills Directory! 🎉

Every skill you add makes AI agents more powerful for everyone.