Skills architecture v2.0#31
Merged
Merged
Conversation
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) <noreply@anthropic.com>
…er-tool reference files
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_<server>__<tool> 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) <noreply@anthropic.com>
…ith reference files
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) <noreply@anthropic.com>
…n-productivity with reference files
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) <noreply@anthropic.com>
…se trigger phrases
Move the workflow files in glean-search, glean-people, glean-meetings,
and glean-docs from commands/<name>.md to skills/<name>/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) <noreply@anthropic.com>
Apply the description-rewriting principles used in this release to the remaining single-skill plugins (glean-project, glean-dev-docs, glean-skills): split description and when_to_use fields, drop the "Auto-triggers when X" framing, lead with concrete user phrasings, state boundaries. Clean up bodies that referenced now-deleted skills or the deprecated mcp__glean_<server>__<tool> runtime-name pattern: - project-awareness pointed to the removed glean-tools-guide skill; redirected to using-glean's reference files instead. - dev-docs-guide documented its tools by their mcp__glean_dev_docs__ runtime form; switched to bare names (docs_search, docs_fetch). - glean-skills/commands/discover.md normalized two `mcp__glean` references to bare `Glean MCP` phrasing. Also fix a pre-existing missing-namespace bug in glean-project/README.md where /project-handoff was documented without the /glean-project: prefix. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ames Add an Unreleased section documenting the breaking renames and the underlying motivation (description budget overflow causing auto-triggering to fail), with a per-plugin mapping from old slash paths to their replacements. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
steve-calvert-glean
changed the title
david-hamilton-glean
approved these changes
May 12, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Consolidate plugin skills around the Anthropic-recommended progressive-disclosure pattern — one parent skill per plugin with topic-specific reference files loaded on demand. Restores reliable auto-triggering by reducing the always-on skill description footprint.
Why
The previous structure put many sibling skills' descriptions into Claude's startup context simultaneously. On a typical install, this exceeded the skill description budget (~1% of the model's context window) and caused descriptions to be silently truncated, breaking auto-triggering.
/doctorconfirmed the overflow.The new layout drops one description per plugin into the listing, with per-tool / per-topic depth living in
reference/files that are read only when the agent needs them.What changes
glean-core: 6 skills →using-glean+ per-MCP-tool reference files (one per Glean tool:search.md,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,knowledge-graph.md,agents-as-tools.md, plus cross-cuttingsynthesis.mdandvetting.md)glean-code: 2 skills →using-glean-code+ 2 reference filesglean-productivity: 2 skills →using-glean-productivity+ 2 reference filesglean-search,glean-people,glean-meetings,glean-docs):commands/migrated toskills/per the official guidance thatcommands/is the legacy form. Slash invocation paths unchanged.glean-project,glean-dev-docs,glean-skills): description andwhen_to_usefrontmatter tightened; stale references to deleted skills cleaned up.scripts/validate-plugins.mjsnow passes through YAML block-scalar indicators (|and>) instead of breaking them.Breaking changes
Several skill names have changed; consolidated-skill slash paths replace the old per-skill paths. Workflow-plugin slash paths are unchanged. See CHANGELOG.md for the full mapping.
Test plan
node scripts/validate-plugins.mjspasses--plugin-dirand confirm/doctorshows description budget no longer overflowingusing-gleanfires, routes toreference/search.mdusing-glean+reference/employee-search.mdusing-glean+reference/meeting-lookup.mdusing-glean-codeusing-glean-productivity/glean-people:find-expert/glean-meetings:catch-up/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🤖 Generated with Claude Code