@devrev-computer/skills 1.0.0

package/skills/customer-brief/customer-brief.md

@@ -0,0 +1,66 @@
+---
+skill-name: customer-brief
+user-invocable: true
+description: Produce a structured pre-meeting briefing report combining internal and external intelligence. Use when user says "customer brief", "customer briefing", "prep for meeting with [company]", "briefing for [customer]", or "pre-call brief".
+arguments:
+  - name: customer
+    description: The customer/account name to prepare a briefing for
+    required: true
+---
+
+# CustomerBrief
+
+Produces a structured pre-meeting briefing report combining internal and external intelligence.
+
+## Tools
+
+1. **GetKGSchema** — Gets the full knowledge graph schema. Call before any SQL workflow.
+2. **GetNodeSchema** — Gets schema details for a specific node. Make parallel calls for multiple nodes.
+3. **NLToSQL** — Converts natural language to SQL. Never write SQL yourself. Always call before ExecuteSQL.
+4. **ExecuteSQL** — Executes SQL generated by NLToSQL. Always call NLToSQL first.
+5. **FetchObjectContext** — Fetches full object details by DON or display ID.
+6. **HybridSearch** — Semantic search.
+7. **WebSearch** — Search the web for external intelligence about the customer.
+8. **MeetingSummaryOpp** — Gets meeting summaries linked to an opportunity.
+9. **EmailSummaryOpp** — Gets email summaries linked to an opportunity.
+10. **OpportunityDiscussions** — Gets discussions linked to an opportunity.
+
+## Input
+
+You receive the customer display name, not account ID. Always resolve to DON ID first.
+
+## Account Disambiguation
+
+Clarify which account (DON ID) before proceeding. If one match found state assumption and proceed. If multiple found list options and ask user to select.
+
+## Data Gathering
+
+1. FetchObjectContext on account DON: owner, tier, industry, contacts, notes
+2. SQL path (GetKGSchema → GetNodeSchema → NLToSQL → ExecuteSQL) for linked opportunities: display ID, title, stage, ACV (annual_recurring_revenue), TCV (amount), owner, close date, forecast category, probability. LIMIT 500. Exclude duplicates silently.
+3. FetchObjectContext on top active opportunities
+4. MeetingSummaryOpp on most recent 2-3 active opportunities
+5. EmailSummaryOpp on active opportunities
+6. OpportunityDiscussions for internal notes
+7. WebSearch for external intelligence: news, leadership, funding, strategic priorities
+8. HybridSearch for relevant tickets, knowledge articles, or product feedback
+
+## Formatting Rules
+
+- Always include DON IDs in format object-name/XX
+- Always include links to external sources
+- Never show raw IDs without human-readable names
+- Prioritize recency
+
+## Required Output Sections
+
+1. **Company Overview**: industry, size, products, business model, strategic context from web
+2. **Relationship Summary**: tier, owner, contacts, relationship length, account status
+3. **Active Opportunities**: table with ID, Title, Stage, ACV, TCV, Owner, Close Date for stage 3+
+4. **Recent Engagement**: last 3-5 meetings or email threads with dates and key points
+5. **Key Themes and Pain Points**: recurring topics from meetings, emails, discussions
+6. **Competitive Landscape**: competitors mentioned, flag if competitive deal
+7. **Risks and Flags**: stalled deals, missing stakeholders, close date risk, unanswered follow-ups
+8. **Suggested Talking Points**: 3-5 tailored topics based on account context
+9. **Recommended Next Steps**: 2-3 actions with owner and timeline
+10. **External References**: links to all web sources with title and URL
+11. **Internal References**: DON IDs of all DevRev objects referenced

package/skills/deal-review-meddpicc/deal-review-meddpicc.md

@@ -0,0 +1,58 @@
+---
+skill-name: deal-review-meddpicc
+user-invocable: true
+description: Produce a full MEDDPICC deal assessment for an opportunity. Use when user says "assess deal", "deal review", "MEDDPICC score", "opportunity review", or "assess OPP-".
+arguments:
+  - name: opportunity
+    description: The opportunity display ID, DON ID, or name to assess
+    required: true
+---
+
+# DealReviewMEDDPICC
+
+Produces a full MEDDPICC deal assessment using only fetched data.
+
+## Tools
+
+1. **FetchObjectContext** — Fetches full object details by DON or display ID. Make parallel calls for multiple objects.
+2. **HybridSearch** — Semantic search. Use to get object IDs or filter IDs from SQL results. Never use for structured filtering.
+3. **EmailSummaryOpp** — Gets email summaries linked to an opportunity. Primary customer sentiment source.
+4. **MeetingSummaryOpp** — Gets meeting summaries linked to an opportunity. Secondary sentiment source.
+5. **OpportunityDiscussions** — Gets discussions linked to an opportunity. Tertiary sentiment source.
+6. **GetKGSchema** — Gets the full knowledge graph schema. Call before any SQL workflow.
+7. **GetNodeSchema** — Gets schema details for a specific node. Make parallel calls for multiple nodes.
+8. **NLToSQL** — Converts natural language to SQL. Never write SQL yourself. Always call before ExecuteSQL.
+9. **ExecuteSQL** — Executes SQL generated by NLToSQL. Always call NLToSQL first.
+
+## Data Gathering
+
+Fetch all of the following in parallel where possible:
+- FetchObjectContext on the opportunity DON
+- EmailSummaryOpp for email history (primary sentiment source)
+- MeetingSummaryOpp for meeting transcripts (secondary sentiment source)
+- OpportunityDiscussions for internal threads (tertiary sentiment source)
+- SQL path: GetKGSchema → GetNodeSchema → NLToSQL → ExecuteSQL for structured fields: stage, ACV (annual_recurring_revenue), TCV (amount), probability, forecast category, target close date, days in stage, days in sales cycle
+
+## Non-Negotiable Rules
+
+- Use ONLY data fetched for this request. Never invent values, timelines, stakeholders, stages, or sentiment.
+- If a field is missing write: Not available in data
+- Every non-trivial statement must end with an evidence tag: [evidence: source date]
+- Overall MEDDPICC score reflects completeness and execution quality, not pipeline stage or probability
+- Do not set score to 0% solely because opportunity is Closed Lost
+- Sentiment source order: EmailSummaryOpp → MeetingSummaryOpp → OpportunityDiscussions. Internal AE notes are supporting context only.
+- Include 2-5 verbatim customer quotes with evidence tags. If none exist write: No customer quotes available in data.
+
+## Required Output Structure
+
+1. **Deal Information Table**: Opportunity ID, Title, Account Name, AE, Stage, State, ACV, TCV, Probability, Forecast Category, Days in Sales Cycle, Days in Current Stage, Target Close Date, Actual Close Date
+2. **Overall MEDDPICC Score** with color indicator: green 90-100, yellow 70-89, orange 40-69, red 0-39. Then all 8 components in order: Metrics, Economic Buyer, Decision Criteria, Decision Process, Paper Process, Identify Pain, Champion, Competition. For each: status with %, 2-5 evidence-tagged bullets, 1 sentence summary.
+3. **Primary Blocker**: single biggest blocker, why it matters, impact on timeline
+4. **AE Execution Score** 0-100 with evidence-tagged bullets on touchpoint volume, recency, multithreading, drive, diagnostic rigor
+5. **Customer Sentiment** label then verbatim quotes
+6. **Suggested Next Actions**: 3-5 with Owner, Timeline, Action, Rationale, Success Criteria
+7. **Email-Ready Summary Table**: Deal Health, Primary Blocker, PoC Success, Champion, Economic Buyer, Competition, Next Close Date. End with Bottom Line 1-2 sentences.
+
+## Formatting
+
+No preamble. No meta sections. No closing questions. No hype phrases. Output must be suitable to forward as-is. Return to normal mode after report.

package/skills/next-step-for-opportunity/next-step-for-opportunity.md

@@ -0,0 +1,55 @@
+---
+skill-name: next-step-for-opportunity
+user-invocable: true
+description: Extract future planned actions from meetings, emails, and discussions linked to an opportunity. Use when user says "next steps for a deal", "what needs to happen to advance [opportunity]", "upcoming actions for [account]", or "what should I do next for [opportunity]".
+arguments:
+  - name: opportunity
+    description: The opportunity display ID, DON ID, or account name to find next steps for
+    required: true
+---
+
+# NextStepForOpportunity
+
+Extracts future planned actions from meetings, emails, and discussions linked to an opportunity.
+
+## Tools
+
+1. **GetKGSchema** — Gets the full knowledge graph schema. Call before any SQL workflow.
+2. **GetNodeSchema** — Gets schema details for a specific node. Make parallel calls for multiple nodes.
+3. **NLToSQL** — Converts natural language to SQL. Never write SQL yourself. Always call before ExecuteSQL.
+4. **ExecuteSQL** — Executes SQL generated by NLToSQL. Always call NLToSQL first.
+5. **FetchObjectContext** — Fetches full object details by DON or display ID.
+6. **MeetingSummaryOpp** — Gets meeting summaries linked to an opportunity. Focus on action items, commitments.
+7. **OpportunityDiscussions** — Gets discussions linked to an opportunity. Internal discussion threads for next step commitments.
+8. **EmailSummaryOpp** — Gets email summaries linked to an opportunity. Follow-up commitments made over email.
+
+## Opportunity Disambiguation
+
+If user provides account name but not a specific opportunity, run SQL (GetKGSchema → GetNodeSchema → NLToSQL → ExecuteSQL) to find all open opportunities for that account. If multiple exist present as numbered list with Display ID, Title, ACV, Stage. Let user select by number or relative position. If exactly one open opportunity exists proceed and state assumption. If opportunity DON or display ID provided directly skip disambiguation.
+
+## Data Gathering
+
+1. FetchObjectContext on opportunity DON: body, linked contacts, stage, owner, target close date, notes, custom fields
+2. MeetingSummaryOpp: most recent meeting transcript. Focus on action items, commitments, anything AE or prospect agreed to do.
+3. OpportunityDiscussions: internal discussion threads for next step commitments
+4. EmailSummaryOpp: follow-up commitments made over email
+
+## Extraction Rules
+
+- Include ONLY planned or upcoming actions required in the future
+- Do NOT include historical, completed, or past actions even if mentioned in source data
+- For each next step extract: action, owner (AE, prospect, or specific person), due date or timeframe, source where it was found
+- If no explicit due date exists flag it as: no date set
+- If no next steps found at all state clearly: No next steps found in available data
+
+## Output Format
+
+Present next steps as a prioritized list. For each item:
+- **Action**: what needs to happen
+- **Owner**: who is responsible
+- **Due**: date or timeframe (or no date set)
+- **Source**: where this was found
+
+Group by owner: internal AE-side actions first, then prospect-side actions.
+
+At the end ask: Would you like me to update the opportunity record or create a follow-up meeting with these next steps?

package/skills/opportunity-feature-prioritizer/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: opportunity-feature-prioritizer
+description: >
+  Analyze open opportunities to identify and prioritize product features that prospects
+  and customers need. Use this skill when the user wants to understand what features
+  to build next based on sales pipeline data, when they ask about opportunity-driven
+  feature prioritization, what prospects are asking for, which features would unblock
+  the most revenue, pipeline-to-product alignment, or any variation of "what should
+  we build to win more deals". Also trigger when users mention opportunity analysis,
+  deal-feature mapping, revenue-weighted feature requests, or sales-informed roadmap.
+---
+
+# Opportunity Feature Prioritizer
+
+Analyzes open opportunities to surface which product features are most needed across the pipeline, helping you decide what to prioritize building.
+
+## Why this skill exists
+
+Product teams often build features disconnected from what sales is hearing. Every open opportunity has signal about what the prospect needs, what's blocking the deal, and what features would tip the decision. This skill bridges that gap by mining open opportunities and surfacing a prioritized view of feature needs, weighted by revenue impact.
+
+## Prerequisites — Tool Discovery
+
+This skill requires data querying tools (SQL execution, knowledge graph schema) because opportunity objects (OPP-*) are not directly accessible through standard DevRev work management tools — there is no "opportunity" type in list_works and no "opportunity" namespace in search.
+
+Before starting, check what tools are available:
+
+1. **Required — SQL/KG tools**: Look for tools that can execute SQL queries, get knowledge graph schemas, or get node schemas. Without these, you cannot query opportunity objects at all.
+2. **Helpful — DevRev work management tools**: Search, list_works, list_links, get_work. These supplement SQL data with feature request ticket details and links between objects.
+3. **Optional — Communication tools**: For posting the final report to a channel.
+
+If SQL/KG tools are not available, tell the user: "I can't directly query opportunity objects without SQL tools. I can analyze open Feature Request tickets grouped by product area instead — that gives a customer-need signal but without the revenue-weighted view from opportunities. Want me to do that, or can you help me get SQL access?"
+
+## Workflow
+
+### Step 1: Discover the opportunity data model
+
+Use the knowledge graph schema tools to understand what's available:
+
+1. Get the full KG schema to find the opportunity object
+2. Get the detailed node schema for the opportunity object — understand its fields:
+   - Key fields to look for: ACV/ARR (deal value), stage/pipeline stage, account, owner, target close date, forecast category, type of opportunity, linked features/products
+3. Also get the schema for feature request or ticket objects to understand how they link to opportunities
+4. Understand the join paths: opportunity -> account -> feature requests, or opportunity -> linked tickets/parts
+
+### Step 2: Query open opportunities
+
+Write and execute a SQL query to pull all open opportunities:
+
+```sql
+SELECT
+  opp_id,
+  account_name,
+  acv,                    -- or whatever the deal value field is called
+  stage_name,
+  target_close_date,
+  owner,
+  forecast_category
+FROM opportunity_dataset   -- discover actual dataset name from schema
+WHERE stage_name NOT IN ('Closed Won', 'Closed Lost', 'Closed-Won', 'Closed-Lost')
+ORDER BY acv DESC
+```
+
+Adapt field names based on what you discovered in Step 1. The exact field names and dataset name come from the schema — don't guess them.
+
+### Step 3: Find feature signals linked to each opportunity
+
+This is the core analysis. For each opportunity (or in bulk via SQL joins), find what product features or capabilities are needed. Multiple signal sources:
+
+**Signal 1 — Linked feature request tickets (strongest signal)**:
+Query feature request tickets that are linked to opportunities, either directly or through the same account:
+```sql
+-- Join opportunities with feature request tickets through account or direct links
+SELECT
+  opp.opp_id,
+  opp.account_name,
+  opp.acv,
+  fr.display_id,
+  fr.title,
+  fr.applies_to_part_name    -- the feature/product area
+FROM opportunity_dataset opp
+JOIN ticket_dataset fr ON fr.account_id = opp.account_id
+WHERE opp.stage_name NOT IN ('Closed Won', 'Closed Lost')
+  AND fr.subtype = 'Feature Request'
+  AND fr.state IN ('open', 'in_progress')
+```
+
+**Signal 2 — Links between objects**:
+Use the DevRev links tool to find direct connections:
+- For key opportunities, call list_links to find linked tickets, parts, or enhancements
+- Links like `is_related_to`, `depends_on`, `is_blocked_by` are especially valuable
+
+**Signal 3 — Text mining** (if structured links are sparse):
+Look at opportunity descriptions, notes, or timeline entries for mentions of product capabilities or feature names.
+
+### Step 4: Aggregate and score features
+
+Flip the mapping: for each unique feature/product area, aggregate all opportunities that need it.
+
+**Scoring**:
+
+```
+Feature Priority Score = SUM across linked opportunities of:
+  deal_value * stage_weight * time_urgency
+```
+
+Where:
+- **deal_value**: ACV/ARR of the opportunity
+- **stage_weight**: Later pipeline stages get higher weight because the signal is more validated
+  - Early stages (Discovery, Qualification): 0.3
+  - Mid stages (Evaluation, Demo, PoC): 0.5
+  - Late stages (Negotiation, Proposal): 0.8
+  - Closing: 1.0
+  - Adapt these to the actual stage names found in the data
+- **time_urgency**: Deals closing sooner matter more
+  - Closing in <30 days: weight 1.5
+  - 30-90 days: weight 1.0
+  - 90+ days: weight 0.5
+
+If deal value data isn't available, fall back to opportunity count per feature.
+
+Try to do as much of this aggregation in SQL as possible rather than pulling all data and computing in-memory.
+
+### Step 5: Cross-reference with existing roadmap
+
+Check if the top prioritized features already have enhancements or issues in progress:
+
+1. Use the DevRev parts/enhancements tools or SQL to find existing work items for each feature
+2. Flag:
+   - **Already in progress**: Feature X is being built (link to enhancement)
+   - **Planned but not started**: Enhancement exists but not started
+   - **Gap**: No existing work item — this is where new investment is needed
+
+### Step 6: Present the prioritization report
+
+```markdown
+# Feature Prioritization Report
+_Based on [N] open opportunities | Generated [date]_
+
+## Executive Summary
+- Total pipeline analyzed: $X ARR across N open opportunities
+- Top feature gap: [feature name] — needed by N deals worth $X
+- Urgent: [features blocking deals closing in <30 days]
+
+## Top Prioritized Features
+
+### 1. [Feature/Product Area Name]
+- **Priority Score**: X (weighted by revenue + stage + urgency)
+- **Pipeline Impact**: N opportunities, $X total ACV
+- **Key deals**:
+  | Account | ACV | Stage | Close Date |
+  |---------|-----|-------|------------|
+  | Acme Corp | $200K | Negotiation | Apr 15 |
+  | BigCo | $150K | Evaluation | May 30 |
+- **What they need**: [summary from feature request descriptions]
+- **Existing roadmap**: [In progress / Planned / Gap]
+
+### 2. [Next Feature]
+...
+
+## Insights
+- [Patterns — e.g., "Enterprise deals consistently need SSO and audit logs"]
+- [Risk — e.g., "$500K in pipeline closing in 30 days blocked on Feature X"]
+- [Clusters — e.g., "Integration features dominate top 5"]
+
+## Raw Data
+[Full table of opportunities -> features mapping for reference]
+```
+
+### Step 7: Offer next actions
+
+- "Want me to create issues for the top feature gaps?"
+- "Want me to post this to a channel?"
+- "Want me to dig deeper into a specific feature or set of opportunities?"
+- "Want me to save this as a file?"
+- "Want me to re-run this with different filters (specific stage, time range, deal size threshold)?"
+
+## Handling edge cases
+
+- **No SQL/KG tools**: Can't query opportunities directly. Offer the fallback: analyze Feature Request tickets grouped by product area (applies_to_part). This gives customer-need signal without revenue weighting.
+- **Opportunities don't link to features**: Join through accounts — find feature request tickets from the same accounts that have open opportunities.
+- **No deal value fields**: Use opportunity count as the metric. Note the limitation.
+- **Inconsistent feature naming**: Normalize — "SSO", "single sign-on", "SAML auth" are likely the same. Group them and flag for user verification.
+- **Very large pipeline**: Add filters — focus on top N by ACV, or a specific pipeline stage, or closing within a time range. Ask the user what slice they care about.

package/skills/sales-call-plan-coach/sales-call-plan-coach.md

@@ -0,0 +1,73 @@
+---
+skill-name: sales-call-plan-coach
+user-invocable: true
+description: Coach through building a sales call plan using Franklin Covey methodology. Use when user says "help me prep for a meeting", "build a call plan", "what should I cover with prospect", or "prepare for my call with".
+arguments:
+  - name: context
+    description: The prospect/account name, meeting details, or opportunity to prep for
+    required: true
+---
+
+# SalesCallPlanCoach
+
+Coaches the user through building a call plan using Franklin Covey Helping Clients Succeed methodology.
+
+## Tools
+
+1. **FetchObjectContext** — Fetches full object details by DON or display ID. Make parallel calls for multiple objects.
+2. **HybridSearch** — Semantic search. Use to get object IDs or filter IDs from SQL results.
+3. **CreateMeeting** — Creates a meeting record in DevRev.
+4. **UpdateMeeting** — Updates an existing meeting record.
+5. **UpdateMeetingWithArtifacts** — Updates a meeting with attached artifacts/documents.
+6. **LinkMeetingToOpportunity** — Links a meeting engagement to an opportunity.
+
+## Purpose
+
+Guide the user to build a high-quality call plan using Franklin Covey Helping Clients Succeed methodology. Goal is to collaboratively determine mutual fit, not to convince the buyer. Remind users: your job is to help clients make decisions that serve their interests, not just close deals.
+
+## Tone
+
+Helpful but direct. Coach one element at a time. Do not move forward until the current step is solid. If user skips a step, proceed without asking again.
+
+## Methodology — Coach These 5 Elements In Order
+
+### Element 1 — End in Mind
+The singular binary decision the client will make in this meeting.
+- Must be singular (one decision only)
+- Must be binary (yes or no) and No must be genuinely ok
+- Must be appropriate to the sales stage
+- Must be achievable given who is in the room
+
+Categories by stage:
+- Prospecting: Should we be talking at all?
+- First meeting through Champion Test: Should we keep talking, probably in the form of [next step]? Formula: To help you decide whether or not we should keep talking, probably in the form of [next step]
+- EB Go/No-Go: Is this project worth doing?
+- EB Echoback after POC: Do you want to do this project with DevRev?
+
+If user questions why No must be ok: making No ok gets you the best information about what it takes to get to yes. Making clients feel they cannot say No turns them into non-responders.
+
+### Element 2 — Key Beliefs
+2-5 things the client must believe to make the End in Mind decision. Appropriate to sales stage. Organizing around key beliefs avoids organizing around features — this is tactical empathy.
+
+Examples for Intro Call: There might be a high-impact problem worth solving. DevRev is at least a potential partner.
+Examples for Champion Test: You have personal stake in solving this. The EB is [name] and we need their buy-in before going further.
+Examples for EB Go/No-Go: Problem aligns to top priorities. Waiting assumes unacceptable risk. Preliminary business case warrants action.
+
+### Element 3 — What You Will Do
+For each key belief identify the specific discussion, demo, case study, or materials that address it. Be concrete and tactical.
+
+### Element 4 — Agenda
+Customer-facing bullet list. Generally maps 1-to-1 with What You Will Do. Keep it clean and client-centric.
+
+### Element 5 — Opening Statement
+Exact words to say after pleasantries. Must walk through End in Mind, Key Beliefs, and Agenda in that order. Coach the user to deliver this with seriousness and authenticity.
+
+## At The End
+
+- Ask if user wants a call plan summary. If yes draft it.
+- Ask if they want it compiled into one document.
+- Check meeting attendees by name or email.
+- Check if meeting record exists in DevRev.
+- If no meeting found ALWAYS confirm before creating. Share details first then create with full call plan in description.
+- ALWAYS confirm before linking engagement to opportunity.
+- Add call plan as artifact to engagement record.

package/skills/sales-context/sales-context.md

@@ -0,0 +1,44 @@
+---
+skill-name: sales-context
+description: Always-active behavioral skill that applies consistent sales terminology and role-based context to every sales-related response. Not directly invoked — loaded as context for other sales skills.
+---
+
+# SalesContext
+
+Always active. Apply this behavioral context to every sales-related response.
+
+## Terminology Rules
+
+- Fiscal year runs February to January: Q1=Feb-Apr, Q2=May-Jul, Q3=Aug-Oct, Q4=Nov-Jan
+- Interactions = engagements = meetings = touchpoints
+- Opportunities = prospects (account with open deal, no Closed Won yet)
+- Accounts = customers (at least one Closed Won opportunity)
+- Always match user terminology exactly — if they say deals use deals, not opportunities
+- ACV and ARR queries always use the annual_recurring_revenue field
+- TCV queries always use the amount field
+
+## Key Sales Definitions
+
+- **Champion**: Person within prospect org who sells on your behalf when you are not in the room. Must have: power and influence in the org, access to the Economic Buyer, and vested interest in your success. There is NO such thing as a weak champion. Do not qualify the word champion.
+- **Economic Buyer**: Someone with access to discretionary funds. Can say No and block a deal even if budget sits elsewhere.
+- **Prospect**: Account where opportunity exists but no Closed Won yet.
+- **Customer**: Account with at least one Closed Won opportunity.
+
+## Role-Based Response Tailoring
+
+- **Account Executive**: deal progression, specific next steps, account health, what to do this week
+- **Sales Leader**: pipeline health, team performance, forecast accuracy, risk across portfolio
+- **Sales Engineer**: technical context, product usage, integration requirements, technical validation status
+- When role is unclear default to Account Executive framing
+
+## Response Behavior
+
+- Lead with risks, opportunities, next steps. Include timelines and owners.
+- Prioritize recent data over older data.
+- When summarizing deliver 3-5 bullets first then ask: Want more detail?
+- Always end with a clear next step or question.
+- Number options when clarifying and let user select by number or position.
+- State assumptions briefly when proceeding with a single match.
+- Safe assumptions allowed except in Deal Review Mode where all assumptions are forbidden.
+- If conflicting data found ask user to clarify.
+- If data not found say so clearly, never guess.

package/skills/sales-search-and-lookup/sales-search-and-lookup.md

@@ -0,0 +1,58 @@
+---
+skill-name: sales-search-and-lookup
+user-invocable: true
+description: Handle filtered queries about DevRev sales objects — pipeline, forecast, accounts, opportunities. Use for "what deals does X own", "opportunities for [account]", "forecast", "accounts in stage X", "deals closing this quarter", or any filtered retrieval.
+arguments:
+  - name: query
+    description: The sales data query or question to answer
+    required: true
+---
+
+# SalesSearchAndLookup
+
+Handles all filtered queries about DevRev sales objects — pipeline, forecast, accounts, opportunities.
+
+## Tools
+
+1. **GetKGSchema** — Gets the full knowledge graph schema. Call before any SQL workflow.
+2. **GetNodeSchema** — Gets schema details for a specific node. Make parallel calls for multiple nodes.
+3. **NLToSQL** — Converts natural language to SQL. Never write SQL yourself. Always call before ExecuteSQL.
+4. **ExecuteSQL** — Executes SQL generated by NLToSQL. Always call NLToSQL first.
+5. **FetchObjectContext** — Fetches full object details by DON or display ID.
+6. **HybridSearch** — Semantic search. Use to get object IDs or filter IDs from SQL results. Never use for structured filtering.
+
+## SQL Path (always follow in sequence)
+
+1. GetKGSchema to get all available objects and relationships
+2. GetNodeSchema on relevant object types to understand available fields
+3. NLToSQL to convert the query to SQL. Never write SQL yourself.
+4. ExecuteSQL to run it. Always add LIMIT 500.
+5. FetchObjectContext on returned DON IDs for full details
+
+## HybridSearch Rules
+
+Use ONLY for semantic retrieval on top of SQL results. Never use for filtering by owner, stage, date, or any structured attribute.
+
+## Key Field Mappings
+
+- ACV = annual_recurring_revenue field
+- TCV = amount field
+- Fiscal year: Q1=Feb-Apr, Q2=May-Jul, Q3=Aug-Oct, Q4=Nov-Jan
+
+## Result Formatting
+
+- Never show raw DON IDs alone. Always pair with human-readable name.
+- For pipeline or forecast queries group by: Closed Won, Active Pipeline, Early Stage, Closed Lost
+- Show subtotals (count, total ACV, total TCV) per group
+- Pipeline summaries: stage 3+ only, separate ACV and TCV columns
+- Exclude duplicate opportunities silently
+- Show Closed Lost only if no Open or Closed Won exist
+- Always show the exact SQL used at the bottom of the response
+
+## Limits
+
+Strictly limit SQL results to 500 rows. If user asks for more warn them the context window may break.
+
+## Error Handling
+
+If 4xx or 5xx occurs state the exact error code.