From 41e15897cb8c650a7181133165c06564487ab6b6 Mon Sep 17 00:00:00 2001 From: Steve Calvert Date: Mon, 11 May 2026 17:37:50 -0700 Subject: [PATCH 1/7] fix(validate-plugins): allow YAML block-scalar indicators in frontmatter The quoteSpecialValues pre-pass treated `|` and `>` as YAML special characters and wrapped them in double quotes, which breaks the standard YAML block-scalar syntax (`key: |` followed by an indented body). Skills using a multi-line `when_to_use` field were failing validation as a result. Recognize block-scalar headers (`|` / `>` with optional chomp and indent indicators) and pass those lines through unchanged so the YAML parser can read the indented body. Co-Authored-By: Claude Opus 4.7 (1M context) --- scripts/validate-plugins.mjs | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/scripts/validate-plugins.mjs b/scripts/validate-plugins.mjs index 76102d8..1f64106 100644 --- a/scripts/validate-plugins.mjs +++ b/scripts/validate-plugins.mjs @@ -16,6 +16,8 @@ import process from "node:process"; // Characters that require quoting in YAML values when unquoted const YAML_SPECIAL_CHARS = /[{}[\]*&#!|>%@`]/; +// YAML block-scalar headers (| or > with optional chomp/indent indicators) — leave them alone +const BLOCK_SCALAR_HEADER = /^[|>][1-9]?[+-]?$/; const FRONTMATTER_REGEX = /^---\s*\n([\s\S]*?)---\s*\n?/; const pluginNamePattern = /^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/; @@ -41,6 +43,10 @@ function quoteSpecialValues(text) { (value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")) ) { result.push(line); continue; } + // Block-scalar indicators (key: |, key: >, with optional chomp/indent) are + // valid YAML and must pass through unchanged so the parser can read the + // indented body that follows. + if (BLOCK_SCALAR_HEADER.test(value.trim())) { result.push(line); continue; } if (YAML_SPECIAL_CHARS.test(value)) { const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"'); result.push(`${key}: "${escaped}"`); From 0000296473deb6ea4abec58613d5d098f399d173 Mon Sep 17 00:00:00 2001 From: Steve Calvert Date: Mon, 11 May 2026 17:38:12 -0700 Subject: [PATCH 2/7] refactor(glean-core)!: consolidate six skills into using-glean with per-tool reference files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the six sibling skills (enterprise-search, meeting-context, people-lookup, synthesis-patterns, confidence-signals, glean-tools-guide) with a single using-glean skill plus a reference/ directory carrying per-tool depth on demand. The previous structure published six descriptions to the skill listing, each with overlapping triggers and shared boilerplate (every one cross-referenced glean-tools-guide for tool naming). On a typical install with other plugins present, that pushed the skill description budget over its 1% limit and caused descriptions to be silently truncated, which made auto-triggering unreliable. The new layout: plugins/glean-core/skills/using-glean/ ├── SKILL.md # parent: when to use, intent->tool decision │ # tree, cross-tool rules, links to reference └── reference/ ├── search.md # one file per Glean MCP tool ├── chat.md ├── code-search.md ├── employee-search.md ├── meeting-lookup.md ├── gmail-search.md ├── outlook-search.md ├── read-document.md ├── user-activity.md ├── memory.md # read_memory + memory_schema (paired) ├── knowledge-graph.md# knowledge_graph_query + ..._schema (paired) ├── agents-as-tools.md# dynamic Glean platform agent discovery ├── synthesis.md # cross-cutting: combining multiple tools └── vetting.md # cross-cutting: source quality / freshness Reference files are loaded on demand; only the parent skill's description sits in the always-on listing. Tool docs reference Glean MCP tools by their bare names (search, employee_search, etc.) rather than the runtime mcp__glean___ identifier, matching what Anthropic's official plugins do. BREAKING CHANGE: the old slash paths (/glean-core:enterprise-search, /glean-core:meeting-context, /glean-core:people-lookup, /glean-core:synthesis-patterns, /glean-core:confidence-signals, /glean-core:glean-tools-guide) no longer exist. Use /glean-core:using-glean or simply ask in natural language and let the skill auto-trigger. Co-Authored-By: Claude Opus 4.7 (1M context) --- plugins/glean-core/README.md | 55 ++-- .../skills/confidence-signals/SKILL.md | 262 ------------------ .../skills/enterprise-search/SKILL.md | 116 -------- .../skills/glean-tools-guide/SKILL.md | 252 ----------------- .../skills/meeting-context/SKILL.md | 91 ------ .../glean-core/skills/people-lookup/SKILL.md | 123 -------- .../skills/synthesis-patterns/SKILL.md | 194 ------------- .../glean-core/skills/using-glean/SKILL.md | 55 ++++ .../using-glean/reference/agents-as-tools.md | 51 ++++ .../skills/using-glean/reference/chat.md | 54 ++++ .../using-glean/reference/code-search.md | 58 ++++ .../using-glean/reference/employee-search.md | 53 ++++ .../using-glean/reference/gmail-search.md | 56 ++++ .../using-glean/reference/knowledge-graph.md | 95 +++++++ .../using-glean/reference/meeting-lookup.md | 54 ++++ .../skills/using-glean/reference/memory.md | 68 +++++ .../using-glean/reference/outlook-search.md | 58 ++++ .../using-glean/reference/read-document.md | 49 ++++ .../skills/using-glean/reference/search.md | 62 +++++ .../skills/using-glean/reference/synthesis.md | 80 ++++++ .../using-glean/reference/user-activity.md | 49 ++++ .../skills/using-glean/reference/vetting.md | 91 ++++++ 22 files changed, 972 insertions(+), 1054 deletions(-) delete mode 100644 plugins/glean-core/skills/confidence-signals/SKILL.md delete mode 100644 plugins/glean-core/skills/enterprise-search/SKILL.md delete mode 100644 plugins/glean-core/skills/glean-tools-guide/SKILL.md delete mode 100644 plugins/glean-core/skills/meeting-context/SKILL.md delete mode 100644 plugins/glean-core/skills/people-lookup/SKILL.md delete mode 100644 plugins/glean-core/skills/synthesis-patterns/SKILL.md create mode 100644 plugins/glean-core/skills/using-glean/SKILL.md create mode 100644 plugins/glean-core/skills/using-glean/reference/agents-as-tools.md create mode 100644 plugins/glean-core/skills/using-glean/reference/chat.md create mode 100644 plugins/glean-core/skills/using-glean/reference/code-search.md create mode 100644 plugins/glean-core/skills/using-glean/reference/employee-search.md create mode 100644 plugins/glean-core/skills/using-glean/reference/gmail-search.md create mode 100644 plugins/glean-core/skills/using-glean/reference/knowledge-graph.md create mode 100644 plugins/glean-core/skills/using-glean/reference/meeting-lookup.md create mode 100644 plugins/glean-core/skills/using-glean/reference/memory.md create mode 100644 plugins/glean-core/skills/using-glean/reference/outlook-search.md create mode 100644 plugins/glean-core/skills/using-glean/reference/read-document.md create mode 100644 plugins/glean-core/skills/using-glean/reference/search.md create mode 100644 plugins/glean-core/skills/using-glean/reference/synthesis.md create mode 100644 plugins/glean-core/skills/using-glean/reference/user-activity.md create mode 100644 plugins/glean-core/skills/using-glean/reference/vetting.md diff --git a/plugins/glean-core/README.md b/plugins/glean-core/README.md index 174a019..356b31f 100644 --- a/plugins/glean-core/README.md +++ b/plugins/glean-core/README.md @@ -2,7 +2,7 @@ **Required foundation for all Glean plugins.** -This plugin provides shared skills, MCP tool guidance, and configuration commands that all other Glean plugins depend on. +Provides the canonical skill for using Glean's MCP tools, plus the commands and hook that configure your Glean MCP server connection. ## Installation @@ -10,37 +10,60 @@ This plugin provides shared skills, MCP tool guidance, and configuration command claude plugin install glean-core ``` -## What's Included +## What's included -### Skills -- **glean-tools-guide** - Comprehensive guidance for selecting and using Glean MCP tools -- **enterprise-search** - Triggers for document search queries -- **people-lookup** - Triggers for people/org queries -- **meeting-context** - Triggers for meeting queries +### Skill + +- **`using-glean`** — Auto-triggers when the user asks about anything in enterprise systems (documents, people, meetings, internal code, email, the user's own activity, structured memory, the knowledge graph). The skill teaches Claude how to map the user's question to the right Glean MCP tool and links to per-tool reference files. + + Reference files live under [`skills/using-glean/reference/`](skills/using-glean/reference/) and are loaded only when needed: + + | File | Covers | + |---|---| + | `search.md` | The `search` tool: structured params, filters, pitfalls | + | `chat.md` | The `chat` tool: when synthesis beats raw search | + | `code-search.md` | The `code_search` tool: inline filters, query patterns | + | `employee-search.md` | The `employee_search` tool: people, teams, org structure | + | `meeting-lookup.md` | The `meeting_lookup` tool: dates, transcripts, peer calendars | + | `gmail-search.md` | The `gmail_search` tool (Google Workspace email) | + | `outlook-search.md` | The `outlook_search` tool (Microsoft 365 email) | + | `read-document.md` | The `read_document` tool: full content by URL | + | `user-activity.md` | The `user_activity` tool: the user's own work history | + | `memory.md` | `read_memory` + `memory_schema` | + | `knowledge-graph.md` | `knowledge_graph_query` + `knowledge_graph_schema` | + | `agents-as-tools.md` | Discovering and invoking dynamic Glean platform agents | + | `synthesis.md` | Combining multiple tools for cross-source answers | + | `vetting.md` | Source quality, freshness, authority — before presenting | ### Commands -- `/glean-core:mcp-setup` - Configure your Glean MCP server connection -- `/glean-core:status` - Check MCP connection status + +- `/glean-core:mcp-setup` — Configure your Glean MCP server connection +- `/glean-core:status` — Check MCP connection status ### Hooks -- **SessionStart** - Automatically checks MCP configuration on session start + +- **SessionStart** — Automatically checks MCP configuration on session start ## Requirements - Claude Code CLI - Glean MCP server configured (run `/glean-core:mcp-setup` to configure) -## Next Steps +## Next steps After installing glean-core, install the feature plugins you need: | Plugin | Purpose | -|--------|---------| -| [glean-search](../glean-search) | Enterprise document search | -| [glean-people](../glean-people) | People discovery and expertise | -| [glean-meetings](../glean-meetings) | Meeting intelligence | -| [glean-docs](../glean-docs) | Document analysis | +|---|---| +| [glean-search](../glean-search) | Quick enterprise search workflow | +| [glean-people](../glean-people) | People discovery and expertise workflows | +| [glean-meetings](../glean-meetings) | Meeting catch-up and prep workflows | +| [glean-docs](../glean-docs) | Onboarding and RFC verification workflows | | [glean-code](../glean-code) | Cross-repo code exploration | +| [glean-productivity](../glean-productivity) | Personal activity, priorities, briefings | +| [glean-project](../glean-project) | Project status and handoff | +| [glean-skills](../glean-skills) | Generate new Claude Code skills from your work patterns | +| [glean-dev-docs](../glean-dev-docs) | Glean platform / SDK documentation | ## Support diff --git a/plugins/glean-core/skills/confidence-signals/SKILL.md b/plugins/glean-core/skills/confidence-signals/SKILL.md deleted file mode 100644 index 68ca147..0000000 --- a/plugins/glean-core/skills/confidence-signals/SKILL.md +++ /dev/null @@ -1,262 +0,0 @@ ---- -name: confidence-signals -description: Use when you need to communicate the reliability, freshness, or authority of information from Glean. Triggers when presenting search results, when data might be stale, when sources have different authority levels, when the user should verify information, or when you're uncertain about completeness of results. ---- - -# Confidence Signals - -When presenting information from Glean, communicate the reliability, freshness, and authority of your sources clearly. - -## When This Applies - -Use these patterns when: -- Presenting search results that may be outdated -- Information comes from sources with different authority levels -- Results are incomplete or may have gaps -- The user should verify before acting -- Multiple sources have conflicting information -- You're making inferences beyond what sources explicitly state - ---- - -## Part 1: Vetting & Filtering (Before Presenting) - -**Be skeptical.** Not everything Glean returns should be presented. Better to return 3 high-quality results than 10 unvetted mentions. - -### Vetting Criteria - -Before including ANY result, evaluate: - -**1. Relevance Test** -- Does this actually answer the question, or just contain matching keywords? -- Is this about the same thing or just similar terminology? -- ❌ REJECT: Tangential mentions, keyword coincidences, unrelated contexts - -**2. Authority Test** -- 📗 **Official**: RFCs, approved specs, policies, CODEOWNERS → Include -- 📙 **Semi-official**: Team wikis, project docs → Include with note -- 📕 **Informal**: Slack discussions, drafts, personal notes → Include only if no official sources exist -- ❌ REJECT: Clearly superseded or deprecated content - -**3. Recency Test** -- ✅ **Current** (<3 months): Include with confidence -- ⚠️ **Aging** (3-12 months): Include with staleness warning -- ❌ **Stale** (12+ months): Only include if no alternatives, with strong warning -- Ask: "Would this still be true today?" - -**4. Expertise Test (for people recommendations)** -- Did they actually do significant work, or just mentioned it once? -- Are they still in a relevant role? -- Do multiple signals confirm expertise? -- ❌ REJECT: Single mentions, departed employees, outdated ownership - -### "Nothing Found" Is Valid - -If vetting eliminates all candidates, say so clearly: - -```markdown -No high-quality results found for [topic]. - -**This could mean:** -- The topic is new or undocumented -- Different terminology is used internally -- Access restrictions limit visibility -- This genuinely doesn't exist - -**Suggested next steps:** -- Try alternative terms: [suggestions] -- Ask in [relevant Slack channel] -- Check with [likely team] -``` - -Never pad results with low-quality matches to avoid saying "nothing found." - ---- - -## Part 2: Confidence Dimensions (When Presenting) - -### 1. Freshness - -How recently was this information updated? - -| Freshness | Indicator | Implication | -|-----------|-----------|-------------| -| Current | Updated within past week | High confidence | -| Recent | Updated within past month | Good confidence | -| Older | Updated 1-6 months ago | Verify if critical | -| Stale | Updated 6+ months ago | Likely outdated | -| Unknown | No update date available | Treat with caution | - -**How to express:** -- "As of [date]..." -- "Last updated [timeframe]..." -- "Note: This doc hasn't been updated since [date]" -- Include "(updated [date])" in source citations - -### 2. Source Authority - -How authoritative is this source? - -| Authority | Examples | Confidence | -|-----------|----------|------------| -| Official | RFCs, approved specs, policies | High | -| Semi-official | Team wikis, shared docs | Medium-High | -| Discussion | Slack threads, meeting notes | Medium | -| Personal | Individual docs, drafts | Lower | -| AI-generated | Chat synthesis | Verify claims | - -**How to express:** -- "According to the official [doc type]..." -- "From team documentation (may be informal)..." -- "Based on Slack discussion (not formally documented)..." -- "From meeting notes (verify if critical)..." - -### 3. Completeness - -How complete is this information? - -| Completeness | Situation | Action | -|--------------|-----------|--------| -| Comprehensive | Multiple sources confirm | High confidence | -| Partial | Some aspects found, gaps exist | Note gaps | -| Limited | Few results, may miss context | Suggest verification | -| Inference | Synthesized from indirect sources | Clearly state | - -**How to express:** -- "Based on comprehensive documentation..." -- "Found partial information - gaps in [area]" -- "Limited results found - suggest checking with [person/team]" -- "Inferred from related documents (not explicitly stated)..." - -### 4. Corroboration - -Do multiple sources agree? - -| Corroboration | Situation | Confidence | -|---------------|-----------|------------| -| Strongly corroborated | 3+ sources agree | Very high | -| Corroborated | 2 sources agree | High | -| Single source | Only one source found | Medium | -| Conflicting | Sources disagree | Note conflict | - -**How to express:** -- "Confirmed across multiple sources..." -- "Single source - recommend verification" -- "Note: Sources conflict on this point..." - ---- - -## Signal Templates - -### For Search Results - -```markdown -**[Title]** ([link]) -- Updated: [date] ([freshness assessment]) -- Source: [authority level] -- Relevance: [why this matches] -``` - -### For Synthesized Answers - -```markdown -## [Answer] - -**Confidence**: [High/Medium/Low] -- Based on [X] sources -- Most recent: [date] -- [Any caveats] - -**Sources**: -- [Source 1] - [authority], updated [date] -- [Source 2] - [authority], updated [date] -``` - -### For Uncertain Information - -```markdown -## [Topic] - -**What I Found**: [Information] - -**Caveats**: -- [ ] Source is [X] months old - verify currency -- [ ] Based on single source - seek corroboration -- [ ] Inferred, not explicitly stated -- [ ] Conflicts with [other source] - -**Suggested Verification**: Contact [person] or check [source] -``` - -### For Conflicts - -```markdown -## [Topic] - Conflicting Information - -| Aspect | Source A | Source B | Assessment | -|--------|----------|----------|------------| -| [Item] | [Says X] | [Says Y] | [Which is likely correct] | - -**Recommendation**: Verify with [authoritative source/person] -``` - ---- - -## Common Patterns - -### Pattern: Stale Documentation -``` -Note: This documentation was last updated [X months ago]. -The information may be outdated - verify with [team/person] -if making decisions based on this. -``` - -### Pattern: Informal Source -``` -This comes from [Slack/meeting notes] rather than formal -documentation. Consider documenting this officially if it's -important knowledge to preserve. -``` - -### Pattern: AI-Synthesized -``` -This answer was synthesized by Glean's AI across multiple -sources. For critical decisions, verify the underlying -documents directly: [links] -``` - -### Pattern: Incomplete Results -``` -I found [X] relevant results, but there may be additional -information in [other sources/systems]. This represents -what's accessible through Glean with your current permissions. -``` - -### Pattern: Strong Confidence -``` -This is well-documented with multiple corroborating sources: -- Official spec: [link] -- Recent meeting confirmation: [link] -- Implementation: [link] - -High confidence in this answer. -``` - ---- - -## When to Emphasize Confidence - -Always note confidence when: -- User will make a decision based on the information -- Information is time-sensitive -- Sources are from informal channels -- Only one source was found -- The topic involves policy, security, or compliance -- You're synthesizing rather than directly quoting - -## Relationship to Other Skills - -This skill works with: -- `synthesis-patterns` - When combining multiple sources -- `glean-tools-guide` - For understanding source types -- `enterprise-search` - When presenting search results diff --git a/plugins/glean-core/skills/enterprise-search/SKILL.md b/plugins/glean-core/skills/enterprise-search/SKILL.md deleted file mode 100644 index c7c97a9..0000000 --- a/plugins/glean-core/skills/enterprise-search/SKILL.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -name: enterprise-search -description: Use when the user asks about company documents, internal wikis, policies, specifications, design docs, RFCs, or enterprise knowledge. Triggers on phrases like "find the doc about", "what's our policy on", "where is the spec for", "company guidelines", "internal documentation", or when searching for information that would be in enterprise systems rather than the local codebase. ---- - -# Enterprise Search via Glean - -When users ask about internal company information that lives in enterprise systems (not the local codebase), use Glean tools to find it. - -## Tool Naming - -See the `glean-tools-guide` skill for Glean MCP tool naming conventions. Tools follow the pattern `mcp__glean_[server-name]__[tool]` where the server name is dynamic. Use whatever Glean server is available in your tool list. - -## When This Applies - -Use Glean search when users ask about: -- Company policies, guidelines, or procedures -- Design documents, RFCs, or specifications -- Internal wikis or knowledge base articles -- Project documentation or roadmaps -- Slack discussions or announcements -- Any "where is the doc about X" questions - -## BE SKEPTICAL - -Not every search result is relevant or current. Before presenting results, evaluate: - -**Relevance Test** -- Does this actually answer the question, or just contain keywords? -- ✅ INCLUDE: Directly addresses the query -- ❌ EXCLUDE: Keyword coincidence, different context - -**Freshness Test** -- Is this information current? -- ✅ CURRENT: Updated in past 6 months -- ⚠️ AGING: 6-12 months - note the age -- ❌ STALE: 12+ months - include only with strong warning, or exclude - -**Authority Test** -- How reliable is this source? -- 📗 OFFICIAL: Approved policies, signed-off specs -- 📙 SEMI-OFFICIAL: Team wikis, shared docs -- 📕 INFORMAL: Slack discussions, personal notes - -**Filter Out**: -- Superseded or deprecated documents -- Draft documents presented as final -- Keyword matches in unrelated contexts - -**See `confidence-signals` skill** for how to communicate reliability. - -## Tool Selection - -| User Intent | Glean Tool | -|-------------|------------| -| Find documents, policies, specs | `search` | -| Complex analysis across sources | `chat` | -| Read full document content | `read_document` | - -## Query Optimization - -Glean understands natural language. Enhance queries with filters when helpful: - -``` -# Recent documents -"API documentation updated:past_week" - -# By author -"design doc owner:\"Sarah Chen\"" - -# Date range -"quarterly planning after:2024-01-01" - -# Specific app -"authentication RFC app:confluence" -``` - -## Workflow - -1. **Search first**: Use `search` to find relevant documents -2. **Vet results**: Apply vetting criteria before presenting -3. **Read for details**: Use `read_document` with URLs from vetted results -4. **Synthesize if complex**: Use `chat` for multi-source analysis - -## Always Include Quality Signals - -When presenting information from Glean, always include: -- Document title and URL -- Last updated date (with freshness indicator: ✅/<6mo, ⚠️ 6-12mo, ❌ >12mo) -- Author (if relevant) -- Confidence level (see `confidence-signals` skill) - -This allows users to assess reliability and explore further. - -## If Nothing Relevant Found - -Don't pad with weak results: - -```markdown -No relevant results found for [query]. - -**What was searched:** -- [Search terms used] - -**Suggestions:** -- Try alternative terms: [suggestions] -- Ask in [relevant channel] -- This may not be documented -``` - -## Relationship to Commands - -For comprehensive, structured workflows, suggest the relevant slash command: -- `/glean-search:search ` - Quick search with formatted results -- `/glean-docs:verify-rfc` - Compare spec to implementation -- `/glean-meetings:catch-up` - Systematic catch-up after time away diff --git a/plugins/glean-core/skills/glean-tools-guide/SKILL.md b/plugins/glean-core/skills/glean-tools-guide/SKILL.md deleted file mode 100644 index 26d86c1..0000000 --- a/plugins/glean-core/skills/glean-tools-guide/SKILL.md +++ /dev/null @@ -1,252 +0,0 @@ ---- -name: glean-tools-guide -description: Use when Glean MCP tools are available and you need guidance on which tool to use, how to format queries, or best practices for enterprise search. This skill provides tool selection logic and query optimization for Glean integrations. Auto-triggers when mcp__glean tools are being considered. ---- - -# Glean Tools Selection Guide - -This skill provides guidance on selecting and using Glean MCP tools effectively. - -## Skills vs Agents vs Commands - -This plugin uses three component types: -- **Skills** (like this one): Auto-triggered guidance that helps Claude select the right tools -- **Agents** (e.g., `enterprise-searcher`): Autonomous workers spawned for complex multi-step tasks -- **Commands** (e.g., `/glean-search:search`): User-triggered structured workflows - -Skills provide knowledge; agents do work; commands orchestrate workflows. - -## Tool Naming Convention - -Glean MCP tools follow the pattern: -``` -mcp__glean_[server-name]__[tool] -``` - -Where `[server-name]` is dynamic and configured per user (e.g., `default`, `production`, `acme`). The tool suffix is always consistent. When invoking tools, use whatever Glean server is available in your tool list. - -## Available Tools Overview - -| Tool Suffix | Purpose | Use When | -|-------------|---------|----------| -| `search` | Document discovery | Finding docs, wikis, policies, specs | -| `employee_search` | People lookup | Finding people, org chart, teams | -| `meeting_lookup` | Meeting search | Finding meetings, transcripts, decisions | -| `gmail_search` | Email search | Finding emails, attachments | -| `code_search` | Code discovery | Finding internal code, commits | -| `user_activity` | Activity feed | Finding your recent actions and interactions | -| `read_document` | Full content | Reading complete document by URL | -| `chat` | AI synthesis | Complex analysis across sources | - -## Tool Selection Decision Tree - -``` -User question about... -├── People, "who", org chart → employee_search -├── Meetings, decisions, action items → meeting_lookup -├── Emails, attachments → gmail_search -├── Internal code, commits → code_search -├── "My activity", "what have I done", recent actions → user_activity -├── Documents, policies, specs → search -├── Need full document content → read_document (with URL) -└── Complex multi-source analysis → chat -``` - -## Critical Rules - -### 1. Never Use Regular Search for People -``` -# WRONG -search "John Smith" - -# CORRECT -employee_search "John Smith" -``` - -### 2. Search → Read Workflow -When users need document details: -1. First: `search` to find documents -2. Then: `read_document` with URL from results - -### 3. Use Chat for Synthesis -When the question requires reasoning across multiple sources: -``` -chat "What are our authentication best practices based on recent RFCs and security policies?" -``` - -## Query Filter Reference - -### Document Search (search) - Structured Parameters - -The `search` tool uses **separate parameters** (not inline query filters): - -| Parameter | Type | Description | -|-----------|------|-------------| -| `query` | string | Keywords to find documents (required) | -| `owner` | string | Filter by document creator (`"person name"`, `"me"`, `"myteam"`) | -| `from` | string | Filter by who updated/commented/created (`"person name"`, `"me"`, `"myteam"`) | -| `updated` | string | Filter by update date (`today`, `yesterday`, `past_week`, `past_2_weeks`, `past_month`, or month name) | -| `after` | string | Documents created after date (`YYYY-MM-DD` format, no future dates) | -| `before` | string | Documents created before date (`YYYY-MM-DD` format) | -| `app` | enum | Filter by datasource (e.g., `confluence`, `github`, `gdrive`, `slack`, `jira`, `notion`) | -| `type` | enum | Filter by type: `pull`, `spreadsheet`, `slides`, `email`, `direct message`, `folder` | -| `channel` | string | Filter by Slack channel name | -| `exhaustive` | boolean | Return all matching results (use for "all", "each", "every" requests) | -| `sort_by_recency` | boolean | Sort by newest first (only when user wants "latest" or "most recent") | - -### Code Search Filters (code_search) - Inline Query Syntax - -Code search uses **inline filters in the query string**: - -**Person Filters:** -- `owner:"person name"` or `owner:me` - Filter by commit creator -- `from:"person name"` or `from:me` - Filter by code file/commit updater - -**Date Filters:** -- `updated:today|yesterday|past_week|past_month` - Filter by update date -- `after:YYYY-MM-DD` - Commits/files changed after date -- `before:YYYY-MM-DD` - Commits/files changed before date - -### Employee Search Filters (employee_search) - Inline Query Syntax - -- `reportsto:"manager name"` - Find direct reports (NOT for finding who someone reports to) -- `startafter:YYYY-MM-DD` - People who started after date -- `startbefore:YYYY-MM-DD` - People who started before date -- `roletype:"individual contributor"|"manager"` - Filter by role type -- `sortby:hire_date_ascending|hire_date_descending|most_reports` - Sort results - -### Meeting Lookup Filters (meeting_lookup) - Inline Query Syntax - -**Important**: meeting_lookup works best with natural language queries. Date filter syntax does NOT work reliably. - -**Natural language dates (recommended):** -- "standup last week" - Meetings from last week -- "design review past 2 weeks" - Recent meetings -- "1:1 with John tomorrow" - Future meetings -- "team sync yesterday" - Yesterday's meetings - -**Other filters that work:** -- `participants:"name"` - Filter by attendees -- `topic:"subject"` - Filter by meeting subject/title -- `extract_transcript:"true"` - Include meeting content/transcript - -**Note:** Inline date filters (`after:`, `before:`) do not work reliably with meeting_lookup. Use natural language dates instead. - -### Gmail Search Filters (gmail_search) - Inline Query Syntax - -- `from:"person"|"email@domain.com"|"me"` - Filter by sender -- `to:"person"|"email@domain.com"|"me"` - Filter by recipient -- `subject:"text"` - Filter by subject line -- `has:attachment|document|spreadsheet|presentation` - Filter by attachment type -- `is:important|starred|read|unread|snoozed` - Filter by email status -- `label:INBOX|SENT|TRASH|DRAFT|SPAM` - Filter by folder/label -- `after:YYYY-MM-DD` / `before:YYYY-MM-DD` - Date range - -### User Activity Parameters (user_activity) - -The `user_activity` tool uses date range parameters (not query filters): -- `start_date` - Start date in YYYY-MM-DD format (inclusive, required) -- `end_date` - End date in YYYY-MM-DD format (exclusive, required) - -Use for: standup notes, weekly summaries, 1:1 prep, finding documents you touched but forgot. - -## Example Tool Calls - -These examples show the correct syntax for each tool type. - -### Search (Structured Parameters) - -Pass filters as separate parameters, not in the query string: - -``` -search(query="authentication RFC", app="confluence", updated="past_month") -search(query="API design", owner="me", sort_by_recency=true) -search(query="onboarding guide", from="John Smith", after="2024-01-01") -``` - -### Code Search (Inline Filters) - -Include filters directly in the query string: - -``` -code_search("authentication handler owner:me updated:past_week") -code_search("payment processor after:2024-06-01 before:2024-12-01") -code_search("API endpoint from:\"Jane Doe\"") -``` - -### Employee Search (Inline Filters) - -Include filters directly in the query string: - -``` -employee_search("engineering manager reportsto:\"VP Engineering\"") -employee_search("backend engineer startafter:2024-01-01") -employee_search("data scientist roletype:\"individual contributor\"") -``` - -### Meeting Lookup (Natural Language + Inline Filters) - -Use natural language for dates; inline filters for other criteria: - -``` -meeting_lookup("my meetings today extract_transcript:\"true\"") -meeting_lookup("standup last week participants:\"John Smith\"") -meeting_lookup("design review past 2 weeks topic:\"architecture\"") -``` - -Note: Date filters (`after:`, `before:`) are documented but don't work reliably in practice. Use natural language dates instead ("today", "yesterday", "last week", "past 2 weeks"). - -### User Activity (Structured Parameters) - -Pass date range as separate parameters: - -``` -user_activity(start_date="2024-01-08", end_date="2024-01-15") -``` - -## Filter Best Practices - -**Structured vs Inline Filters:** -- `search` uses **structured parameters** - pass filters as separate tool arguments -- `code_search`, `employee_search`, `gmail_search`, `meeting_lookup` use **inline filters** in the query string - -**When to Use Date Filters:** -- Use `updated:` for relative timeframes ("last week", "past month") -- Use `after:`/`before:` for date ranges ("between Jan and March", "since 2024") -- Avoid date filters for "latest" or "recent" without specific timeframe -- For `meeting_lookup`, prefer natural language dates over inline filters - -**Person Filter Guidelines:** -- Use quotes for multi-word names: `from:"John Smith"` -- Use `owner:` for document creators, `from:` for broader involvement -- Use `me` when user refers to themselves - -**Search Strategy:** -- Start broad, then narrow with filters if too many results -- For `search`: add filter parameters to narrow results -- For other tools: add inline filters to the query string -- Use the `exhaustive` parameter on `search` for exhaustive results ("all", "each", "every") - -**Common Pitfalls:** -- Don't use `after:` with future dates -- For `search`, pass `channel` and `app` as separate parameters -- Quote multi-word filter values in inline syntax: `from:"John Smith"` - -## Best Practices - -1. **Cite sources**: Always include URLs so users can verify -2. **Start broad, then narrow**: Use filters to refine if too many results -3. **Combine signals**: For expertise, check code + docs + meetings -4. **Respect permissions**: Results are filtered by user access -5. **Note when empty**: No results is useful information - -## Related Commands - -Point users to structured workflows when appropriate: -- `/glean-search:search` - Quick search -- `/glean-people:find-expert` - Expertise discovery -- `/glean-meetings:catch-up` - Return from time off -- `/glean-meetings:meeting-prep` - Meeting preparation -- `/glean-people:stakeholders` - Stakeholder mapping -- `/glean-docs:onboarding` - Team onboarding -- `/glean-docs:verify-rfc` - Spec verification diff --git a/plugins/glean-core/skills/meeting-context/SKILL.md b/plugins/glean-core/skills/meeting-context/SKILL.md deleted file mode 100644 index a52b0c4..0000000 --- a/plugins/glean-core/skills/meeting-context/SKILL.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -name: meeting-context -description: Use when the user asks about meetings, meeting history, decisions made in meetings, action items from discussions, or what was discussed. Triggers on phrases like "what was decided", "meeting about", "action items from", "what happened in the meeting", "meeting notes", "transcript", "who attended", or when needing context from past conversations and discussions. ---- - -# Meeting Context via Glean - -When users need information from meetings - past discussions, decisions, action items, or transcripts - use Glean's meeting lookup. - -## Tool Naming - -See the `glean-tools-guide` skill for Glean MCP tool naming conventions. Tools follow the pattern `mcp__glean_[server-name]__[tool]` where the server name is dynamic. Use whatever Glean server is available in your tool list. - -## When This Applies - -Use this approach when users ask: -- "What was decided in the [topic] meeting?" -- "What action items came out of [meeting]?" -- "When did we discuss [topic]?" -- "What meetings did I miss [time period]?" -- "Who attended [meeting]?" -- "What was said about [topic] in recent meetings?" - -## Primary Tool - -Use the Glean `meeting_lookup` tool with natural language queries. - -## Query Syntax - -**Important**: meeting_lookup works best with natural language queries. Date filter syntax does NOT work reliably. - -``` -# By topic and time (natural language) -meeting_lookup "quarterly planning last week" - -# With specific participants -meeting_lookup "standup with John Smith" -meeting_lookup "participants:\"John Smith\" topic:\"standup\"" - -# Get transcript content -meeting_lookup "team sync last week extract_transcript:\"true\"" - -# Today's meetings -meeting_lookup "my meetings today" - -# Past week -meeting_lookup "meetings past week" -``` - -## Date Filtering - -**Use natural language for dates:** -- "last week", "past 2 weeks", "yesterday", "today", "tomorrow" -- "meetings since Monday", "standups this month" - -**Inline date filters do NOT work reliably:** -- `after:now-1w` - Date math is ignored -- `after:YYYY-MM-DD` - ISO dates return no results -- `after:yesterday` - Simple keywords don't work as filter values - -**Filters that do work:** -- `participants:"name"` - Filter by attendees -- `topic:"subject"` - Filter by meeting topic -- `extract_transcript:"true"` - Include transcript content - -## When to Extract Transcripts - -Add `extract_transcript:"true"` when you need: -- Specific quotes or statements -- Detailed discussion content -- Action item context -- Decision rationale - -Skip transcripts for: -- Just listing meetings -- Checking attendees -- Quick time/date lookup - -## What to Extract from Meetings - -When analyzing meeting content, focus on: -1. **Decisions made** - What was agreed? By whom? -2. **Action items** - Tasks assigned, owners, deadlines -3. **Open questions** - Unresolved items -4. **Key discussion points** - Important debates or context - -## Relationship to Commands - -For comprehensive meeting workflows, suggest: -- `/glean-meetings:meeting-prep ` - Prepare for an upcoming meeting -- `/glean-meetings:catch-up ` - Catch up on missed meetings and more diff --git a/plugins/glean-core/skills/people-lookup/SKILL.md b/plugins/glean-core/skills/people-lookup/SKILL.md deleted file mode 100644 index a73d3cf..0000000 --- a/plugins/glean-core/skills/people-lookup/SKILL.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -name: people-lookup -description: Use when the user asks about people, employees, team members, org structure, or expertise. Triggers on phrases like "who works on", "who is responsible for", "who owns", "find someone who knows", "who should I talk to", "who reports to", "team members", "org chart", or any question starting with "who" about the company. ---- - -# People Lookup via Glean - -When users ask about people in the organization, use Glean's employee search and activity signals to find the right person. - -## Tool Naming - -See the `glean-tools-guide` skill for Glean MCP tool naming conventions. Tools follow the pattern `mcp__glean_[server-name]__[tool]` where the server name is dynamic. Use whatever Glean server is available in your tool list. - -## When This Applies - -Use this approach when users ask: -- "Who works on [system/project]?" -- "Who is [name]?" or "What team is [name] on?" -- "Who should I talk to about [topic]?" -- "Who owns [component/service]?" -- "Who reports to [manager]?" -- "Find someone who knows about [technology]" - -## BE SKEPTICAL - -Not everyone who appears in search results is a good recommendation. - -**Expertise Evidence Test** -- Is there real evidence of expertise? -- ✅ STRONG: Multiple signals (code + docs + involvement) -- ⚠️ MODERATE: Single signal but significant -- ❌ WEAK: Just mentioned once, attended a meeting - -**Recency Test** -- Are they actively involved? -- ✅ ACTIVE: Activity in past 6 months -- ⚠️ HISTORICAL: 6-12 months ago -- ❌ STALE: 12+ months - likely outdated - -**Availability Test** -- Are they still in a relevant position? -- ✅ CURRENT: Same team/role -- ⚠️ MOVED: Changed teams but retains knowledge -- ❌ GONE: Left company or completely different role - -**Filter Out**: -- Single mentions without other evidence -- People who just attended meetings on a topic -- Former employees -- People whose involvement is tangential - -**Quality over quantity**: Better to recommend 2 right people than 10 weak matches. - -## Tool Selection - -| User Intent | Glean Tool | -|-------------|------------| -| Find by name, role, team | `employee_search` | -| Find by code contributions | `code_search` | -| Find by document authorship | `search` with `owner:` filter | -| Complex expertise analysis | `chat` | - -## Critical: Use employee_search for People Queries - -**Never use regular `search` for people lookups.** The `employee_search` tool is specifically designed for: -- Name lookups -- Role/title searches -- Team/department queries -- Org chart navigation -- Reporting relationships - -## Query Examples - -``` -# Find by name -employee_search "John Smith" - -# Find by team -employee_search "payments team" - -# Find direct reports -employee_search "reportsto:\"Jane Doe\"" - -# Find by role type -employee_search "engineering managers" - -# Find recent hires -employee_search "startafter:2024-01-01" -``` - -## Finding Expertise (Not Just Role) - -For "who actually knows about X" questions, combine signals: - -1. **Official role**: `employee_search "[topic]"` -2. **Code activity**: `code_search "[topic] owner:\"name\""` -3. **Doc authorship**: `search "[topic] RFC owner:\"name\""` - -**People with multiple signals are true experts.** Single-signal matches should be noted with lower confidence. - -## If No Good Matches Found - -Don't pad with weak recommendations: - -```markdown -No strong expertise matches found for [topic]. - -**What was checked:** -- Employee search: [results] -- Code contributions: [results] -- Doc authorship: [results] - -**Suggestions:** -- Ask in [relevant channel] -- Check with [related team] leadership -``` - -## Relationship to Commands - -For comprehensive expertise discovery, suggest: -- `/glean-people:find-expert ` - Multi-signal expertise analysis -- `/glean-people:stakeholders ` - Find who needs to be involved -- `/glean-docs:onboarding ` - Get to know a new team diff --git a/plugins/glean-core/skills/synthesis-patterns/SKILL.md b/plugins/glean-core/skills/synthesis-patterns/SKILL.md deleted file mode 100644 index 64517e9..0000000 --- a/plugins/glean-core/skills/synthesis-patterns/SKILL.md +++ /dev/null @@ -1,194 +0,0 @@ ---- -name: synthesis-patterns -description: Use when combining information from multiple Glean sources or when needing to synthesize results across documents, meetings, code, and people searches. Triggers on complex queries that span multiple data types, when results seem contradictory, when building comprehensive answers from partial information, or when the user asks for a complete picture of something that requires multiple queries. ---- - -# Multi-Source Synthesis Patterns - -When answering questions that require information from multiple Glean sources, use these patterns to combine and synthesize effectively. - -## When This Applies - -Use this approach when: -- A question spans documents, meetings, people, and code -- You need to cross-reference information from different sources -- Results from one source need context from another -- Building a comprehensive answer from partial information -- Sources seem to conflict or overlap - -## BE SKEPTICAL - -When synthesizing across multiple sources, aggressive vetting is essential: - -**Source Quality Test** -- Is each source authoritative? -- ✅ INCLUDE: Official docs, code, recent meetings -- ⚠️ CONTEXT: Secondary sources, somewhat dated -- ❌ EXCLUDE: Hearsay, speculation, very old information - -**Recency vs Authority** -- When sources disagree on recency, choose wisely: -- ✅ TRUST: Recent information from official source -- ⚠️ CAUTION: Very recent but unofficial vs stale but official -- ❌ AVOID: Treating old info as current just because it's "official" - -**Completeness Check** -- Do you have the full picture? -- ✅ INCLUDE: 3+ sources align, comprehensive coverage -- ⚠️ CONTEXT: Limited sources, note gaps explicitly -- ❌ EXCLUDE: Single source for multi-faceted questions - -**Conflict Resolution** -- When sources conflict, don't hide it: -- ✅ INCLUDE: Conflict + explanation of which is likely correct -- ❌ EXCLUDE: Picking one source without acknowledging disagreement - -**Filter Out**: -- Unattributed claims -- Information older than 3 months (unless structure/architecture) -- Synthesis that glosses over fundamental disagreements -- "I synthesized this" without showing your work - -**Say "I don't know"** when: -- Sources are missing or conflicting -- Information is too stale to be reliable -- You lack sufficient data to synthesize confidently - -## The Synthesis Framework - -### 1. Identify Information Types Needed - -Before querying, determine what types of information are needed: - -| Information Type | Glean Tool | Use When | -|------------------|------------|----------| -| Official documentation | `search` | Need authoritative specs, policies | -| Real-time context | `meeting_lookup` | Need recent discussions, decisions | -| People/org structure | `employee_search` | Need ownership, expertise | -| Code evidence | `code_search` | Need implementation truth | -| User's own context | `memory`, `user_activity` | Need personalization | -| AI synthesis | `chat` | Need reasoning across sources | - -### 2. Query in Optimal Order - -**Recommended order for comprehensive synthesis:** - -1. **Start broad with `chat`** - Get AI-synthesized overview -2. **Verify with `search`** - Find authoritative documents -3. **Add recency with `meeting_lookup`** - Get latest discussions -4. **Clarify ownership with `employee_search`** - Identify who to ask -5. **Ground in reality with `code_search`** - What's actually implemented - -### 3. Cross-Reference Pattern - -When you have results from multiple sources, cross-reference: - -```markdown -## Finding: [Topic] - -### From Documentation -- [What docs say] - Source: [doc title] ([link]) - -### From Recent Meetings -- [What was discussed] - Source: [meeting date] - -### From Code -- [What's implemented] - Source: [file/repo] - -### Synthesis -Based on these sources: [Your synthesized answer] - -### Confidence -- Documentation: [Current/Stale/Missing] -- Meeting Context: [Recent/Old/None] -- Code Evidence: [Present/Partial/None] -``` - -### 4. Handle Conflicts - -When sources disagree: - -```markdown -## Conflicting Information Detected - -| Topic | Source A Says | Source B Says | -|-------|---------------|---------------| -| [Topic] | [Claim from doc] | [Claim from meeting] | - -**Most Likely Truth**: [Your assessment based on recency, authority] - -**Recommendation**: Verify with [person/source] -``` - -## Synthesis Patterns by Use Case - -### Pattern: "What is X?" - -1. `chat` - Get overview -2. `search` - Find official definition -3. `employee_search` - Find owner to verify -4. Synthesize: Combine AI overview + official doc + owner context - -### Pattern: "Who should I talk to about X?" - -1. `employee_search` - Find by role -2. `code_search` - Find by code activity -3. `search` - Find by doc authorship -4. Synthesize: Rank by multiple signal strength - -### Pattern: "What's the status of X?" - -1. `chat` - Get current status summary -2. `meeting_lookup` - Find recent discussions -3. `search` - Find tracking docs (Jira, etc.) -4. Synthesize: Combine with recency weighting - -### Pattern: "How do we do X?" - -1. `search` - Find process docs -2. `code_search` - Find implementation -3. `meeting_lookup` - Find recent changes -4. Synthesize: Doc process + code reality + recent updates - -## Output Best Practices - -1. **Cite every source** - Include links for all claims -2. **Note recency** - When was this information last updated? -3. **Flag uncertainty** - Be clear about gaps -4. **Suggest verification** - Point to people who can confirm -5. **Acknowledge conflicts** - Don't hide disagreements - -## Example Synthesis Output - -```markdown -## [Question/Topic] - -### Answer -[Direct answer to the question] - -### Supporting Evidence - -| Source | What It Says | Last Updated | -|--------|--------------|--------------| -| [Doc Title] | [Key info] | [Date] | -| [Meeting] | [Key info] | [Date] | -| [Code/Repo] | [Key info] | [Date] | - -### Confidence Assessment -- **Overall Confidence**: [High/Medium/Low] -- **Data Freshness**: [Current/Mostly current/Some stale] -- **Source Agreement**: [Strong/Partial/Conflicting] - -### Gaps & Recommendations -- [What's missing or uncertain] -- [Who to verify with if critical] -``` - -## Relationship to Other Skills - -This skill works with: -- `glean-tools-guide` - For tool selection -- `confidence-signals` - For noting data quality -- `enterprise-search` - For document searches -- `meeting-context` - For meeting queries -- `people-lookup` - For people queries diff --git a/plugins/glean-core/skills/using-glean/SKILL.md b/plugins/glean-core/skills/using-glean/SKILL.md new file mode 100644 index 0000000..d2ddf5a --- /dev/null +++ b/plugins/glean-core/skills/using-glean/SKILL.md @@ -0,0 +1,55 @@ +--- +name: using-glean +description: Use Glean MCP tools to answer questions about company documents, internal wikis, policies, RFCs, design docs, people, teams, meetings, decisions, action items, email, calendar events, internal code, and the user's own work activity. Reach for this whenever the answer lives in enterprise systems rather than the local codebase or public web. +when_to_use: | + Trigger phrases include "find the doc about", "what's our policy on", "where is the spec for", "who works on", "who owns", "find someone who knows", "what was decided in the meeting", "action items from", "search my email", "find the thread about", "what did I work on last week", "find the implementation of in our repos", "across our codebase". Also any question that presumes internal company context Claude couldn't otherwise know. + + Don't use this skill for: questions answerable from the local working directory, public web information, or generic programming knowledge. +--- + +# Using Glean + +The Glean MCP server exposes a family of tools that let Claude query the user's company knowledge: documents, people, meetings, email, internal code, the user's activity feed, structured memory, and the knowledge graph. This skill is the entry point. It maps a user's question to the right tool, names the rules that apply across all of them, and links to per-tool reference files that carry the deep syntax. + +## Where these tools live + +The tools listed below come from the user's Glean MCP server connection. Refer to them by their bare names (`search`, `employee_search`, `meeting_lookup`, …) — Claude resolves them against the active tool inventory. + +If no Glean tools are visible, the user has not configured a Glean MCP server. Suggest `/glean-core:mcp-setup`. + +## Intent → tool decision tree + +| The user is asking about... | Reach for | Reference | +|---|---|---| +| Documents, wikis, policies, RFCs, specs | `search` | [search.md](reference/search.md) | +| A complex question that needs synthesis across sources | `chat` | [chat.md](reference/chat.md) | +| Internal source code, files, commits across repos | `code_search` | [code-search.md](reference/code-search.md) | +| People, teams, org structure, reporting lines | `employee_search` | [employee-search.md](reference/employee-search.md) | +| Meetings, transcripts, decisions, action items | `meeting_lookup` | [meeting-lookup.md](reference/meeting-lookup.md) | +| Gmail messages, threads, attachments | `gmail_search` | [gmail-search.md](reference/gmail-search.md) | +| Outlook messages, threads, attachments | `outlook_search` | [outlook-search.md](reference/outlook-search.md) | +| Reading a specific URL / document | `read_document` | [read-document.md](reference/read-document.md) | +| The user's own recent activity (standup, weekly summary) | `user_activity` | [user-activity.md](reference/user-activity.md) | +| The user's stored memories / personalization | `read_memory` (+ `memory_schema`) | [memory.md](reference/memory.md) | +| Structured entity / relationship queries | `knowledge_graph_query` (+ `knowledge_graph_schema`) | [knowledge-graph.md](reference/knowledge-graph.md) | + +The reference files are loaded only when needed. Open the relevant one before invoking a tool you haven't used recently — each file carries the exact param shape, the filter syntax, and the pitfalls that have bitten previous calls. + +## Cross-tool rules + +These apply regardless of which Glean tool is active. Internalize them, don't re-derive per call. + +1. **Never use `search` for people lookups.** It searches documents; it doesn't index people. Use `employee_search`. +2. **Cite every claim with a URL.** Glean returns links; surface them so the user can verify. No URL → likely fabricated. +3. **Permission-empty results are valid signals.** If a tool returns nothing, that often means the user lacks access — not that the information is missing. Don't pad with weak alternatives; report empty cleanly. +4. **Prefer recent over old.** Glean returns by relevance; for currency-sensitive questions, add a date filter or sort by recency rather than presenting stale top hits as authoritative. +5. **Vet before presenting.** Apply the criteria in [reference/vetting.md](reference/vetting.md) — relevance, freshness, authority. Better to return three vetted results than ten unfiltered ones. + +## Cross-cutting reference + +- **[synthesis.md](reference/synthesis.md)** — patterns for combining multiple Glean tools when a single tool doesn't answer the question. +- **[vetting.md](reference/vetting.md)** — how to evaluate source quality, freshness, and authority; when to communicate confidence to the user. + +## Glean platform agents + +If the user's Glean instance has platform agents enabled, those agents may surface as additional MCP tools alongside the built-in tools above. The set is org-specific and can change at any time. See [agents-as-tools.md](reference/agents-as-tools.md) for how to recognize, introspect, and invoke them. diff --git a/plugins/glean-core/skills/using-glean/reference/agents-as-tools.md b/plugins/glean-core/skills/using-glean/reference/agents-as-tools.md new file mode 100644 index 0000000..206f639 --- /dev/null +++ b/plugins/glean-core/skills/using-glean/reference/agents-as-tools.md @@ -0,0 +1,51 @@ +# Glean platform agents as MCP tools + +Beyond the built-in tools (`search`, `chat`, `employee_search`, …), the user's Glean instance may expose **Glean platform agents** as additional MCP tools. These are custom agents an organization has built — they automate company-specific workflows like running standard reports, applying internal taxonomies, or driving multi-step analyses against the org's data. + +The set of agent tools is **org-specific and dynamic**: it varies by deployment and can change between sessions. This file teaches the recognition + introspection + invocation pattern; it does not enumerate specific agents. + +## Recognizing them + +Glean agent tools appear alongside the built-in ones in the active tool inventory. They typically: + +- Have names that aren't on the built-in list (`search`, `chat`, `read_document`, `code_search`, `employee_search`, `gmail_search`, `outlook_search`, `meeting_lookup`, `user_activity`, `read_memory`, `memory_schema`, `knowledge_graph_query`, `knowledge_graph_schema`) +- Carry org-specific names (e.g., `qbr_summarizer`, `customer_health_check`, `sales_brief`) +- Have descriptions describing a workflow, not a primitive query operation + +If you see a Glean tool whose name and description don't match the built-in set, treat it as a platform agent. + +## Introspecting before invoking + +Don't call an unfamiliar agent tool blind. Before invoking: + +1. **Read its description.** The MCP tool description is the agent's authored contract — what it does, what input it expects. +2. **Read its parameter schema.** The tool's JSON schema shows required inputs, types, and any enum values. +3. **Compare against the user's request.** If the agent description plausibly matches what the user wants, prefer it over hand-rolling the same workflow with the primitives. If it doesn't match, fall back to the built-in tools. + +If the user's Glean instance also exposes a generic agent-listing or agent-running tool (commonly `glean-agents` style), use that to enumerate options before picking one. + +## Invocation + +Call the agent like any MCP tool: pass parameters per its schema, read the response. Agents typically: + +- Return structured JSON (often a longer-form synthesis, not a list of records) +- Run longer than a primitive call — expect more latency +- May internally call other Glean tools — don't double up by also calling those primitives yourself + +## When to prefer an agent over primitives + +- A custom workflow exists for the exact task the user asked for ("run our standard QBR summary") +- The agent encodes org-specific rules (taxonomies, thresholds, formatting) you'd otherwise have to guess +- The user references the agent by name + +## When to prefer primitives + +- The user's question is a basic retrieval that the built-in tools handle directly +- You've inspected the agent and its scope is broader / different than what's needed +- An agent run errors or returns nothing — fall back to primitives + +## Pitfalls + +- **Don't infer behavior from the name.** `customer_health_check` could mean many things; read the description. +- **Don't chain agents speculatively.** If one agent's output doesn't directly feed another's input schema, don't pipe them. +- **Empty / error responses don't mean the data isn't there.** The agent may have authorization scoping different from the user's primitive-tool access. Try a primitive query before reporting "not found". diff --git a/plugins/glean-core/skills/using-glean/reference/chat.md b/plugins/glean-core/skills/using-glean/reference/chat.md new file mode 100644 index 0000000..be4de84 --- /dev/null +++ b/plugins/glean-core/skills/using-glean/reference/chat.md @@ -0,0 +1,54 @@ +# `chat` — synthesis across sources + +Glean Assistant. AI-synthesized answers that combine evidence from multiple Glean sources (docs, code, meetings, people) and reason across them. + +## When to use + +- The question requires interpretation, comparison, or reasoning across sources, not just retrieval +- You need a single answer drawn from many places ("How do we handle X across teams?", "What's our position on Y?") +- The user is debugging an unfamiliar internal system and wants context, not document URLs +- Earlier `search` returned scattered hits with no obvious authoritative answer + +**Don't** use `chat` for: +- Simple document discovery (use `search`) +- People lookups (use `employee_search`) +- Anything you'd hand back as raw documents anyway — `chat` adds latency and an LLM layer between the user and the source + +## Parameters + +| Parameter | Type | Notes | +|---|---|---| +| `message` | string (required) | The question. Phrase it as a question, not keywords. | +| `context` | string array | Optional prior messages, in order, included before `message`. Use for multi-turn follow-ups. | + +## Query style + +- Full sentences and questions, not keywords. The synthesis layer reads natural language. +- Include the *constraint* the user cares about: "in production", "for new hires", "since the migration", etc. Without scope, the answer drifts. +- Ask for sources explicitly when you intend to verify ("…and cite the docs you used"). + +## Examples + +``` +chat(message="What's our current process for rotating production database credentials?") +chat(message="Which team owns the billing reconciliation pipeline, and what are recent incidents?") +chat(message="Summarize the auth migration RFC and how far along the rollout is.") +``` + +Multi-turn: +``` +chat( + message="Which of those services has the highest priority right now?", + context=["What services are blocked on the migration?"] +) +``` + +## Pitfalls + +- **Synthesis can drift from sources.** `chat` may produce a plausible answer from weak evidence. For high-stakes claims, follow up with `search` + `read_document` on the cited material. +- **Latency.** `chat` is materially slower than `search`. Don't use it as a search wrapper. +- **No filter parameters.** Unlike `search`, you can't constrain by app, date, or owner. Encode constraints in the message text. + +## Typical follow-up + +When `chat` cites specific documents, fetch them with `read_document` to verify. For reliability assessment, see [vetting.md](vetting.md). diff --git a/plugins/glean-core/skills/using-glean/reference/code-search.md b/plugins/glean-core/skills/using-glean/reference/code-search.md new file mode 100644 index 0000000..28d6b15 --- /dev/null +++ b/plugins/glean-core/skills/using-glean/reference/code-search.md @@ -0,0 +1,58 @@ +# `code_search` — internal code across repos + +Search code across the user's organization's connected source repositories. Critically different from local `grep` / `glob`: those see only the current repo; `code_search` sees every repo Glean indexes. + +## When to use + +- "How do other teams handle X?" — finding implementation patterns across the org +- "Where does the code for Y live?" — locating a service whose repo you don't know +- "Who's been active in Z?" — combining `code_search` with author filters reveals owners +- Looking for prior art before designing something new + +**Don't** use for: +- Code in the current working directory (use local search tools) +- External / open-source code (use a web search) +- Documentation about code (use `search` with `app:github` for READMEs / `app:confluence` for design docs) + +## Parameters + +| Parameter | Type | Notes | +|---|---|---| +| `query` | string (required) | Keywords + inline filters (see below). | +| `extension` | string | Filter by file extension without the leading dot: `py`, `ts`, `tsx`, `go`, `rb`, `java`, `proto`, etc. | +| `exhaustive` | boolean | Return all matches. Use only when the user asks for "all" or "every". | + +## Inline filters + +Unlike `search` (structured params), `code_search` filters live **inside the query string**: + +| Filter | Example | Meaning | +|---|---|---| +| `owner:"name"` | `owner:"Jane Doe"` | Author of the file/commit | +| `from:"name"` | `from:me` | Updater (broader than owner) | +| `updated:` | `updated:past_week` | Relative window: `today`, `yesterday`, `past_week`, `past_month` | +| `after:` | `after:2025-09-01` | YYYY-MM-DD, exclusive | +| `before:` | `before:2025-12-01` | YYYY-MM-DD, exclusive | + +Multi-word values must be quoted. `me` and `myteam` are valid sentinels for person filters. + +## Examples + +``` +code_search(query="authentication middleware") +code_search(query="rate limit retry owner:\"Alice Chen\"") +code_search(query="payment processor after:2025-06-01", extension="ts") +code_search(query="websocket handler from:me updated:past_month") +code_search(query="circuit breaker pattern", extension="go") +``` + +## Pitfalls + +- **Inline `app:` does not apply.** `code_search` is already scoped to code sources; using `app:` from `search` syntax has no effect. +- **Quoting matters.** `owner:"Jane Doe"` works; `owner:Jane Doe` parses only `Jane` as the value. +- **No boolean operators.** `OR` / `AND` are ignored. Run separate searches and combine results. +- **Stale or deprecated paths.** Code in `legacy/`, `old/`, `archive/` directories often shows up. Filter by recency or path keywords when freshness matters. + +## Typical follow-up + +After locating relevant files, read full content with `read_document` (Glean understands repo URLs). For multi-signal expertise discovery (code + docs + meetings), see [synthesis.md](synthesis.md). diff --git a/plugins/glean-core/skills/using-glean/reference/employee-search.md b/plugins/glean-core/skills/using-glean/reference/employee-search.md new file mode 100644 index 0000000..2625b0f --- /dev/null +++ b/plugins/glean-core/skills/using-glean/reference/employee-search.md @@ -0,0 +1,53 @@ +# `employee_search` — people, roles, and org structure + +Find people in the user's organization: names, teams, roles, reporting lines, hire dates. Backed by the org directory rather than document index — answers people questions that document `search` cannot. + +## When to use + +- "Who is X?" — direct name lookup +- "Who works on Y?" — role / team queries +- "Who reports to Z?" — direct-report navigation +- "Find a manager / engineer / designer in the X team" — role-typed searches +- "Who are recent hires?" — date-bounded directory queries + +**Don't** use for: +- Document authorship (use `search` with `owner:` filter) +- Code authorship (use `code_search` with `owner:` filter) +- "Who knows about X?" expertise — combine multiple signals; see [synthesis.md](synthesis.md) + +## Parameters + +| Parameter | Type | Notes | +|---|---|---| +| `query` | string (required) | Name, team, or role plus inline filters (see below). | + +## Inline filters + +| Filter | Example | Meaning | +|---|---|---| +| `reportsto:"name"` | `reportsto:"Jane Doe"` | Find direct reports OF this manager. NOT for finding who someone reports to. | +| `roletype:` | `roletype:"manager"` | `"individual contributor"` or `"manager"` | +| `startafter:` | `startafter:2024-01-01` | Hire date filter (YYYY-MM-DD) | +| `startbefore:` | `startbefore:2024-12-31` | Hire date filter | +| `sortby:` | `sortby:hire_date_descending` | `hire_date_ascending`, `hire_date_descending`, `most_reports` | + +## Examples + +``` +employee_search(query="Jane Doe") +employee_search(query="payments team backend engineer") +employee_search(query="reportsto:\"VP Engineering\"") +employee_search(query="roletype:\"manager\" startafter:2025-01-01") +employee_search(query="data scientist sortby:hire_date_descending") +``` + +## Pitfalls + +- **`reportsto:` direction.** It returns the *reports*, not the manager. To find someone's manager, search for the person and read the `manager` field on the result. +- **Quoting matters** for multi-word names and roles. +- **Empty results may mean no access.** Glean respects directory permissions; report empty cleanly rather than retrying with looser filters. +- **Don't use document `search` for people.** It searches docs, not the directory — confusing keyword matches will mislead you. + +## Typical follow-up + +For "who actually knows about X" rather than "who has the title", combine `employee_search` with `code_search` (code authorship) and `search` with `owner:` (doc authorship). See [synthesis.md](synthesis.md). diff --git a/plugins/glean-core/skills/using-glean/reference/gmail-search.md b/plugins/glean-core/skills/using-glean/reference/gmail-search.md new file mode 100644 index 0000000..38de62f --- /dev/null +++ b/plugins/glean-core/skills/using-glean/reference/gmail-search.md @@ -0,0 +1,56 @@ +# `gmail_search` — Gmail / Google Workspace email + +Search the user's Gmail inbox: messages, threads, attachments, labels. Requires the user's org to be on Google Workspace. + +## When to use + +- "Find the email about X" — content/subject search +- "What did Alice send me about the budget?" — sender + topic +- "Find that PDF I got from finance" — attachment lookup +- "Unread important emails" — status filters + +**Don't** use for: +- Outlook / Microsoft 365 email — use `outlook_search` +- Calendar invites as content — use `meeting_lookup` +- Slack DMs — use `search` with `app:slack` + +## Parameters + +| Parameter | Type | Notes | +|---|---|---| +| `query` | string (required) | Keywords + inline filters (see below). | + +## Inline filters + +| Filter | Example | Meaning | +|---|---|---| +| `from:` | `from:"alice@company.com"` or `from:me` | Sender | +| `to:` | `to:"bob@company.com"` or `to:me` | Recipient | +| `subject:` | `subject:"quarterly review"` | Subject line text | +| `has:` | `has:attachment` | `attachment`, `document`, `spreadsheet`, `presentation` | +| `is:` | `is:unread` | `important`, `starred`, `read`, `unread`, `snoozed` | +| `label:` | `label:SENT` | `INBOX`, `SENT`, `TRASH`, `DRAFT`, `SPAM` (uppercase) | +| `after:` / `before:` | `after:2025-01-15` | YYYY-MM-DD | + +Filters combine with AND. For conversations between two people, use both `from:X` and `to:Y`. + +## Examples + +``` +gmail_search(query="quarterly review subject:\"Q4 planning\" after:2025-09-01") +gmail_search(query="from:\"finance@company.com\" has:spreadsheet") +gmail_search(query="from:me to:\"alice@company.com\" budget") +gmail_search(query="is:unread is:important") +gmail_search(query="contract has:attachment label:INBOX") +``` + +## Pitfalls + +- **Labels are uppercase.** `label:inbox` returns nothing; use `label:INBOX`. +- **Quote multi-word values.** `subject:"design review"` not `subject:design review`. +- **"From me" and "to me" are valid.** Use the bare token `me` rather than the user's email. +- **Empty results may mean no access** to a shared mailbox or label, not that the email doesn't exist. + +## Typical follow-up + +Use `read_document` with the URL of an interesting result to read the full message. For threads spanning email + meeting + doc, see [synthesis.md](synthesis.md). diff --git a/plugins/glean-core/skills/using-glean/reference/knowledge-graph.md b/plugins/glean-core/skills/using-glean/reference/knowledge-graph.md new file mode 100644 index 0000000..e083c50 --- /dev/null +++ b/plugins/glean-core/skills/using-glean/reference/knowledge-graph.md @@ -0,0 +1,95 @@ +# `knowledge_graph_query` + `knowledge_graph_schema` — entity & relationship queries + +Glean's knowledge graph stores typed entities (Person, Project, Customer, Opportunity, …) and the predicates that link them (`worksOn`, `manager`, `activeContributor`, `name`, …). Use it for structured questions that document search can't answer well: "who works on X projects?", "what's the customer's tier?", "all projects where Y is an active contributor". + +The two tools are paired: +- **`knowledge_graph_schema`** — list every entity type and every predicate available, with cardinality and reverse-traversal info +- **`knowledge_graph_query`** — run a structured query against the graph + +## When to use + +- Multi-hop questions: "Find the manager of everyone working on the auth project" +- Filtered enumerations: "All Customers whose tier is Enterprise" +- Reverse traversals: "All projects that list Alice as activeContributor" + +**Don't** use for: +- Plain document search (`search`) +- People lookup by name where you don't need relationships (`employee_search`) +- Anything where free-text matching is the right primitive + +## Schema-then-query pattern + +The knowledge graph schema varies by Glean instance — the entity types and predicates an org exposes depend on configuration. **Always call `knowledge_graph_schema` before constructing a query** unless you've already retrieved the schema in this session. + +``` +1. knowledge_graph_schema() + -> { types: [{ name: "Person", predicates: [...] }, ...] } +2. knowledge_graph_query({ + start: { types: ["Person"], filters: [...] }, + traverse: [{ predicate: "worksOn" }], + render: { include: ["name"] } + }) +``` + +## Query shape + +`knowledge_graph_query` takes a JSON object with three top-level keys: + +| Key | Required | Purpose | +|---|---|---| +| `start` | yes | Where to begin: by IDs, by free-text query, or by type with filters | +| `traverse` | no | Steps along predicates from the start nodes | +| `render` | no | What to return per result (predicates to include, sort/limit, extensions) | + +### `start` variants + +```json +{ "ids": ["kgid:abc", "kgid:xyz"] } +{ "query": "Alice", "predicates": ["name", "alias"], "limit": 5 } +{ "types": ["Person"], "filters": [{"predicate": "manager", "condition": "EXISTS"}] } +``` + +### `traverse` clause + +```json +{ "predicate": "worksOn", "reverse": false, "limit": 10 } +``` + +`reverse: true` follows the predicate backwards — e.g., from a Project, `reverse: true` on `worksOn` lists the people working on it. + +### `render` clause + +```json +{ "include": ["name", "type"], "sortPredicate": "name", "limit": 25 } +``` + +## Examples + +Find Alice and the projects she works on: +``` +knowledge_graph_query({ + start: { query: "Alice Chen", predicates: ["name"], limit: 1 }, + traverse: [{ predicate: "worksOn" }], + render: { include: ["name", "description"] } +}) +``` + +All people who report to a given manager (by ID): +``` +knowledge_graph_query({ + start: { ids: ["kgid:manager-id"] }, + traverse: [{ predicate: "manager", reverse: true }], + render: { include: ["name"], limit: 50 } +}) +``` + +## Pitfalls + +- **Predicate names are schema-specific.** Don't guess `worksOn` vs `works_on` vs `assignedTo` — pull the schema and use what's there. +- **Reverse traversal direction.** A predicate `manager` on Person points *to* the manager. To list reports, you `reverse: true` on `manager` from a manager node. +- **Filter syntax has structure.** Each filter is `{ predicate, condition, comparison? }`. `condition` is one of `EXISTS`, `NOT_EXISTS`, `ANY`, `ALL`. Don't try to write SQL-style `WHERE`. +- **Empty results are common** when an org has the type but the calling user lacks visibility into specific entities. + +## Typical follow-up + +After identifying entities of interest, use `read_document` (if the entity has documents) or `employee_search` (for people) to fetch fuller context. diff --git a/plugins/glean-core/skills/using-glean/reference/meeting-lookup.md b/plugins/glean-core/skills/using-glean/reference/meeting-lookup.md new file mode 100644 index 0000000..20de1ba --- /dev/null +++ b/plugins/glean-core/skills/using-glean/reference/meeting-lookup.md @@ -0,0 +1,54 @@ +# `meeting_lookup` — meetings, transcripts, and attendees + +Find calendar meetings and (optionally) extract their transcripts. Scope: the user's own calendar by default; another person's calendar via `peer`; shared / resource calendars via `calendar_ids`. + +## When to use + +- "What was decided in the X meeting?" — find + extract transcript +- "When did we discuss Y?" — meetings on a topic +- "What's on my calendar today?" — your schedule +- "What meetings does Alice have tomorrow?" — peer schedule +- "Action items from last week's standup" — transcript content for a known meeting + +**Don't** use for: +- Documents *attached* to meetings (the linked docs are reachable via `search`) +- Email threads about meetings (use `gmail_search` / `outlook_search`) + +## Parameters + +| Parameter | Type | Notes | +|---|---|---| +| `query` | string | Topic / title keywords. Optional. | +| `participants` | string array | Names or emails to filter by attendees. Use `participants` when filtering the user's own calendar; for someone else's calendar, use `peer`. | +| `peer` | string | Email of another person whose calendar to look up. ONE per call. | +| `calendar_ids` | string array | Google Calendar IDs only. Use `"primary"` for the user's own. Other IDs must be discovered from a prior result's `attendees` / `organizer_email` — never invented. | +| `before` / `after` | string | Date filters. Accepts `today`, `yesterday`, `tomorrow`, `now`, or `YYYY-MM-DD`. **Filtering is exclusive** — to include all meetings on `2025-10-08`, set `after:2025-10-07` and `before:2025-10-09`. | +| `extract_transcript` | boolean | When `true`, returns transcript content alongside metadata. Skip for simple listings. | +| `exhaustive` | boolean | Return all results, e.g., for "what is my calendar today" or "show me every meeting on this topic". | + +## Date handling + +- **Use `before` / `after` for date constraints.** Older skills used inline filters in the query string — those are unreliable here. +- **Buffer for inclusive dates.** Filtering is exclusive on both ends; pad by one day to include a target date fully. +- **Natural language keywords work** in `before` / `after`: `today`, `yesterday`, `tomorrow`, `now`. Use them when relative is what the user said. + +## Examples + +``` +meeting_lookup(query="quarterly planning", after="2025-10-01", before="2025-10-31") +meeting_lookup(participants=["Alice Chen"], extract_transcript=true) +meeting_lookup(peer="bob@example.com", after="today", before="tomorrow") +meeting_lookup(calendar_ids=["primary"], after="today", before="2025-10-09") +meeting_lookup(query="design review", extract_transcript=true, exhaustive=true) +``` + +## Pitfalls + +- **Don't invent `calendar_ids`.** Only use `"primary"` or IDs that appeared verbatim in a prior `meeting_lookup` result's `attendees` / `organizer_email`. Inventing IDs will return empty. +- **`peer` and `calendar_ids` interact.** `peer` wins when both are set. +- **Transcript extraction has cost.** Don't pass `extract_transcript=true` for simple "list my meetings today" queries. +- **Inline date filters in `query` don't work reliably.** Prefer `before` / `after`. + +## Typical follow-up + +Action items from a transcript usually need follow-on `search` (the doc they reference) or `gmail_search` (the email thread). For multi-source synthesis, see [synthesis.md](synthesis.md). diff --git a/plugins/glean-core/skills/using-glean/reference/memory.md b/plugins/glean-core/skills/using-glean/reference/memory.md new file mode 100644 index 0000000..f5a5f29 --- /dev/null +++ b/plugins/glean-core/skills/using-glean/reference/memory.md @@ -0,0 +1,68 @@ +# `read_memory` + `memory_schema` — the user's long-term work memory + +Glean Memory stores per-user context: writing style, role, active projects, explicit notes the user saved, recent topics. Use it to personalize responses and to recall facts the user established in earlier sessions. + +The two tools are paired: +- **`memory_schema`** — discover what categories exist and what fields each carries (call first if unsure) +- **`read_memory`** — read entries from one or more categories + +## When to use + +- "What am I working on?" / "What are my active projects?" — pull `ActiveProjects` +- Drafting in the user's voice — pull `WritingStyle` +- "What's my role?" / "What do I work on?" — pull `RolesAndResponsibilities` +- The user references something from earlier sessions ("the X project", "what I told you about Y") +- Personalizing any answer where the user's identity / context matters + +**Don't** use for: +- Other people's memory (memory is calling-user only) +- General company knowledge (use `search` / `chat`) +- Real-time activity (use `user_activity`) + +## Schema-then-read pattern + +Memory categories are an enum; field shapes per category are also enumerated. Don't guess. + +``` +1. memory_schema() -> list of categories +2. memory_schema(category="ActiveProjects") -> field schema for that category +3. read_memory(action="read", category="ActiveProjects", query="…") +``` + +For routine reads of well-known categories, you can skip step 2 — but always run step 1 if you're unfamiliar with what's available. + +## Categories (the standard set) + +`WritingStyle`, `RolesAndResponsibilities`, `ActiveProjects`, `ExplicitMemories`, `RecentTopics`, `CommunicationPreferences`, `KnowledgeLevelMap`, `Preferences`, `GoalsAndPriorities`, `IdentityAndNarrative`, `ConstraintsAndGuardrails`, `DecisionHeuristics`, `WorkingStyle`, `DomainContext`, `RelationshipContext`, `CommitmentsAndResponsibilities`, `ContextualState`, `Miscellaneous`, `NativeMemories`. + +If your client has write access (varies by Glean instance and integration), `read_memory` also supports `action: "add" | "update" | "delete"`. Default is `"read"`. + +## Parameters (read action) + +| Parameter | Type | Notes | +|---|---|---| +| `action` | enum | `"read"` for retrieval. | +| `category` | enum | Omit to read across categories. | +| `query` | string | Optional semantic search within the category. | +| `read_filters` | map | Field equality filters (use `memory_schema` to discover filterable fields). | +| `memory_source` | enum | Optional source filter: `GleanAssistant`, `ClaudeCode`, `Cursor`, etc. | +| `limit` | number | Default 10. | + +## Examples + +``` +read_memory(action="read", category="ActiveProjects") +read_memory(action="read", category="WritingStyle", limit=3) +read_memory(action="read", query="auth migration", limit=5) +read_memory(action="read", category="ExplicitMemories", read_filters={"topic":"deployment"}) +``` + +## Pitfalls + +- **Memory can be stale.** A `WorkingStyle` entry from a year ago may no longer reflect the user. Treat as context, not ground truth, for facts that change. +- **Categories vary by Glean instance.** The standard set above is the maximum; some categories may be empty or absent. `memory_schema` tells you what's actually available. +- **Empty results are normal.** A new user's memory is sparse. Don't probe repeatedly — fall back to asking the user. + +## Typical follow-up + +For status reports / weekly summaries, pair `read_memory` (what the user *says* they work on) with `user_activity` ([user-activity.md](user-activity.md), what they actually touched) and surface any drift. diff --git a/plugins/glean-core/skills/using-glean/reference/outlook-search.md b/plugins/glean-core/skills/using-glean/reference/outlook-search.md new file mode 100644 index 0000000..79df8ca --- /dev/null +++ b/plugins/glean-core/skills/using-glean/reference/outlook-search.md @@ -0,0 +1,58 @@ +# `outlook_search` — Outlook / Microsoft 365 email + +Search the user's Outlook mailbox: messages, threads, attachments. The Microsoft 365 counterpart to `gmail_search`. Requires the user's org to be on M365. + +## When to use + +- "Find the email about X" — content/subject search +- "What did Alice send me about the budget?" — sender + topic +- "Find that report I got from finance" — attachment lookup + +**Don't** use for: +- Gmail / Google Workspace email — use `gmail_search` +- Calendar invites as content — use `meeting_lookup` + +## Picking the right tool + +If the user has only one of `gmail_search` / `outlook_search` available in the active tool inventory, use that one. If both are available — rare, usually means the org is mid-migration — ask the user which mailbox they want to search, or default to the one that matches their `me` email. + +## Parameters + +| Parameter | Type | Notes | +|---|---|---| +| `query` | string (required) | Keywords + inline filters. | + +## Inline filters + +The filter vocabulary largely parallels `gmail_search`: + +| Filter | Example | Meaning | +|---|---|---| +| `from:` | `from:"alice@company.com"` or `from:me` | Sender | +| `to:` | `to:"bob@company.com"` or `to:me` | Recipient | +| `subject:` | `subject:"quarterly review"` | Subject line | +| `has:` | `has:attachment` | Attachment presence | +| `after:` / `before:` | `after:2025-01-15` | YYYY-MM-DD | + +Differences from `gmail_search`: +- No `label:` taxonomy — Outlook uses folders. The standard folders (Inbox, Sent, Deleted) are searched by default. +- No Gmail-specific `is:starred` / `is:snoozed`. `is:unread` and `is:read` typically work; verify against the live tool list before relying on others. + +## Examples + +``` +outlook_search(query="quarterly review subject:\"Q4 planning\" after:2025-09-01") +outlook_search(query="from:\"finance@company.com\" has:attachment") +outlook_search(query="from:me to:\"alice@company.com\" budget") +outlook_search(query="contract has:attachment") +``` + +## Pitfalls + +- **Don't assume Gmail filter vocabulary 1:1.** Verify by trying the bare query first if a filter returns unexpected empty results. +- **Quote multi-word values.** +- **Empty results may mean no access** to a shared mailbox. + +## Typical follow-up + +Use `read_document` with the URL of an interesting result to read the full message. diff --git a/plugins/glean-core/skills/using-glean/reference/read-document.md b/plugins/glean-core/skills/using-glean/reference/read-document.md new file mode 100644 index 0000000..5cce12f --- /dev/null +++ b/plugins/glean-core/skills/using-glean/reference/read-document.md @@ -0,0 +1,49 @@ +# `read_document` — fetch full content by URL + +Retrieve the complete content of one or more URLs (internal Glean-indexed resources or public web pages). The natural follow-up to `search`, `code_search`, `gmail_search`, etc., when you have a URL and need the body. + +## When to use + +- After `search` returns a candidate document and you need to quote, summarize, or analyze it +- The user provides a Glean URL or any other URL and asks "what does this say?" +- You need full content rather than the short excerpt search returns +- Reading multiple related documents in one call + +**Don't** use for: +- Discovery without a URL — use `search` (or the appropriate per-source tool) first +- Repeatedly re-reading the same URL — results are deterministic; cache mentally + +## Parameters + +| Parameter | Type | Notes | +|---|---|---| +| `urls` | string array (required) | One or more URLs. Pass them all in a single call rather than one call per URL. | +| `mode` | enum | Omit for default structured/text response. Set to `"raw_bytes"` to retrieve original bytes (recommended for `.xlsx` and other formats where extracted text loses structure). | + +## When to use `raw_bytes` + +For Office 365 spreadsheets (`.xlsx`), the structured-text response collapses formulas, formatting, and grid structure. Try `mode: "raw_bytes"` first to get the native file. If `raw_bytes` fails, retry without `mode` to fall back to text extraction. + +For most documents (Confluence pages, Google Docs, web pages), the default extracted text is what you want. + +## Examples + +``` +read_document(urls=["https://company.glean.com/doc/abc123"]) +read_document(urls=[ + "https://company.glean.com/doc/abc123", + "https://company.glean.com/doc/def456" +]) +read_document(urls=["https://drive.google.com/file/d/.../view"], mode="raw_bytes") +``` + +## Pitfalls + +- **One call, multiple URLs.** Don't issue four `read_document` calls for four URLs — one call with the array is faster and shares the same auth. +- **All-or-nothing.** Empty response means the URL was inaccessible (auth, access, deleted, never existed). Empty doesn't mean "doesn't exist on the platform." +- **No retries with variations.** If the URL fails, trying the same URL with different casing or query params won't help. Re-issue your `search` if needed. +- **Public URLs work.** `read_document` will fetch external pages too — useful when an internal doc references a vendor's docs page. + +## Typical follow-up + +After `read_document`, you have content to quote / summarize / cite. Apply [vetting.md](vetting.md) before presenting freshness-sensitive material. diff --git a/plugins/glean-core/skills/using-glean/reference/search.md b/plugins/glean-core/skills/using-glean/reference/search.md new file mode 100644 index 0000000..519fa37 --- /dev/null +++ b/plugins/glean-core/skills/using-glean/reference/search.md @@ -0,0 +1,62 @@ +# `search` — document discovery + +Search documents across all the user's Glean-indexed sources (Confluence, Google Drive, GitHub, Slack, Jira, Notion, …). This is the workhorse tool for *"find the doc about X"* questions. + +## When to use + +- Documents, wikis, policies, RFCs, specs, design docs, runbooks +- Slack threads, announcements, public messages +- Any "where is the doc about …" question +- Starting point before reading individual documents with `read_document` + +**Don't** use `search` for people (use `employee_search`), code (`code_search`), email (`gmail_search` / `outlook_search`), or meetings (`meeting_lookup`). + +## Parameter shape + +`search` uses **structured parameters** — pass each filter as its own argument, not embedded in the query string. + +| Parameter | Type | Notes | +|---|---|---| +| `query` | string (required) | Keywords to match. Short, discriminative, no boolean operators. | +| `app` | enum | One source app (`confluence`, `gdrive`, `github`, `slack`, `jira`, `notion`, `gong`, `salescloud`, `gmail`, `o365sharepoint`, …). | +| `type` | enum | Document type: `pull`, `spreadsheet`, `slides`, `email`, `direct message`, `folder`. | +| `owner` | string | Document creator. Accepts a name, `me`, or `myteam`. | +| `from` | string | Person who created, updated, or commented on the doc. Same value space as `owner`. | +| `channel` | string | Slack channel name (only meaningful with `app: slack`). | +| `updated` | string | Relative window: `today`, `yesterday`, `past_week`, `past_2_weeks`, `past_month`, or a month name. | +| `after` | string | `YYYY-MM-DD`. Documents updated strictly after this date. No future dates. | +| `before` | string | `YYYY-MM-DD`. Documents updated strictly before this date. | +| `sort_by_recency` | boolean | Newest first instead of by relevance. Use only when the user explicitly asks for the *latest* or *most recent*. | +| `exhaustive` | boolean | Return all matches. Use only when the user asks for "all", "each", or "every". | +| `num_results` | integer | Default is small. Pass up to 500 only when the user wants a comprehensive list. | +| `dynamic_search_result_filters` | string | After a first search, refine using `key:value` filters drawn from the result metadata (e.g., `brand:Apple|screen_size:14-inch`). Never invent values. | +| `cursor` | string | Pagination cursor from a previous response. | + +## Query style + +- **Short, discriminative keywords.** "auth RFC" beats "documentation about how authentication works at our company". +- **No boolean logic.** `AND`/`OR` is ignored; using them adds noise. +- **No quotes** unless the user is asking for a verbatim phrase. +- **Iterate, don't query-stuff.** If results are wrong, run another search with a tighter term — adding synonyms to one query rarely helps. + +## Examples + +``` +search(query="authentication RFC", app="confluence", updated="past_month") +search(query="payment retry policy", owner="me") +search(query="design doc onboarding", from="Sarah Chen", after="2025-09-01") +search(query="incident runbook", app="confluence", sort_by_recency=true) +search(query="quarterly planning", updated="past_2_weeks", exhaustive=true) +``` + +## Pitfalls + +- **`after:` with a future date returns nothing.** The API silently drops the filter. +- **`updated` keywords vs. `after` / `before` dates.** Use `updated` for relative windows; use `after`/`before` for ISO date ranges. Don't combine both unless the dates are inside the relative window. +- **`sort_by_recency=true` overrides relevance.** A high-relevance match from last quarter will rank below a low-relevance match from yesterday. Only enable it when the user actually wants newest-first ordering. +- **Empty results don't always mean "doesn't exist".** With Glean, empty often means *the calling user doesn't have access* to anything matching. Report cleanly rather than retrying with looser filters that might leak a partial answer from a different scope. +- **`num_results` defaults are small.** If the user said "all" or "every", pass `exhaustive=true` and a large `num_results` together. + +## Typical follow-up + +After `search` returns candidates, fetch full content with `read_document` (see [read-document.md](read-document.md)) for the URLs you need to quote or analyze. For multi-source synthesis, see [synthesis.md](synthesis.md). Before presenting, apply [vetting.md](vetting.md). diff --git a/plugins/glean-core/skills/using-glean/reference/synthesis.md b/plugins/glean-core/skills/using-glean/reference/synthesis.md new file mode 100644 index 0000000..b0d3dbe --- /dev/null +++ b/plugins/glean-core/skills/using-glean/reference/synthesis.md @@ -0,0 +1,80 @@ +# Synthesis across Glean tools + +Some questions can't be answered by a single Glean tool. Use this file when the answer requires combining sources — docs + code + meetings, or org structure + activity, or memory + search. + +## When this applies + +- A question spans documents, meetings, people, and code +- Results from one source need context from another to be useful +- "Who actually knows about X?" — the title says one thing, the activity says another +- "What's the status of project Y?" — need official docs *and* recent meeting context *and* code activity +- Sources disagree and you need to reconcile + +## Choose tools by information type + +| What you need | Reach for | +|---|---| +| Authoritative doc (RFC, policy, spec) | `search` | +| Synthesized overview across many sources | `chat` | +| Recent discussion / decisions | `meeting_lookup` | +| Org structure, role, reporting | `employee_search` | +| Code-level truth (what's actually built) | `code_search` | +| User's own context / personalization | `read_memory`, `user_activity` | +| Structured entity / relationship | `knowledge_graph_query` | + +## Patterns + +### "What is X, really?" + +1. `chat` for an overview +2. `search` for the authoritative doc +3. `employee_search` for the owner (so the user can verify) +4. Reconcile: what the AI says + what the doc says + who to ask + +### "Who actually knows about X?" + +Title alone is weak signal. Combine: + +1. `employee_search` — who has the role +2. `code_search` with `owner:` — who has been writing code on it +3. `search` with `owner:` — who has been authoring docs on it +4. Rank by how many signals overlap. People with multiple signals are the real experts; single-signal hits are weaker. + +### "What's the status of project Y?" + +1. `chat` — current-status summary +2. `meeting_lookup` — recent decisions +3. `search` with `app:jira` or `app:notion` — tracking docs +4. Recency-weight: a 2-day-old meeting beats a 6-month-old wiki page. + +### "How do we do X?" + +1. `search` — process docs +2. `code_search` — what the code actually does +3. `meeting_lookup` — recent changes to the process +4. Reconcile: doc + code + recent updates. Flag any drift. + +## Reconciling conflicts + +When two sources disagree: + +- **Surface the conflict, don't hide it.** "The spec says A; the code does B." +- **Recency wins for state, authority wins for policy.** A recent meeting overrides an old wiki on "what we're doing now"; an approved RFC overrides a Slack thread on "what the rule is". +- **When unsure, suggest verification with the owner.** Better to point to a person than to pick wrong. + +## Output discipline + +When presenting synthesized answers: + +1. **Cite each claim with a URL.** No URL → don't include the claim. +2. **Note recency** for time-sensitive claims. +3. **Show your sources as a list**, not just inline. The user verifies by clicking. +4. **Apply [vetting.md](vetting.md) before presenting.** Three good sources beat ten weak ones. + +## When to say "I don't know" + +- Sources are missing or all stale +- Conflicts have no clear resolution and no owner to point to +- The user is making a high-stakes decision and the evidence is thin + +A clean "I don't have enough to answer this confidently — try [person/channel]" is better than a synthesized answer the user will rely on incorrectly. diff --git a/plugins/glean-core/skills/using-glean/reference/user-activity.md b/plugins/glean-core/skills/using-glean/reference/user-activity.md new file mode 100644 index 0000000..8a7e22d --- /dev/null +++ b/plugins/glean-core/skills/using-glean/reference/user-activity.md @@ -0,0 +1,49 @@ +# `user_activity` — the user's own work history + +Retrieve the calling user's activity log over a date range: documents they created or edited, comments they made, items they viewed, mentions they received. The data source for "what did I do?" questions. + +## When to use + +- "What have I been working on?" — weekly / daily summary +- "What did I do last week?" — status updates, standup notes +- "What documents have I touched recently?" — recall after time away +- 1:1 prep, performance-review evidence, project handoff +- The user forgot a doc name but remembers they edited it recently + +**Don't** use for: +- Other people's activity — `user_activity` is calling-user only +- Activity outside Glean's connected sources +- Discovery of unfamiliar documents — use `search` + +## Parameters + +| Parameter | Type | Notes | +|---|---|---| +| `start_date` | string (required) | YYYY-MM-DD. **Inclusive.** | +| `end_date` | string (required) | YYYY-MM-DD. **Exclusive** — must be strictly after `start_date`. | + +## Date conventions + +- For "last week" (assuming today is Monday): `start_date: 2025-09-29`, `end_date: 2025-10-06` (a 7-day window). +- For "yesterday": `start_date: 2025-10-12`, `end_date: 2025-10-13`. +- For "today's activity": `start_date: 2025-10-13`, `end_date: 2025-10-14`. + +The exclusive end date catches users off-guard. To include all of a target day, set `end_date` to the day *after*. + +## Examples + +``` +user_activity(start_date="2025-10-06", end_date="2025-10-13") // last week +user_activity(start_date="2025-10-01", end_date="2025-11-01") // October +``` + +## Pitfalls + +- **`end_date` is exclusive.** Off-by-one is the most common mistake. +- **Activity ≠ contributions.** A document the user briefly viewed shows up alongside one they authored. Filter for significance when summarizing — a status report should highlight creates/edits, not views. +- **No filter by app or type.** The result mixes docs, code, meetings, comments. You filter post-hoc. +- **Time zones.** Dates are interpreted in the user's profile time zone — consistent with how the user thinks about their week. + +## Typical follow-up + +For "what did I work on?" reports, combine `user_activity` (what they touched) with `read_memory` ([memory.md](memory.md), what their stated active projects are) for thematic grouping. For accomplishment summaries, vet results per [vetting.md](vetting.md) — exclude trivial views, surface decisions and shipped work. diff --git a/plugins/glean-core/skills/using-glean/reference/vetting.md b/plugins/glean-core/skills/using-glean/reference/vetting.md new file mode 100644 index 0000000..31f0e52 --- /dev/null +++ b/plugins/glean-core/skills/using-glean/reference/vetting.md @@ -0,0 +1,91 @@ +# Vetting Glean results + +Glean returns lots of results. Most should not reach the user verbatim. Vet for relevance, freshness, authority, and corroboration before presenting. + +## When this applies + +- Any time you're about to surface Glean results to the user +- Especially when the user will *act* on the answer (decisions, code changes, communications) +- When sources disagree +- When results are sparse and there's pressure to fill the gap with weak matches + +## The four tests + +### Relevance + +Does the result actually answer the question, or does it just contain matching keywords? + +- **Include**: directly addresses the query +- **Exclude**: tangential mentions, keyword coincidences, unrelated contexts +- Ask: *"If I sent only this to the user, would they say 'yes that answers it'?"* + +### Freshness + +How recently was the source updated? + +| Window | Treatment | +|---|---| +| < 3 months | Current — present without caveat | +| 3–12 months | Aging — note the date | +| 12+ months | Stale — include only if no alternative, with explicit warning | + +For currency-sensitive topics (active projects, team ownership, deployment process), tighten the window. For timeless content (architectural patterns, design philosophy), relax it. + +### Authority + +Where does the source live? + +| Tier | Examples | +|---|---| +| Official | RFCs, approved specs, signed-off policies, CODEOWNERS | +| Semi-official | Team wikis, project docs, design docs | +| Discussion | Slack threads, meeting notes | +| Personal | Individual drafts, scratch notes | + +Don't present a Slack message as policy. Don't present a draft as approved. When the only result is informal, say so. + +### Corroboration + +Do multiple sources agree? + +- 3+ agree → high confidence +- 2 agree → medium +- 1 source → call it out as single-source +- Sources conflict → see [synthesis.md](synthesis.md) on reconciling + +## Filter before presenting + +Run results through this filter: + +1. Drop tangential keyword matches +2. Drop content older than your freshness threshold (unless no alternative) +3. Drop drafts being passed off as final +4. Drop content from people who left the company (for ownership questions) +5. Drop deprecated / legacy content unless that's what the user asked for + +Three vetted results beat ten unfiltered ones. + +## "Nothing found" is a valid answer + +If vetting eliminates everything, say so cleanly: + +> No high-quality results for [topic]. Search returned [N] candidates; vetting excluded them as [reason: stale / tangential / informal]. +> +> Suggested next steps: +> - Try alternative terms: [suggestions] +> - Ask in [relevant channel] +> - Check with [likely owner] + +Never pad with weak matches to avoid saying "nothing found". + +## Communicating confidence + +When you do present results, signal confidence. Examples: + +- "Per the auth RFC (approved 2025-03, last updated 2025-08): …" +- "From a Slack thread on 2025-09-02 (informal): …" +- "Three sources agree on this: [docs]" +- "Single source — recommend verifying with [owner]" +- "This doc is 14 months old; verify currency before relying on it" + +Specificity is the discipline. "Recently" and "according to docs" tell the user nothing. From 4730c4404accea1918b5481d346f7f15043aefcc Mon Sep 17 00:00:00 2001 From: Steve Calvert Date: Mon, 11 May 2026 17:38:27 -0700 Subject: [PATCH 3/7] refactor(glean-code)!: consolidate two skills into using-glean-code with reference files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the code-exploration and plan-prep skills with a single using-glean-code skill plus a reference/ directory. The new layout: plugins/glean-code/skills/using-glean-code/ ├── SKILL.md └── reference/ ├── exploration.md # cross-repo exploration workflow └── plan-prep.md # research before plan mode Tool-syntax depth for code_search lives canonically in glean-core's using-glean/reference/code-search.md; this plugin links to it by name. BREAKING CHANGE: /glean-code:code-exploration and /glean-code:plan-prep slash paths no longer exist. Use /glean-code:using-glean-code, or ask in natural language and let the skill auto-trigger. The /glean-code:plan-prep command (a separate command, not the skill of the same name) remains and is unchanged. Co-Authored-By: Claude Opus 4.7 (1M context) --- plugins/glean-code/README.md | 53 ++++---- .../skills/code-exploration/SKILL.md | 123 ------------------ plugins/glean-code/skills/plan-prep/SKILL.md | 98 -------------- .../skills/using-glean-code/SKILL.md | 49 +++++++ .../using-glean-code/reference/exploration.md | 64 +++++++++ .../using-glean-code/reference/plan-prep.md | 80 ++++++++++++ 6 files changed, 217 insertions(+), 250 deletions(-) delete mode 100644 plugins/glean-code/skills/code-exploration/SKILL.md delete mode 100644 plugins/glean-code/skills/plan-prep/SKILL.md create mode 100644 plugins/glean-code/skills/using-glean-code/SKILL.md create mode 100644 plugins/glean-code/skills/using-glean-code/reference/exploration.md create mode 100644 plugins/glean-code/skills/using-glean-code/reference/plan-prep.md diff --git a/plugins/glean-code/README.md b/plugins/glean-code/README.md index df829db..fc55824 100644 --- a/plugins/glean-code/README.md +++ b/plugins/glean-code/README.md @@ -1,6 +1,6 @@ # Glean Code -**Cross-repository code exploration - search code across your org, find examples, and discover similar implementations.** +**Cross-repository code exploration — search code across your org, find examples, and discover similar implementations.** Leverage Glean's code search to explore beyond your local repository. @@ -15,24 +15,33 @@ claude plugin install glean-core # if not already installed claude plugin install glean-code ``` -## What's Included +## What's included -### Skills -- **code-exploration** - Guidance for cross-repo code search, triggers on implementation questions -- **plan-prep** - Research enterprise context before entering plan mode, triggers on planning-related phrases +### Skill + +- **`using-glean-code`** — Auto-triggers on cross-repo code questions ("how is X implemented", "where is the code for", "find similar code", "how do other teams handle Y"). The skill teaches the workflow; the canonical `code_search` tool reference lives in `glean-core` (see [`using-glean/reference/code-search.md`](../glean-core/skills/using-glean/reference/code-search.md)). + + Reference files under [`skills/using-glean-code/reference/`](skills/using-glean-code/reference/): + + | File | Covers | + |---|---| + | `exploration.md` | Workflow for exploring an unfamiliar system across repos | + | `plan-prep.md` | Gathering enterprise context before entering plan mode | ### Agents -- **codebase-navigator** - Navigates internal repositories to find implementations and patterns -- **plan-prep-researcher** - Gathers design docs, implementations, stakeholders, and related systems for planning + +- **codebase-navigator** — Navigates internal repositories to find implementations and patterns +- **plan-prep-researcher** — Gathers design docs, implementations, stakeholders, and related systems for planning ### Commands -- `/glean-code:codebase-context ` - Get architectural context from internal repos -- `/glean-code:find-examples ` - Find usage examples across the org -- `/glean-code:code-owners ` - Identify who owns/maintains code areas -- `/glean-code:similar-code ` - Find similar implementations across repos -- `/glean-code:plan-prep ` - Research enterprise context before entering plan mode -## Example Usage +- `/glean-code:codebase-context ` — Get architectural context from internal repos +- `/glean-code:find-examples ` — Find usage examples across the org +- `/glean-code:code-owners ` — Identify who owns/maintains code areas +- `/glean-code:similar-code ` — Find similar implementations across repos +- `/glean-code:plan-prep ` — Research enterprise context before entering plan mode + +## Example usage ```bash # Get context before working on a system @@ -57,7 +66,7 @@ claude plugin install glean-code /glean-code:plan-prep Implement webhooks ``` -## Key Differentiator +## Key differentiator **Local search tools only see your current repo.** Glean Code searches across ALL repositories in your organization. This enables: @@ -66,24 +75,10 @@ claude plugin install glean-code - Finding owners: "Who's actively working on payments?" - Avoiding duplication: "Has someone already built a rate limiter?" -## Works for Monorepos and Multi-Repo +## Works for monorepos and multi-repo Whether your company uses a monorepo or multiple repositories, Glean Code searches across everything that's indexed. -## Planning with Enterprise Context - -The plan-prep command brings enterprise knowledge into your planning process: - -- **Research Before Planning**: Use `/glean-code:plan-prep` to gather design docs, similar implementations, and stakeholder info -- **Better Decisions**: See what's been tried, what patterns are proven, and who needs to be involved -- **Informed Architecture**: Make decisions informed by organizational knowledge and prior art - -Example workflow: -1. Run `/glean-code:plan-prep "Add webhook support to payments service"` -2. Review the enterprise context: design decisions, similar implementations, stakeholders -3. Enter plan mode with this fresh knowledge -4. Design your approach informed by organizational patterns and constraints - ## Support - Documentation: https://docs.glean.com/mcp diff --git a/plugins/glean-code/skills/code-exploration/SKILL.md b/plugins/glean-code/skills/code-exploration/SKILL.md deleted file mode 100644 index 80e5876..0000000 --- a/plugins/glean-code/skills/code-exploration/SKILL.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -name: code-exploration -description: Use when the user asks about internal code, implementations, patterns across repositories, or needs to understand how something is built. Triggers on "how is X implemented", "where is the code for", "find the implementation of", "what repos contain", "who wrote the code for", or code architecture questions about internal systems. ---- - -# Cross-Repository Code Exploration via Glean - -When users need to understand code across internal repositories—beyond the local codebase—use Glean's code search to explore the entire organization's code. - -## Tool Naming - -See the `glean-tools-guide` skill for Glean MCP tool naming conventions. Tools follow the pattern `mcp__glean_[server-name]__[tool]` where the server name is dynamic. - -## When This Applies - -Use Glean code search when users ask about: -- How something is implemented (in other repos) -- Where the code for a system/service lives -- Who has been working on a codebase -- Similar implementations across the org -- Examples of how to use an internal API/library -- Code patterns used by other teams - -## BE SKEPTICAL - -Not every code result is worth presenting. - -**Quality Test** -- Is this good code to reference? -- ✅ GOOD: Clean, tested, actively maintained -- ⚠️ ACCEPTABLE: Works but has caveats -- ❌ POOR: Hacky, deprecated, abandoned - -**Recency Test** -- Is this code maintained? -- ✅ ACTIVE: Commits in past 3 months -- ⚠️ SLOWING: 3-12 months since last commit -- ❌ STALE: 12+ months - likely outdated patterns - -**Relevance Test** -- Does this actually answer the question? -- ✅ RELEVANT: Directly addresses what was asked -- ⚠️ RELATED: Similar but different context -- ❌ TANGENTIAL: Keyword match only - -**Filter Out**: -- Code in `/deprecated/`, `/old/`, `/legacy/` paths -- Abandoned repositories -- Prototype/experimental code -- Code with extensive TODO/FIXME comments - -**Quality over quantity**: 3 good examples beat 10 mediocre ones. - -## Key Differentiator - -**Local tools (grep, glob) search only the current repo.** Glean searches across ALL repositories in the organization. This is powerful for: -- Finding examples: "How do other teams handle authentication?" -- Understanding systems: "What repos touch the billing service?" -- Finding owners: "Who's been active in the payments codebase?" - -## Tool Selection - -| User Intent | Glean Tool | -|-------------|------------| -| Find code by content, pattern, or file | `code_search` | -| Find related design docs or specs | `search` | -| Identify code owners/contributors | `code_search` + `employee_search` | -| Read full file content | `read_document` | - -## Query Patterns - -Glean's code search understands natural language. Use filters for precision: - -``` -# Search by content -code_search "authentication middleware" -code_search "rate limiting implementation" - -# Search by contributor -code_search "owner:\"John Smith\" billing service" -code_search "from:me updated:past_week" - -# Search by time -code_search "after:2024-01-01 payments API" - -# Search by file pattern -code_search "*.proto user service" -``` - -## Workflow: Exploring a System - -1. **Find the code**: `code_search "[system name]"` -2. **Vet results**: Filter for quality and recency -3. **Find the docs**: `search "[system name] design doc OR architecture"` -4. **Find the people**: `code_search "owner:* [system] updated:past_month"` -5. **Read details**: `read_document` with URLs from vetted results - -## If No Good Code Found - -Don't pad with weak results: - -```markdown -No high-quality code examples found for [topic]. - -**What was searched:** -- [Queries attempted] - -**What was filtered:** -- [X] matches - [reasons: outdated/poor quality] - -**Suggestions:** -- Check external libraries -- Ask in [relevant channel] -- This may need to be built from scratch -``` - -## Relationship to Commands - -For structured workflows, suggest the relevant slash command: -- `/glean-code:codebase-context [system]` - Get comprehensive context -- `/glean-code:find-examples [API/pattern]` - Find usage examples -- `/glean-code:code-owners [component]` - Identify maintainers -- `/glean-code:similar-code [pattern]` - Find similar implementations diff --git a/plugins/glean-code/skills/plan-prep/SKILL.md b/plugins/glean-code/skills/plan-prep/SKILL.md deleted file mode 100644 index e63e6ae..0000000 --- a/plugins/glean-code/skills/plan-prep/SKILL.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -name: plan-prep -description: Use when the user wants to prepare for plan mode by gathering enterprise context. Triggers on "plan with glean", "prep for plan", "research before planning", "plan prep", or when starting strategic/architectural planning work. ---- - -# Planning Preparation via Glean - -When users need to enter plan mode but want enterprise context first, use Glean to research design docs, similar implementations, stakeholders, and related systems. - -## When This Applies - -Use plan prep when users: -- Want to research before entering plan mode -- Are planning architectural or strategic changes -- Need to understand related systems before designing -- Want to identify stakeholders and code owners early -- Phrase it as: "plan with glean", "prep for plan", "research before planning", "plan prep" - -## BE SKEPTICAL - -Filter aggressively for relevant, current information. - -**Freshness Test** -- ✅ CURRENT: Updated in past 6 months -- ⚠️ AGING: 6-12 months old -- ❌ STALE: 12+ months old - -**Relevance Test** -- ✅ RELEVANT: Directly applies to the planned work -- ⚠️ RELATED: Similar context but different use case -- ❌ TANGENTIAL: Keyword match only - -**Authority Test** -- ✅ OFFICIAL: Approved RFCs, design docs, official docs -- ⚠️ INFORMAL: Team wiki, notes -- ❌ OUTDATED: Rejected proposals, abandoned work - -**Quality over quantity**: 3-4 high-quality findings beat 10 weak ones. - -## Key Differentiator - -**Local tools only see your current repo.** The plan-prep workflow searches your entire organization for: -- Design docs and architectural decisions -- Similar implementations and code patterns -- Code owners and stakeholders -- Related systems and dependencies - -This gives you enterprise context for better planning decisions. - -## Tool Selection - -| Research Need | Glean Tool | -|---------------|-----------| -| Find design docs, RFCs, architecture | `search` | -| Find similar code implementations | `code_search` | -| Find code owners and stakeholders | `code_search` + `employee_search` | -| Find related/dependent systems | `code_search` | -| Read full document content | `read_document` | - -## Workflow: Plan Preparation - -1. **Design & Architecture Research**: `search "[task] architecture OR design doc OR RFC"` -2. **Code Patterns & Implementations**: `code_search "[related components]"` for similar solutions -3. **Stakeholders & Owners**: `code_search "[relevant systems] updated:past_month"` + `employee_search` -4. **Related Systems**: `code_search` for upstream/downstream components -5. **Synthesize Findings**: Organize by category, vet for relevance -6. **Present Summary**: Clear sources and citations for verification - -## Output Format - -The plan-prep command returns structured research organized as: - -- **Design & Architecture**: RFCs, design decisions, architectural patterns -- **Implementations & Patterns**: Code examples, similar solutions, proven approaches -- **Stakeholders & Ownership**: Key people, teams, code owners -- **Related Systems**: Upstream/downstream dependencies and integrations -- **Key Insights**: Synthesized findings and critical context - -All with clear source citations so you can verify and dig deeper. - -## Next Steps - -After reviewing the research: -- User can enter plan mode with fresh enterprise context -- Plan generation is informed by organizational knowledge -- Better architectural decisions from cross-repo visibility -- All sources cited for verification - -## Relationship to Commands - -Use `/glean-code:plan-prep ` to start the planning preparation workflow. - -## Related Commands - -- `/glean-code:codebase-context [system]` - Get architectural context about a specific system -- `/glean-code:code-owners [component]` - Identify code owners and maintainers -- `/glean-code:similar-code [pattern]` - Find similar implementations across repos -- `/glean-code:find-examples [API/pattern]` - Find usage examples diff --git a/plugins/glean-code/skills/using-glean-code/SKILL.md b/plugins/glean-code/skills/using-glean-code/SKILL.md new file mode 100644 index 0000000..f2e3e1f --- /dev/null +++ b/plugins/glean-code/skills/using-glean-code/SKILL.md @@ -0,0 +1,49 @@ +--- +name: using-glean-code +description: Search and analyze internal source code across the user's organization's repositories. Use when the user asks how something is implemented, where the code for a system lives, who has been working on a codebase, or wants to find similar patterns across teams — i.e., questions that need visibility beyond the local working directory. +when_to_use: | + Trigger phrases include "how is X implemented", "where is the code for", "find the implementation of", "what repos contain", "who wrote the code for", "how do other teams handle", "find similar code to", "examples of using", "prior art for". + + Don't use this skill for code in the current working directory — prefer local Grep / Glob. Don't use it for design docs (use the `using-glean` skill's `search` reference) or for finding people without code context (use the `using-glean` skill's `employee-search` reference). +--- + +# Using Glean for Code Exploration + +Glean indexes source code across the user's organization's connected repositories. Local tools (`Grep`, `Glob`, `Read`) see only the current repo; this skill is for everything else. + +## When to reach for this + +- **Finding the system** — "Where does our payments code live?" +- **Finding the patterns** — "How do other teams handle rate limiting?" +- **Finding the people** — combining code authorship with `employee_search` reveals real owners (not just titled ones) +- **Prior art before designing** — see [reference/plan-prep.md](reference/plan-prep.md) for the research-before-plan workflow + +## The tool you'll mostly use + +This skill drives the `code_search` MCP tool. For full param shape, inline filter syntax, and pitfalls (quoting names, the `app:` filter not applying, recency caveats), read [`using-glean/reference/code-search.md`](../../../../glean-core/skills/using-glean/reference/code-search.md) in the `glean-core` plugin. That's the canonical reference; this skill carries the *workflow* on top. + +For this skill's own workflow patterns, see: + +- [reference/exploration.md](reference/exploration.md) — exploring an unfamiliar system across repos: what to search for, what to filter, what to present +- [reference/plan-prep.md](reference/plan-prep.md) — gathering enterprise context before entering plan mode for architectural / strategic work + +## Vetting + +Not every match is worth surfacing. Code in `legacy/`, `deprecated/`, `archive/`, abandoned repos, or files with extensive `TODO/FIXME` comments will mislead the user. Apply the criteria in [`using-glean/reference/vetting.md`](../../../../glean-core/skills/using-glean/reference/vetting.md) and prefer 3 high-quality matches over 10 unfiltered ones. + +## Output expectations + +When presenting code findings: + +1. **Cite each file with its full URL** so the user can open it directly +2. **Note last-update date** when a result depends on currency (active patterns vs. archaeological digs) +3. **Group by repo** when results span many repos — it shows the user the shape of the answer +4. **Flag drift** when implementations disagree across teams — don't pretend consensus exists if it doesn't + +## Related commands + +- `/glean-code:codebase-context ` — structured architecture rundown for an unfamiliar system +- `/glean-code:similar-code ` — find similar implementations +- `/glean-code:find-examples ` — usage examples +- `/glean-code:code-owners ` — maintainers and contributors +- `/glean-code:plan-prep ` — the workflow described in [reference/plan-prep.md](reference/plan-prep.md) diff --git a/plugins/glean-code/skills/using-glean-code/reference/exploration.md b/plugins/glean-code/skills/using-glean-code/reference/exploration.md new file mode 100644 index 0000000..16d823b --- /dev/null +++ b/plugins/glean-code/skills/using-glean-code/reference/exploration.md @@ -0,0 +1,64 @@ +# Cross-repo code exploration workflow + +When the user wants to understand a system, pattern, or piece of code that may live anywhere across the org's repositories. + +## When this applies + +- Locating an unfamiliar system: "Where does the billing reconciliation code live?" +- Mapping breadth: "What repos touch the auth flow?" +- Finding examples: "How do other teams handle WebSocket reconnection?" +- Identifying people through their code activity: "Who's been active in payments lately?" + +## Workflow + +1. **Find the code.** Start with `code_search` on the most discriminative keyword. Iterate — if results are too broad, narrow with an `extension`, an `owner:` filter, or a date filter. If results are empty, broaden by removing terms (Glean's keyword matching is strict). + +2. **Vet the matches.** Filter out: + - Files in `legacy/`, `deprecated/`, `archive/`, `old/` paths + - Repos with no commits in 12+ months (likely abandoned) + - Files dense with `TODO` / `FIXME` / `HACK` comments + - Generated code (e.g., `*.pb.go`, `*_pb2.py`) unless that's what was asked for + +3. **Find related docs.** Search for design docs / RFCs / ADRs about the same system using the `using-glean` skill's `search` reference. Code shows what's built; docs explain why. + +4. **Find the people.** For real owners (not titled ones), combine `code_search` with `owner:` filters and `updated:past_month`. People with multiple recent commits are the active maintainers. + +5. **Read full content** of the top 3-5 files with `read_document` for quoting / analyzing. + +6. **Synthesize.** When the answer requires combining code + docs + meetings, follow [`using-glean/reference/synthesis.md`](../../../../glean-core/skills/using-glean/reference/synthesis.md). + +## Output shape + +```markdown +## [System / pattern] + +### Where it lives +- [`repo/path/file.ext`](url) — [one-line role of this file] +- ... + +### Active maintainers +- [Name] — N recent commits, including [most-relevant ones] + +### Related docs +- [Doc title](url) — [date] + +### Notes +- [Anything surprising: drift between repos, deprecation in progress, recent migration, etc.] +``` + +## When nothing useful turns up + +Don't pad with weak matches. Better: + +```markdown +No current implementations found across indexed repos. + +What I searched: [queries] +What I filtered out: [N matches removed because deprecated / abandoned / tangential] + +Suggestions: +- Try alternative terms: [...] +- Check external libraries +- Ask in [relevant channel] +- This may need to be built from scratch +``` diff --git a/plugins/glean-code/skills/using-glean-code/reference/plan-prep.md b/plugins/glean-code/skills/using-glean-code/reference/plan-prep.md new file mode 100644 index 0000000..fff62bc --- /dev/null +++ b/plugins/glean-code/skills/using-glean-code/reference/plan-prep.md @@ -0,0 +1,80 @@ +# Plan-prep: enterprise context before plan mode + +When the user is about to enter plan mode for architectural or strategic work, gather org-wide context first so the plan is informed by what already exists rather than reasoning in isolation. + +## When this applies + +- The user says "plan with glean", "prep for plan", "research before planning", "plan prep" +- The user is starting an architectural change, not a localized fix +- The work touches systems beyond the current repo and existing patterns or owners are relevant +- Better designs would come from seeing prior art across teams + +**Don't** use this for: +- Localized bug fixes (just enter plan mode directly) +- Greenfield work in unfamiliar territory (do `using-glean-code` exploration first, *then* plan-prep) + +## Workflow + +1. **Design & architecture research.** Search for RFCs, design docs, ADRs covering the same area: + ``` + search(query="[task] architecture OR design doc OR RFC", app="confluence") + search(query="[task] ADR", app="github") + ``` + Note proposals that were *rejected* — they record constraints worth respecting. + +2. **Code patterns & implementations.** Use `code_search` for similar solutions across the org: + ``` + code_search(query="[similar component or pattern]") + code_search(query="[interface or library being affected]") + ``` + Filter for active code (not legacy paths) per [reference/exploration.md](exploration.md). + +3. **Stakeholders & owners.** Identify who needs to know: + ``` + code_search(query="[relevant systems] updated:past_month") + employee_search(query="[relevant team or role]") + ``` + Cross-reference recent code activity with org structure to find real owners (not just titled ones). + +4. **Related systems.** Search for upstream / downstream dependencies: + ``` + code_search(query="[component] import OR dependency") + ``` + +5. **Synthesize.** Group findings by category (architecture, implementations, stakeholders, related systems). Cite every claim. Apply vetting per [`using-glean/reference/vetting.md`](../../../../glean-core/skills/using-glean/reference/vetting.md). + +## Output shape + +```markdown +## Plan-prep: [task] + +### Design & architecture +- [Doc title](url) — [date] — [one-line takeaway] +- ... + +### Implementations & patterns +- [`repo/path`](url) — [what it does, why relevant] +- ... + +### Stakeholders & owners +- [Name] — [role / signal: code activity, doc authorship, etc.] +- ... + +### Related systems +- [System] — [how it depends on or is depended on by this work] +- ... + +### Key insights +- [Synthesized observation, e.g., "Two teams independently implemented X; converging would simplify Y"] +- ... +``` + +## Hand-off to plan mode + +When the research is in place, the user enters plan mode with: +- Concrete sources to cite in the plan rationale +- Owners to consult before / after +- Prior art to reuse or supersede +- Awareness of related systems that may be affected + +Plan-mode design quality improves materially when it's informed by what already exists in the org. From da63b959e951d047cfde9daa2fb258608d0ebe9c Mon Sep 17 00:00:00 2001 From: Steve Calvert Date: Mon, 11 May 2026 17:38:39 -0700 Subject: [PATCH 4/7] refactor(glean-productivity)!: consolidate two skills into using-glean-productivity with reference files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the activity-synthesis and priority-signals skills with a single using-glean-productivity skill plus a reference/ directory. The new layout: plugins/glean-productivity/skills/using-glean-productivity/ ├── SKILL.md └── reference/ ├── activity.md # retrospective: what the user did └── priorities.md # prospective: what needs attention Tool-syntax depth for user_activity, read_memory, search, and meeting_lookup lives canonically in glean-core's using-glean reference; this plugin links to it by name. Also normalize a `mcp__glean` runtime-name reference in commands/daily-briefing.md to the bare `Glean MCP` phrasing for consistency with the new skills. BREAKING CHANGE: /glean-productivity:activity-synthesis and /glean-productivity:priority-signals slash paths no longer exist. Use /glean-productivity:using-glean-productivity, or ask in natural language and let the skill auto-trigger. Co-Authored-By: Claude Opus 4.7 (1M context) --- plugins/glean-productivity/README.md | 95 ++++++------ .../commands/daily-briefing.md | 2 +- .../skills/activity-synthesis/SKILL.md | 113 -------------- .../skills/priority-signals/SKILL.md | 140 ------------------ .../skills/using-glean-productivity/SKILL.md | 45 ++++++ .../reference/activity.md | 73 +++++++++ .../reference/priorities.md | 77 ++++++++++ 7 files changed, 238 insertions(+), 307 deletions(-) delete mode 100644 plugins/glean-productivity/skills/activity-synthesis/SKILL.md delete mode 100644 plugins/glean-productivity/skills/priority-signals/SKILL.md create mode 100644 plugins/glean-productivity/skills/using-glean-productivity/SKILL.md create mode 100644 plugins/glean-productivity/skills/using-glean-productivity/reference/activity.md create mode 100644 plugins/glean-productivity/skills/using-glean-productivity/reference/priorities.md diff --git a/plugins/glean-productivity/README.md b/plugins/glean-productivity/README.md index 3ea61dc..a24632b 100644 --- a/plugins/glean-productivity/README.md +++ b/plugins/glean-productivity/README.md @@ -1,6 +1,6 @@ -# glean-productivity +# Glean Productivity -Personal productivity tools powered by Glean - daily briefings, weekly summaries, and activity analysis. +Personal productivity tools powered by Glean — daily briefings, weekly summaries, activity synthesis, and priority triage. ## Overview @@ -14,20 +14,39 @@ claude plugins add gleanwork/claude-plugins/glean-productivity **Requires**: `glean-core` plugin for Glean MCP configuration. -## Commands +## What's included + +### Skill + +- **`using-glean-productivity`** — Auto-triggers on personal-productivity questions ("what have I been working on", "what's urgent", "summarize my week"). The canonical Glean tool references (`user_activity`, `read_memory`, `search`, `meeting_lookup`) live in `glean-core`; this skill carries the workflow. + + Reference files under [`skills/using-glean-productivity/reference/`](skills/using-glean-productivity/reference/): + + | File | Covers | + |---|---| + | `activity.md` | Retrospective questions: what the user did, accomplishments, status updates | + | `priorities.md` | Prospective questions: urgent items, blockers, attention triage | + +### Commands | Command | Description | -|---------|-------------| -| `/daily-briefing` | What happened in the last 24 hours - mentions, shared docs, decisions, action items | -| `/my-week` | Weekly summary of your activity, accomplishments, and collaborations | +|---|---| +| `/glean-productivity:daily-briefing` | What happened in the last 24 hours — mentions, shared docs, decisions, action items | +| `/glean-productivity:my-week` | Weekly summary of your activity, accomplishments, and collaborations | -### Example: Daily Briefing +### Agents + +| Agent | Purpose | +|---|---| +| `activity-analyzer` | Analyzes activity data to categorize by priority, identify patterns, and extract accomplishments | + +## Example: Daily Briefing ``` -/daily-briefing +/glean-productivity:daily-briefing # Or with a focus area: -/daily-briefing payments team +/glean-productivity:daily-briefing payments team ``` **Output includes:** @@ -38,13 +57,13 @@ claude plugins add gleanwork/claude-plugins/glean-productivity - Documents shared with you - Today's meetings with prep suggestions -### Example: Weekly Summary +## Example: Weekly Summary ``` -/my-week +/glean-productivity:my-week # Or with a specific time period: -/my-week past 2 weeks +/glean-productivity:my-week past 2 weeks ``` **Output includes:** @@ -56,58 +75,28 @@ claude plugins add gleanwork/claude-plugins/glean-productivity - Open items to carry forward - Reflection prompts for 1:1s -## Skills - -These skills trigger automatically when relevant: - -| Skill | Triggers On | -|-------|-------------| -| `activity-synthesis` | "What have I been working on?", "my recent activity", "what did I do last week" | -| `priority-signals` | "What's urgent?", "what needs my attention?", "what should I focus on?" | - -## Agents - -| Agent | Purpose | -|-------|---------| -| `activity-analyzer` | Analyzes activity data to categorize by priority, identify patterns, and extract accomplishments | - -## Glean Tools Used - -- `user_activity` - Your work activity feed -- `meeting_lookup` - Meetings and transcripts -- `search` - Documents and mentions -- `chat` - AI synthesis across sources -- `memory` - Your roles, projects, preferences - -## Use Cases - -### Morning Routine -Start your day with `/daily-briefing` to know exactly what needs your attention. - -### Status Updates -Use `/my-week` to quickly generate content for standups or status reports. - -### 1:1 Prep -The "Reflection Prompts" section in `/my-week` provides ready-made discussion points. +## Use cases -### After PTO -Combine with `/glean-meetings:catch-up` for comprehensive catch-up after time away. +- **Morning routine**: `/glean-productivity:daily-briefing` to know what needs attention +- **Status updates**: `/glean-productivity:my-week` for standups and status reports +- **1:1 prep**: the reflection prompts in `/my-week` are ready-made discussion points +- **After PTO**: combine with `/glean-meetings:catch-up` for comprehensive catch-up ## Troubleshooting -### Glean MCP Not Connected +### Glean MCP not connected If commands fail with missing tool errors: - Run `/glean-core:status` to check connection - Run `/glean-core:mcp-setup` to configure -### Limited Activity Data +### Limited activity data If activity data is sparse: - You may work primarily in systems not indexed by Glean - Commands will supplement with meeting and document data - Consider which data sources are connected to your Glean instance -## Related Plugins +## Related plugins -- `glean-core` - Required foundation -- `glean-meetings` - Meeting prep and catch-up -- `glean-people` - Find experts and stakeholders +- `glean-core` — required foundation +- `glean-meetings` — meeting prep and catch-up +- `glean-people` — find experts and stakeholders diff --git a/plugins/glean-productivity/commands/daily-briefing.md b/plugins/glean-productivity/commands/daily-briefing.md index ff4afa2..293efba 100644 --- a/plugins/glean-productivity/commands/daily-briefing.md +++ b/plugins/glean-productivity/commands/daily-briefing.md @@ -183,7 +183,7 @@ If you have time, these updates might be of interest: ## Troubleshooting ### Glean MCP Not Connected -If you see errors about missing `mcp__glean` tools: +If you see errors about missing Glean MCP tools: - Run `/glean-core:status` to check connection - Run `/glean-core:mcp-setup` to configure diff --git a/plugins/glean-productivity/skills/activity-synthesis/SKILL.md b/plugins/glean-productivity/skills/activity-synthesis/SKILL.md deleted file mode 100644 index c6250ec..0000000 --- a/plugins/glean-productivity/skills/activity-synthesis/SKILL.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -name: activity-synthesis -description: Use when the user asks about their recent work, what they've been doing, their contributions, or needs to recall past activity. Triggers on phrases like "what have I been working on", "what did I do last week", "my recent activity", "what have I accomplished", "summarize my work", "what projects am I on", or when the user needs to recall or reflect on their own work. ---- - -# Activity Synthesis - -When users ask about their own work activity, use Glean's user_activity and memory tools to provide a synthesized view of their contributions. - -## Tool Naming - -See the `glean-tools-guide` skill for Glean MCP tool naming conventions. Tools follow the pattern `mcp__glean_[server-name]__[tool]` where the server name is dynamic. - -## When This Applies - -Use this approach when users ask: -- "What have I been working on?" -- "What did I do last week?" -- "Summarize my recent activity" -- "What projects have I touched?" -- "Help me remember what I worked on" -- "What should I put in my status update?" - -## BE SKEPTICAL - -Not every activity is worth highlighting. Before including items, evaluate: - -**Significance Test** -- Is this a meaningful contribution? -- ✅ INCLUDE: Created docs, made decisions, completed tasks -- ⚠️ MAYBE: Reviewed items, attended meetings -- ❌ EXCLUDE: Just viewed something, minor edits, noise - -**Accomplishment Test** -- Did the user actually accomplish something? -- ✅ INCLUDE: Finished tasks, shipped features, resolved issues -- ⚠️ CONTEXT: In-progress work (note the status) -- ❌ EXCLUDE: Started but abandoned, just browsing - -**Relevance Test** -- Does this reflect real work the user did? -- ✅ INCLUDE: Direct contributions with clear ownership -- ❌ EXCLUDE: Auto-generated, mass-distributed, tangential CC's - -**Filter Out**: -- Automated notifications -- Documents the user only viewed briefly -- Mass emails or announcements received -- Activity with no meaningful outcome - -**Quality over quantity**: A focused summary of 5-7 accomplishments is better than 20 trivial activities. - -## Primary Tools - -| Tool | Purpose | When to Use | -|------|---------|-------------| -| `user_activity` | Get work activity feed | Primary source for user's actions | -| `memory` | Get context about user | Roles, projects, responsibilities | -| `search` | Find documents by user | Documents created/updated | -| `meeting_lookup` | Find meetings | Meetings attended | - -## Query Patterns - -### Get Activity Feed -``` -user_activity start_date:[YYYY-MM-DD] end_date:[YYYY-MM-DD] -``` -Note: end_date is exclusive. - -### Get User Context -``` -memory - read all categories -``` -Returns roles, responsibilities, active projects, recent topics. - -### Find User's Documents -``` -search query="*" from="me" updated="past_week" -search query="*" owner="me" -``` - -## Synthesis Approach - -1. **Gather raw data** from user_activity and search -2. **Group by theme**: Projects, meetings, documents, collaborations -3. **Identify patterns**: What topics appear repeatedly? -4. **Highlight accomplishments**: Completed items, decisions made -5. **Note open items**: Things still in progress - -## Output Format - -Present activity in a scannable format: - -```markdown -## Your Recent Activity: [Time Period] - -### By Project -- **[Project A]**: [X activities] - [summary] -- **[Project B]**: [Y activities] - [summary] - -### Key Actions -- [Action 1] - [date] -- [Action 2] - [date] - -### Collaborations -- Worked with [Person] on [topic] -``` - -## Relationship to Commands - -For comprehensive activity summaries, suggest: -- `/glean-productivity:my-week` - Full weekly summary with analysis -- `/glean-productivity:daily-briefing` - What happened in last 24 hours diff --git a/plugins/glean-productivity/skills/priority-signals/SKILL.md b/plugins/glean-productivity/skills/priority-signals/SKILL.md deleted file mode 100644 index 4e0c22f..0000000 --- a/plugins/glean-productivity/skills/priority-signals/SKILL.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -name: priority-signals -description: Use when the user asks about urgent items, what needs attention, priorities, or blockers. Triggers on phrases like "what's urgent", "what needs my attention", "what's blocking", "what should I focus on", "priorities", "critical items", "what's on fire", "what can't wait", or when helping the user triage their workload. ---- - -# Priority Signals - -When users ask about urgent or priority items, use Glean to identify what needs immediate attention based on activity signals. - -## Tool Naming - -See the `glean-tools-guide` skill for Glean MCP tool naming conventions. - -## When This Applies - -Use this approach when users ask: -- "What's urgent?" -- "What needs my attention?" -- "What should I focus on first?" -- "Are there any blockers waiting on me?" -- "What's critical right now?" -- "Help me prioritize" - -## BE SKEPTICAL - -Not every item found is truly urgent. Before including results, evaluate: - -**Urgency Validity Test** -- Is this genuinely urgent, or just recent/noisy? -- ✅ URGENT: Explicit deadline, blocking others, explicitly marked urgent -- ⚠️ IMPORTANT: Should address but not time-critical -- ❌ NOISE: Just new, not actually urgent - -**Relevance Test** -- Is this the user's responsibility? -- ✅ INCLUDE: Directly assigned, explicitly mentioned -- ❌ EXCLUDE: Just CC'd, tangentially related - -**Filter Out**: -- Mass announcements -- CC'd threads where they're not primary audience -- "Urgent" labels on non-urgent items (urgency inflation) -- Old items that were urgent but are now resolved - -**Quality over noise**: Better to report "nothing urgent" than overwhelm with false positives. - -## Priority Signal Sources - -| Signal Type | Glean Tool | What to Look For | -|-------------|------------|------------------| -| Direct mentions | `search` | People tagging/mentioning the user | -| Action items | `meeting_lookup` | Items assigned in meetings | -| Waiting on you | `search` | Questions awaiting response | -| Urgent keywords | `search` | "urgent", "ASAP", "blocking" | -| Recent activity | `user_activity` | Items you've engaged with | - -## Query Patterns - -### Find Urgent Mentions -``` -search query="urgent OR ASAP OR blocking [user name]" updated="past_week" sort_by_recency=true -``` - -### Find Assignments from Meetings -``` -chat "What action items were assigned to [user] in meetings over the past week?" -``` - -### Find Waiting Questions -``` -search query="[user name] question OR asking" updated="past_week" -``` - -## Priority Tiers - -When presenting results, categorize by urgency (ONLY after vetting): - -**Tier 1: Immediate (Today)** -- Explicit deadlines today -- Items marked urgent/ASAP with evidence it's genuine -- Blockers on others - -**Tier 2: Soon (This Week)** -- Action items from recent meetings -- Questions awaiting response -- Review requests - -**Tier 3: Awareness** -- Decisions affecting your area -- Updates to watch -- FYI items - -## Output Format - -```markdown -## Priority Triage - -### Vetting Summary -| Found | Genuinely Urgent | Filtered Out | -|-------|------------------|--------------| -| [X] | [Y] | [Z - not actually urgent] | - -### Immediate Attention -| Item | Source | Why Urgent | -|------|--------|------------| -| [Item] | [Source] | [Specific reason - deadline/blocker] | - -### This Week -| Item | Source | Deadline | -|------|--------|----------| -| [Item] | [Source] | [Date if known] | - -### Filtered (Not Actually Urgent) -- [Item] - [Why filtered: CC'd only / already resolved / etc.] -``` - -## If Nothing Is Urgent - -This is a valid and valuable answer: - -```markdown -## Priority Triage - -### No Urgent Items Found - -Searched [X] sources and found no items requiring immediate attention. - -**What was checked:** -- Direct mentions: None requiring action -- Meeting action items: All current -- Blocking requests: None found - -**Suggestion**: This might be a good time for [deep work / planning / etc.] -``` - -## Relationship to Commands - -For comprehensive briefings, suggest: -- `/glean-productivity:daily-briefing` - Full morning briefing with prioritized items -- `/glean-meetings:catch-up` - Catch up after time away diff --git a/plugins/glean-productivity/skills/using-glean-productivity/SKILL.md b/plugins/glean-productivity/skills/using-glean-productivity/SKILL.md new file mode 100644 index 0000000..806d8e9 --- /dev/null +++ b/plugins/glean-productivity/skills/using-glean-productivity/SKILL.md @@ -0,0 +1,45 @@ +--- +name: using-glean-productivity +description: Synthesize the user's own work activity, priorities, and recent context using Glean. Use when the user asks about their recent work, what they accomplished, what's urgent, what needs their attention, or wants help with status updates, 1:1 prep, or weekly summaries. +when_to_use: | + Trigger phrases include "what have I been working on", "what did I do last week", "what should I focus on", "what's urgent", "what needs my attention", "summarize my week", "help me with my status update", "1:1 prep", "what's blocking me", "what can't wait", "morning briefing", "what happened while I was out". + + Don't use this skill for general enterprise queries (use `using-glean`), for someone else's activity (you can't query that directly), or for project-status questions where the user isn't the subject (use `glean-project`). +--- + +# Using Glean for Personal Productivity + +This skill drives queries about the user's own work life — their recent activity, what they accomplished, what's pending, what's urgent. It pulls from `user_activity`, `meeting_lookup`, `search` (with `from:me` / `owner:me`), and `read_memory` to assemble a personal view rather than an enterprise-wide one. + +## Two shapes of question + +Most personal-productivity asks fall into two shapes: + +- **Activity / accomplishments** — "what did I work on?", "summarize my week", "what shipped?". See [reference/activity.md](reference/activity.md). +- **Priorities / blockers** — "what's urgent?", "what needs my attention?", "what's waiting on me?". See [reference/priorities.md](reference/priorities.md). + +The two overlap (a recent activity feed is the substrate for triaging priorities), but the *output* the user wants is different: activity is retrospective, priorities are prospective. + +## Tool reference lives in glean-core + +`user_activity`, `read_memory`, `search`, and `meeting_lookup` are documented canonically in the `using-glean` skill (in the `glean-core` plugin): + +- [`reference/user-activity.md`](../../../../glean-core/skills/using-glean/reference/user-activity.md) — date-range mechanics, the inclusive/exclusive end-date pitfall +- [`reference/memory.md`](../../../../glean-core/skills/using-glean/reference/memory.md) — `read_memory` + `memory_schema` for personalization +- [`reference/search.md`](../../../../glean-core/skills/using-glean/reference/search.md) — for documents the user authored or was mentioned in +- [`reference/meeting-lookup.md`](../../../../glean-core/skills/using-glean/reference/meeting-lookup.md) — for meetings the user attended + +This skill carries the *workflow* on top. + +## Cross-cutting rules + +1. **Quality over volume.** A status update of 5 real accomplishments beats a list of 20 trivial activities. Filter aggressively per [reference/activity.md](reference/activity.md). +2. **Distinguish "did" from "viewed".** `user_activity` returns both. Surface creates / edits / decisions; demote pure views. +3. **Cite sources.** Every claim should link back to a doc, meeting, or commit so the user can verify and dig deeper. +4. **Personalize via memory.** When framing a summary, `read_memory` (especially `RolesAndResponsibilities` and `ActiveProjects`) tells you what *themes* the user thinks they work on. Group by those themes when possible. +5. **Apply vetting.** Even self-activity should be filtered. See [`using-glean/reference/vetting.md`](../../../../glean-core/skills/using-glean/reference/vetting.md). + +## Related commands + +- `/glean-productivity:my-week` — full weekly summary with analysis +- `/glean-productivity:daily-briefing` — what happened in the last 24 hours diff --git a/plugins/glean-productivity/skills/using-glean-productivity/reference/activity.md b/plugins/glean-productivity/skills/using-glean-productivity/reference/activity.md new file mode 100644 index 0000000..f7e5981 --- /dev/null +++ b/plugins/glean-productivity/skills/using-glean-productivity/reference/activity.md @@ -0,0 +1,73 @@ +# Activity & accomplishments synthesis + +Retrospective questions: what the user did, what they shipped, what they touched. + +## Trigger shapes + +- "What have I been working on?" +- "What did I do last week?" +- "Summarize my recent activity" +- "What projects have I touched?" +- "Help me write my status update" +- "What should I put in my standup?" + +## Workflow + +1. **Pull the activity feed.** `user_activity(start_date=..., end_date=...)` for the requested window. Remember `end_date` is exclusive — to include all of "last Friday" set `end_date` to the day after. + +2. **Pull personalization context.** `read_memory(action="read", category="ActiveProjects")` (and optionally `RolesAndResponsibilities`) to learn what *themes* the user organizes their work around. + +3. **Vet the activity items.** From the raw feed, filter aggressively: + - **Include**: created docs, made decisions, completed tasks, shipped code, posted updates, ran reviews + - **Maybe**: meaningful comments, design reviews attended + - **Exclude**: brief views, auto-generated notifications, mass announcements, items the user only had peripheral involvement with + +4. **Group by theme.** Use the `ActiveProjects` memory entries as the grouping axis when they exist. Otherwise group by repo / project / topic inferred from the activities. + +5. **Rank within theme.** Most significant first. "Shipped feature X" beats "edited doc Y". + +6. **Surface collaboration.** Note who the user worked with (co-authors, commenters, meeting attendees) — this often makes status updates more useful than a list of artifacts. + +## Output template + +```markdown +## [Time period] — your activity + +### Highlights +- [Most significant accomplishment with link] +- [Next-most] +- [Next-most] + +### By project / theme + +**[Project A]** — N items +- [Significant item 1] ([link]) +- [Significant item 2] ([link]) + +**[Project B]** — N items +- ... + +### Collaborations +- Worked with [Person] on [thread/topic] — [link] +- ... + +### In progress +- [Item] — [where you left it] +``` + +## When activity is sparse + +If the requested window has very little, say so cleanly: + +```markdown +Limited activity in [window]. Found [N] items, of which [M] were meaningful contributions. + +Possible reasons: +- Time off, focused-work mode, or work in systems not indexed by Glean +- The window is short; consider a longer one + +Items found: +- [List the few that exist] +``` + +Don't pad. The user will trust a sparse-but-honest report; they will distrust a padded one. diff --git a/plugins/glean-productivity/skills/using-glean-productivity/reference/priorities.md b/plugins/glean-productivity/skills/using-glean-productivity/reference/priorities.md new file mode 100644 index 0000000..03f8bee --- /dev/null +++ b/plugins/glean-productivity/skills/using-glean-productivity/reference/priorities.md @@ -0,0 +1,77 @@ +# Priorities & blockers triage + +Prospective questions: what needs the user's attention right now. + +## Trigger shapes + +- "What's urgent?" +- "What needs my attention?" +- "What should I focus on?" +- "What's blocking me?" +- "What's waiting on me?" +- "What can't wait?" +- "Daily briefing" / "morning briefing" + +## Signal sources + +| Source | What it surfaces | +|---|---| +| `search` for direct mentions of the user | People tagging or @-mentioning them | +| `meeting_lookup` for recent meetings | Action items assigned to them | +| `search` for "urgent" / "ASAP" / "blocking" + their name | Explicit urgency markers | +| Email tools (`gmail_search` / `outlook_search`) with `is:important is:unread` | Unread important threads | +| `user_activity` (recent) | Threads they've been engaged in | + +## Workflow + +1. **Cast the net wide.** Pull from each signal source above for the past 1–7 days (depending on whether it's a daily briefing or a weekly look). + +2. **Vet for genuine urgency.** Most "urgent" items aren't. Apply: + - **Truly urgent**: explicit deadline today / tomorrow, blocking a person who's actively waiting, marked urgent with evidence (not just a label) + - **Important**: action assigned to user, question awaiting their response, decision due + - **Noise** (filter out): mass announcements, CC'd threads they're not the primary audience for, "urgent" labels on resolved or stale items + +3. **Tier the rest.** Three levels: + - **Tier 1 — Today**: explicit deadlines today, blockers on others, items that will hurt if not addressed today + - **Tier 2 — This week**: action items, awaiting-response questions, review requests + - **Tier 3 — Awareness**: decisions affecting their area, FYI updates worth knowing + +4. **Order Tier 1 by impact.** Within Tier 1, sort by who's blocked and how badly. A teammate waiting to ship beats a low-impact deadline. + +## Output template + +```markdown +## Priority triage — [date] + +### Tier 1: Today +| Item | Source | Why it's urgent | +|---|---|---| +| [Item] | [link / source] | [Specific reason — deadline, blocker, etc.] | + +### Tier 2: This week +| Item | Source | When | +|---|---|---| +| [Item] | [link / source] | [Date if known] | + +### Tier 3: Awareness +- [Item] — [why worth knowing] + +### Filtered (looked urgent but isn't) +- [Item] — [why filtered: CC'd only, already resolved, low impact] +``` + +## When nothing is urgent + +This is a valid and valuable answer: + +```markdown +## Priority triage — [date] + +No urgent items requiring immediate attention. + +Checked: direct mentions, meeting action items, blocking requests, urgent-marked threads. + +Suggestion: this might be a good window for [deep work / planning / catching up on a deferred item]. +``` + +The user will trust this report. Padding it with false urgency burns trust on every alarm that turns out to be nothing. From a85874cfcbb0764e5cb3fa8bf9356f0036c92107 Mon Sep 17 00:00:00 2001 From: Steve Calvert Date: Mon, 11 May 2026 17:38:56 -0700 Subject: [PATCH 5/7] refactor(workflow-plugins): migrate commands to skills, add when_to_use trigger phrases Move the workflow files in glean-search, glean-people, glean-meetings, and glean-docs from commands/.md to skills//SKILL.md. Per the Claude Code plugin docs, the two are runtime-equivalent ("a file at commands/deploy.md and a skill at skills/deploy/SKILL.md both create /deploy and work the same way"), but skills/ is the recommended shape for new plugins and unlocks the reference/ directory pattern for future depth. Slash invocations are unchanged: /glean-search:search, /glean-people:find-expert, /glean-people:stakeholders, /glean-meetings:catch-up, /glean-meetings:meeting-prep, /glean-docs:onboarding, /glean-docs:verify-rfc all continue to work. While migrating, add a when_to_use field to each skill's frontmatter with concrete trigger phrases so the skills can auto-trigger on natural-language asks. Also normalize a few `mcp__glean` runtime-name references in skill bodies to the bare `Glean MCP` phrasing. Plugin READMEs updated to reflect the skills/ structure. Co-Authored-By: Claude Opus 4.7 (1M context) --- plugins/glean-docs/README.md | 26 +++++++++-------- .../onboarding/SKILL.md} | 6 +++- .../verify-rfc/SKILL.md} | 6 +++- plugins/glean-meetings/README.md | 26 +++++++++-------- .../catch-up.md => skills/catch-up/SKILL.md} | 8 ++++-- .../meeting-prep/SKILL.md} | 6 +++- plugins/glean-people/README.md | 28 ++++++++++--------- .../find-expert/SKILL.md} | 8 ++++-- .../stakeholders/SKILL.md} | 8 ++++-- plugins/glean-search/README.md | 26 +++++++++-------- .../search.md => skills/search/SKILL.md} | 6 +++- 11 files changed, 96 insertions(+), 58 deletions(-) rename plugins/glean-docs/{commands/onboarding.md => skills/onboarding/SKILL.md} (92%) rename plugins/glean-docs/{commands/verify-rfc.md => skills/verify-rfc/SKILL.md} (92%) rename plugins/glean-meetings/{commands/catch-up.md => skills/catch-up/SKILL.md} (90%) rename plugins/glean-meetings/{commands/meeting-prep.md => skills/meeting-prep/SKILL.md} (89%) rename plugins/glean-people/{commands/find-expert.md => skills/find-expert/SKILL.md} (90%) rename plugins/glean-people/{commands/stakeholders.md => skills/stakeholders/SKILL.md} (91%) rename plugins/glean-search/{commands/search.md => skills/search/SKILL.md} (87%) diff --git a/plugins/glean-docs/README.md b/plugins/glean-docs/README.md index bd8e9c8..aa44434 100644 --- a/plugins/glean-docs/README.md +++ b/plugins/glean-docs/README.md @@ -1,6 +1,6 @@ # Glean Docs -**Document intelligence - analyze docs, verify specs against implementation, and onboard to new areas.** +**Document intelligence — analyze docs, verify specs against implementation, and onboard to new areas.** Deep analysis of enterprise documents and specifications. @@ -15,16 +15,18 @@ claude plugin install glean-core # if not already installed claude plugin install glean-docs ``` -## What's Included +## What's included + +### Skills + +- **`verify-rfc`** — Auto-triggers on "verify the RFC", "compare design doc to implementation", "is the spec implemented", "what's drifted from the RFC". Invokable as `/glean-docs:verify-rfc `. +- **`onboarding`** — Auto-triggers on "onboard me on", "get me up to speed on", "intro to [team]", "I'm new to". Invokable as `/glean-docs:onboarding `. ### Agent -- **doc-reader** - Reads and analyzes enterprise documents to extract key information, requirements, or structured summaries -### Commands -- `/glean-docs:verify-rfc ` - Verify an RFC or design doc against the actual implementation -- `/glean-docs:onboarding ` - Get up to speed on a new team or project +- **doc-reader** — Reads and analyzes enterprise documents to extract key information, requirements, or structured summaries. -## Example Usage +## Example usage ```bash # Verify specs against code @@ -35,17 +37,17 @@ claude plugin install glean-docs /glean-docs:onboarding payments team /glean-docs:onboarding search infrastructure -# The doc-reader agent is automatically triggered +# Skills auto-trigger on natural-language asks "Summarize the key requirements from the API spec" "What does the design doc say about error handling?" ``` ## Features -- **RFC Verification** - Compare specs to implementation, find gaps -- **Onboarding** - Curated introduction to a team or project -- **Document Analysis** - Extract requirements, decisions, and key points -- **Cross-Reference** - Connect docs to code and people +- **RFC verification** — compare specs to implementation, find gaps +- **Onboarding** — curated introduction to a team or project +- **Document analysis** — extract requirements, decisions, and key points +- **Cross-reference** — connect docs to code and people ## Support diff --git a/plugins/glean-docs/commands/onboarding.md b/plugins/glean-docs/skills/onboarding/SKILL.md similarity index 92% rename from plugins/glean-docs/commands/onboarding.md rename to plugins/glean-docs/skills/onboarding/SKILL.md index beb9591..f3e3d1c 100644 --- a/plugins/glean-docs/commands/onboarding.md +++ b/plugins/glean-docs/skills/onboarding/SKILL.md @@ -1,5 +1,9 @@ --- -description: Get up to speed on a new team or project +description: Get up to speed on a new team, project, or area — surface key people, foundational docs, current priorities, and recent activity +when_to_use: | + Trigger phrases include "onboard me on", "get me up to speed on", "intro to [team / area / project]", "I'm new to", "help me understand [team]", "where do I start with", "ramp up on", "background on the [team] team". + + Use when the user is joining a new team, taking on a new area, or learning a system from scratch and wants a structured ramp-up rather than searching ad hoc. argument-hint: Team or project name (e.g., "payments team", "search infrastructure") --- diff --git a/plugins/glean-docs/commands/verify-rfc.md b/plugins/glean-docs/skills/verify-rfc/SKILL.md similarity index 92% rename from plugins/glean-docs/commands/verify-rfc.md rename to plugins/glean-docs/skills/verify-rfc/SKILL.md index 51f64bb..3abae36 100644 --- a/plugins/glean-docs/commands/verify-rfc.md +++ b/plugins/glean-docs/skills/verify-rfc/SKILL.md @@ -1,5 +1,9 @@ --- -description: Verify an RFC or design doc against the actual implementation +description: Verify an RFC or design doc against the actual implementation — find drift, missing pieces, and undocumented changes +when_to_use: | + Trigger phrases include "verify the RFC", "compare design doc to implementation", "is the spec implemented", "does the code match the design", "what's drifted from the RFC", "audit the [doc] against", "spec compliance check", "is what we built what we designed". + + Use when the user has an RFC, ADR, design doc, or spec and wants to know how the actual implementation compares — what's done, what's missing, what diverged. argument-hint: RFC URL or topic to search for --- diff --git a/plugins/glean-meetings/README.md b/plugins/glean-meetings/README.md index 1c7f3cd..6850828 100644 --- a/plugins/glean-meetings/README.md +++ b/plugins/glean-meetings/README.md @@ -1,6 +1,6 @@ # Glean Meetings -**Meeting intelligence - analyze transcripts, prepare for meetings, and catch up after time off.** +**Meeting intelligence — analyze transcripts, prepare for meetings, and catch up after time off.** Get more value from your meetings with AI-powered analysis. @@ -15,16 +15,18 @@ claude plugin install glean-core # if not already installed claude plugin install glean-meetings ``` -## What's Included +## What's included + +### Skills + +- **`meeting-prep`** — Auto-triggers on "prep for my meeting", "context for the [meeting]", "1:1 prep with", "what should I know before". Invokable as `/glean-meetings:meeting-prep `. +- **`catch-up`** — Auto-triggers on "what did I miss", "catch me up", "I'm back from PTO", "summarize while I was away". Invokable as `/glean-meetings:catch-up