Skills architecture v2.0

CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## Unreleased
+
+### ⚠️ Breaking changes
+
+This release consolidates several plugins around the [Anthropic-recommended progressive-disclosure pattern](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices) — one parent skill per plugin with topic-specific reference files loaded on demand. Several skill names have changed; the slash invocation paths for the corresponding consolidated skills have changed accordingly.
+
+The motivation: the old structure put many sibling skills' descriptions into Claude's startup context simultaneously, which on a typical install pushed the description budget over its limit and caused descriptions (the trigger signals) to be silently truncated. The consolidation drops one description per plugin into the listing while moving per-tool / per-topic depth into reference files that are only read when needed.
+
+#### `glean-core` — six skills consolidated into one
+
+| Removed slash path | Replacement |
+|---|---|
+| `/glean-core:enterprise-search` | `/glean-core:using-glean` (or just ask in natural language) |
+| `/glean-core:meeting-context` | `/glean-core:using-glean` |
+| `/glean-core:people-lookup` | `/glean-core:using-glean` |
+| `/glean-core:synthesis-patterns` | `/glean-core:using-glean` |
+| `/glean-core:confidence-signals` | `/glean-core:using-glean` |
+| `/glean-core:glean-tools-guide` | `/glean-core:using-glean` |
+
+The new `using-glean` skill carries an intent-to-tool decision tree and links to per-MCP-tool reference files (`reference/search.md`, `reference/employee-search.md`, `reference/meeting-lookup.md`, etc.).
+
+#### `glean-code` — two skills consolidated into one
+
+| Removed slash path | Replacement |
+|---|---|
+| `/glean-code:code-exploration` | `/glean-code:using-glean-code` |
+| `/glean-code:plan-prep` | `/glean-code:using-glean-code` |
+
+#### `glean-productivity` — two skills consolidated into one
+
+| Removed slash path | Replacement |
+|---|---|
+| `/glean-productivity:activity-synthesis` | `/glean-productivity:using-glean-productivity` |
+| `/glean-productivity:priority-signals` | `/glean-productivity:using-glean-productivity` |
+
+#### Workflow plugins — `commands/` migrated to `skills/`
+
+`glean-search`, `glean-people`, `glean-meetings`, and `glean-docs` had `commands/` directories that have been migrated to `skills/`. Per Anthropic's plugin docs, these are equivalent at runtime — 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). The migration enables the skills to auto-trigger on natural-language phrases and unlocks the `reference/` directory pattern for future use.
+
+### Improvements
+
+- Description quality: every plugin's `SKILL.md` now uses a `description` + `when_to_use` pair with concrete trigger phrasing, dropping the previous "Auto-triggers when X tool is considered" framing that didn't reflect how skill triggering actually works.
+- `scripts/validate-plugins.mjs`: now correctly passes through YAML block-scalar indicators (`|` and `>`) instead of double-quoting them, allowing multi-paragraph `when_to_use` content.
+
+
 ## [1.1.1](///compare/v1.1.0...v1.1.1) (2026-04-10)
 
 ### Bug Fixes

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 <system>` - Get architectural context from internal repos
-- `/glean-code:find-examples <API/pattern>` - Find usage examples across the org
-- `/glean-code:code-owners <component>` - Identify who owns/maintains code areas
-- `/glean-code:similar-code <pattern>` - Find similar implementations across repos
-- `/glean-code:plan-prep <task>` - Research enterprise context before entering plan mode
 
-## Example Usage
+- `/glean-code:codebase-context <system>` — Get architectural context from internal repos
+- `/glean-code:find-examples <API/pattern>` — Find usage examples across the org
+- `/glean-code:code-owners <component>` — Identify who owns/maintains code areas
+- `/glean-code:similar-code <pattern>` — Find similar implementations across repos
+- `/glean-code:plan-prep <task>` — 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