From d1f43f871291528518100010ac5430dcfe88a971 Mon Sep 17 00:00:00 2001 From: Steve Calvert Date: Thu, 19 Mar 2026 16:30:14 -0700 Subject: [PATCH 1/2] feat: auto-generate Agent Skills from schema registry MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add `glean generate-skills` command that deterministically generates SKILL.md files (following the agentskills.io spec) from the CLI's own schema registry. This ensures skills stay in sync with commands — when a flag or subcommand changes, re-running the generator updates the corresponding skill. What's included: - `internal/skills/generator.go` — template-based renderer that reads from the schema registry and produces per-command SKILL.md files - `cmd/generate_skills.go` — hidden `generate-skills` command - 17 generated skills + 1 shared skill covering all namespace commands - `.github/workflows/generate-skills.yml` — CI workflow that regenerates skills on push to main when cmd/ or schema code changes - Updated README with `npx skills add` installation instructions Replaces the previous hand-written flat skill files with structured, folder-based skills installable via: npx skills add https://github.com/gleanwork/glean-cli Inspired by Google Workspace CLI's generate-skills approach. Co-Authored-By: Claude Opus 4.6 (1M context) --- .github/workflows/generate-skills.yml | 55 ++++ README.md | 42 ++- cmd/generate_skills.go | 32 +++ cmd/root.go | 5 + internal/skills/generator.go | 379 ++++++++++++++++++++++++++ skills/CONTEXT.md | 61 ----- skills/chat.md | 65 ----- skills/glean-activity/SKILL.md | 44 +++ skills/glean-agents/SKILL.md | 48 ++++ skills/glean-announcements/SKILL.md | 46 ++++ skills/glean-answers/SKILL.md | 48 ++++ skills/glean-api/SKILL.md | 42 +++ skills/glean-chat/SKILL.md | 41 +++ skills/glean-collections/SKILL.md | 50 ++++ skills/glean-documents/SKILL.md | 47 ++++ skills/glean-entities/SKILL.md | 44 +++ skills/glean-insights/SKILL.md | 44 +++ skills/glean-messages/SKILL.md | 43 +++ skills/glean-pins/SKILL.md | 48 ++++ skills/glean-search/SKILL.md | 53 ++++ skills/glean-shared/SKILL.md | 88 ++++++ skills/glean-shortcuts/SKILL.md | 49 ++++ skills/glean-tools/SKILL.md | 45 +++ skills/glean-verification/SKILL.md | 46 ++++ skills/schema.md | 45 --- skills/search.md | 74 ----- skills/shortcuts.md | 57 ---- 27 files changed, 1331 insertions(+), 310 deletions(-) create mode 100644 .github/workflows/generate-skills.yml create mode 100644 cmd/generate_skills.go create mode 100644 internal/skills/generator.go delete mode 100644 skills/CONTEXT.md delete mode 100644 skills/chat.md create mode 100644 skills/glean-activity/SKILL.md create mode 100644 skills/glean-agents/SKILL.md create mode 100644 skills/glean-announcements/SKILL.md create mode 100644 skills/glean-answers/SKILL.md create mode 100644 skills/glean-api/SKILL.md create mode 100644 skills/glean-chat/SKILL.md create mode 100644 skills/glean-collections/SKILL.md create mode 100644 skills/glean-documents/SKILL.md create mode 100644 skills/glean-entities/SKILL.md create mode 100644 skills/glean-insights/SKILL.md create mode 100644 skills/glean-messages/SKILL.md create mode 100644 skills/glean-pins/SKILL.md create mode 100644 skills/glean-search/SKILL.md create mode 100644 skills/glean-shared/SKILL.md create mode 100644 skills/glean-shortcuts/SKILL.md create mode 100644 skills/glean-tools/SKILL.md create mode 100644 skills/glean-verification/SKILL.md delete mode 100644 skills/schema.md delete mode 100644 skills/search.md delete mode 100644 skills/shortcuts.md diff --git a/.github/workflows/generate-skills.yml b/.github/workflows/generate-skills.yml new file mode 100644 index 0000000..4ed8be7 --- /dev/null +++ b/.github/workflows/generate-skills.yml @@ -0,0 +1,55 @@ +name: Generate Skills + +on: + push: + branches: [main] + paths: + - "cmd/**" + - "internal/schema/**" + - "internal/skills/**" + workflow_dispatch: + +concurrency: + group: generate-skills + cancel-in-progress: true + +jobs: + generate: + name: Regenerate skills + runs-on: ubuntu-latest + permissions: + contents: write + + steps: + - uses: actions/checkout@v6 + + - name: Set up mise + uses: jdx/mise-action@v4 + with: + cache: true + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Build CLI + run: go build -o glean + + - name: Generate skills + run: ./glean generate-skills + + - name: Check for changes + id: diff + run: | + if git diff --quiet skills/; then + echo "changed=false" >> "$GITHUB_OUTPUT" + else + echo "changed=true" >> "$GITHUB_OUTPUT" + fi + + - name: Commit and push + if: steps.diff.outputs.changed == 'true' + run: | + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + git add skills/ + git commit -m "chore: regenerate skills from schema registry [skip ci]" + git push diff --git a/README.md b/README.md index 3239180..b24bb47 100644 --- a/README.md +++ b/README.md @@ -299,15 +299,41 @@ glean completion fish # Fish ## Agent Skills -The `skills/` directory contains markdown skill files for AI coding agents (Claude Code, etc.). They describe how to use each CLI command effectively in an automated context — flag patterns, output formats, and composition examples. +The `skills/` directory contains [Agent Skills](https://agentskills.io) for AI coding agents (Claude Code, Codex, etc.). Each skill teaches the agent how to use a specific CLI command effectively — flags, output formats, and composition patterns. -| File | Description | -|------|-------------| -| `skills/CONTEXT.md` | CLI-wide guidance: auth, output formats, error handling | -| `skills/search.md` | How to use `glean search` in agent pipelines | -| `skills/chat.md` | How to use `glean chat` for AI-assisted workflows | -| `skills/schema.md` | How to use `glean schema` for command introspection | -| `skills/shortcuts.md` | How to manage go-links programmatically | +### Install + +```bash +# Install all skills at once +npx skills add https://github.com/gleanwork/glean-cli + +# Or pick only what you need +npx skills add https://github.com/gleanwork/glean-cli/tree/main/skills/glean-search +npx skills add https://github.com/gleanwork/glean-cli/tree/main/skills/glean-chat +``` + +### Available Skills + +| Skill | Description | +|-------|-------------| +| `glean-shared` | Shared patterns: auth, global flags, output formatting | +| `glean-search` | Search across company knowledge | +| `glean-chat` | Chat with Glean Assistant | +| `glean-schema` | Runtime JSON schema introspection | +| `glean-agents` | List, inspect, and run Glean AI agents | +| `glean-documents` | Retrieve and summarize documents | +| `glean-collections` | Manage curated document collections | +| `glean-entities` | Look up people, teams, and entities | +| `glean-answers` | Manage curated Q&A pairs | +| `glean-shortcuts` | Manage go-links | +| `glean-pins` | Manage promoted search results | +| `glean-announcements` | Manage company announcements | +| `glean-api` | Raw authenticated API access | +| `glean-activity` | Report user activity and feedback | +| `glean-verification` | Document verification workflows | +| `glean-tools` | List and run platform tools | +| `glean-messages` | Retrieve indexed messages | +| `glean-insights` | Search and usage analytics | ## Contributing diff --git a/cmd/generate_skills.go b/cmd/generate_skills.go new file mode 100644 index 0000000..1829203 --- /dev/null +++ b/cmd/generate_skills.go @@ -0,0 +1,32 @@ +package cmd + +import ( + "github.com/gleanwork/glean-cli/internal/skills" + "github.com/spf13/cobra" +) + +// NewCmdGenerateSkills creates the generate-skills command. +func NewCmdGenerateSkills() *cobra.Command { + var outputDir string + + cmd := &cobra.Command{ + Use: "generate-skills", + Short: "Generate SKILL.md files from the CLI's schema registry", + Long: `Generates Agent Skills (https://agentskills.io) from the CLI's own +schema registry. Each command gets a SKILL.md with frontmatter, flags, +subcommands, and examples — derived deterministically from the registered +schemas. + +Run this after adding or modifying commands to keep skills in sync. + + glean generate-skills # write to skills/ + glean generate-skills --output-dir out/ # write to out/`, + RunE: func(cmd *cobra.Command, args []string) error { + return skills.Generate(outputDir) + }, + } + + cmd.Flags().StringVar(&outputDir, "output-dir", "skills", "Output directory for generated skills") + + return cmd +} diff --git a/cmd/root.go b/cmd/root.go index 7eaa610..d783438 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -151,6 +151,11 @@ func NewCmdRoot() *cobra.Command { cmd.AddCommand(sub) } + // Dev/maintenance commands (hidden from default help) + genSkills := NewCmdGenerateSkills() + genSkills.Hidden = true + cmd.AddCommand(genSkills) + // Propagate settings to all subcommands for _, subCmd := range cmd.Commands() { subCmd.SilenceUsage = true diff --git a/internal/skills/generator.go b/internal/skills/generator.go new file mode 100644 index 0000000..db9f91c --- /dev/null +++ b/internal/skills/generator.go @@ -0,0 +1,379 @@ +// Package skills generates SKILL.md files from the CLI's own schema registry. +// +// Usage: glean generate-skills [--output-dir skills/] +package skills + +import ( + "fmt" + "os" + "path/filepath" + "sort" + "strings" + "text/template" + + "github.com/gleanwork/glean-cli/internal/schema" +) + +// subcommandMap provides human-friendly descriptions for subcommands that +// the schema registry doesn't capture (schemas are per-namespace, not per-sub). +// Keys are "namespace.subcommand". +var subcommandMap = map[string]string{ + "agents.list": "List all available agents", + "agents.get": "Get details of a specific agent", + "agents.schemas": "Get input/output schemas for an agent", + "agents.run": "Run an agent", + "answers.list": "List all curated answers", + "answers.get": "Get a specific answer", + "answers.create": "Create a new answer", + "answers.update": "Update an existing answer", + "answers.delete": "Delete an answer", + "announcements.create": "Create a new announcement", + "announcements.update": "Update an existing announcement", + "announcements.delete": "Delete an announcement", + "collections.list": "List all collections", + "collections.get": "Get a specific collection", + "collections.create": "Create a new collection", + "collections.update": "Update a collection", + "collections.delete": "Delete a collection", + "collections.add-items": "Add documents to a collection", + "collections.delete-item": "Remove a document from a collection", + "documents.get": "Retrieve document metadata by URL or ID", + "documents.summarize": "Generate an AI summary of a document", + "documents.get-by-facets": "Retrieve documents matching facet filters", + "documents.get-permissions": "Inspect who has access to a document", + "entities.list": "List entities by type and query", + "entities.read-people": "Get detailed people profiles", + "insights.get": "Get analytics data", + "messages.get": "Retrieve a specific message", + "pins.list": "List all pins", + "pins.get": "Get a specific pin", + "pins.create": "Create a new pin", + "pins.update": "Update a pin", + "pins.remove": "Remove a pin", + "shortcuts.list": "List all shortcuts", + "shortcuts.get": "Get a specific shortcut", + "shortcuts.create": "Create a new shortcut", + "shortcuts.update": "Update an existing shortcut", + "shortcuts.delete": "Delete a shortcut", + "tools.list": "List available platform tools", + "tools.run": "Execute a platform tool", + "verification.list": "List documents pending verification", + "verification.verify": "Mark a document as verified", + "verification.remind": "Send a verification reminder", + "activity.report": "Report a user activity event", + "activity.feedback": "Submit feedback on search results", +} + +// skillDescription maps command names to richer descriptions for the SKILL.md +// frontmatter. These are tuned for agent skill triggering. +var skillDescription = map[string]string{ + "search": "Search across company knowledge with the Glean CLI. Use when finding documents, policies, engineering docs, or any information across enterprise data sources.", + "chat": "Chat with Glean Assistant from the command line. Use when asking questions, summarizing documents, or getting AI-powered answers about company knowledge.", + "api": "Make raw authenticated HTTP requests to any Glean REST API endpoint. Use when no dedicated command exists or for advanced API access.", + "agents": "List, inspect, and run Glean AI agents. Use when discovering available agents, viewing agent schemas, or invoking agents programmatically.", + "documents": "Retrieve, summarize, and inspect documents indexed by Glean. Use when getting document content, summaries, permissions, or metadata by URL.", + "collections": "Manage curated document collections in Glean. Use when creating, updating, or organizing themed sets of documents.", + "entities": "Look up people, teams, and custom entities in Glean. Use when finding employees, org structure, team members, or expertise.", + "answers": "Manage curated Q&A pairs in Glean. Use when creating, updating, or listing company-approved answers to common questions.", + "shortcuts": "Manage Glean go-links (shortcuts). Use when creating, listing, updating, or deleting short URL aliases like go/wiki.", + "pins": "Manage promoted search results (pins) in Glean. Use when pinning specific documents to appear first for certain queries.", + "announcements": "Manage time-bounded company announcements in Glean. Use when creating, updating, or deleting announcements that surface across the Glean UI.", + "activity": "Report user activity and submit feedback to Glean. Use when logging user interactions or providing relevance feedback on search results.", + "verification": "Manage document verification and review workflows in Glean. Use when verifying document accuracy, listing pending verifications, or sending review reminders.", + "tools": "List and run Glean platform tools. Use when discovering available platform tools or executing them programmatically.", + "messages": "Retrieve indexed messages from Slack, Teams, and other messaging platforms via Glean. Use when searching for or reading specific messages.", + "insights": "Retrieve search and usage analytics from Glean. Use when analyzing search patterns, popular queries, or platform adoption metrics.", +} + +// FlagInfo holds rendered flag data for templates. +type FlagInfo struct { + Name string + Type string + Default string + Description string + Required bool +} + +// SkillData holds all data needed to render a SKILL.md template. +type SkillData struct { + Name string + Description string + Command string + SchemaDesc string + Flags []FlagInfo + Subcommands []SubcommandInfo + Example string + HasDryRun bool +} + +// SubcommandInfo describes a subcommand. +type SubcommandInfo struct { + Name string + Description string +} + +var skillTmpl = template.Must(template.New("skill").Parse(`--- +name: glean-{{ .Command }} +description: "{{ .Description }}" +--- + +# glean {{ .Command }} + +> **PREREQUISITE:** Read ` + "`../glean-shared/SKILL.md`" + ` for auth, global flags, and security rules. + +{{ .SchemaDesc }} + +` + "```bash" + ` +glean {{ .Command }}{{ if .Subcommands }} {{ end }} [flags] +` + "```" + ` +{{ if .Subcommands }} +## Subcommands + +| Subcommand | Description | +|------------|-------------| +{{ range .Subcommands -}} +| ` + "`{{ .Name }}`" + ` | {{ .Description }} | +{{ end }}{{ end }} +## Flags + +| Flag | Type | Default | Description | +|------|------|---------|-------------| +{{ range .Flags -}} +| ` + "`{{ .Name }}`" + ` | {{ .Type }} | {{ .Default }} | {{ .Description }}{{ if .Required }} **(required)**{{ end }} | +{{ end }} +## Examples + +` + "```bash" + ` +{{ .Example }} +` + "```" + ` + +## Discovering Commands + +` + "```bash" + ` +# Show machine-readable schema for this command +glean schema {{ .Command }} + +# List all available commands +glean schema | jq '.commands' +` + "```" + ` +`)) + +var sharedTmpl = template.Must(template.New("shared").Parse(`--- +name: glean-shared +description: "Glean CLI: Shared patterns for authentication, global flags, output formatting, and security rules." +compatibility: Requires the glean binary on $PATH. Install via brew install gleanwork/tap/glean-cli +--- + +# glean — Shared Reference + +> **Read this first.** All other glean skills assume familiarity with auth, flags, and output formats described here. + +## Installation + +` + "```bash" + ` +brew install gleanwork/tap/glean-cli +` + "```" + ` + +## Authentication + +` + "```bash" + ` +# Browser-based OAuth (interactive — recommended) +glean auth login + +# Verify credentials +glean auth status + +# CI/scripting (no interactive setup needed) +export GLEAN_API_TOKEN=your-token +export GLEAN_HOST=your-company-be.glean.com +` + "```" + ` + +Credentials resolve in this order: environment variables → system keyring → ~/.glean/config.json. + +## CLI Syntax + +` + "```bash" + ` +glean [subcommand] [flags] +` + "```" + ` + +### Global Flags + +| Flag | Description | +|------|-------------| +| --output | json (default), ndjson (one result per line), text | +| --fields | Dot-path field projection (e.g. results.document.title,results.document.url) | +| --json | Complete JSON request body (overrides all other flags) | +| --dry-run | Print request body without sending | + +## Schema Introspection + +Always call glean schema before invoking a command you haven't used before. + +` + "```bash" + ` +glean schema | jq '.commands' # list all commands +glean schema search | jq '.flags' # flags for search +` + "```" + ` + +## Security Rules + +- **Never** output API tokens or secrets directly +- **Always** use --dry-run before write/delete operations in automated pipelines +- Prefer environment variables over config files for CI/CD + +## Error Handling + +All errors go to stderr; stdout contains only structured output. +Exit code 0 = success, non-zero = error. + +## Available Commands + +| Command | Description | +|---------|-------------| +{{ range .Commands -}} +| [glean {{ .Name }}](../glean-{{ .Name }}/SKILL.md) | {{ .Description }} | +{{ end }} +`)) + +// CommandEntry is used by the shared skill template. +type CommandEntry struct { + Name string + Description string +} + +// skipCommands lists commands that should not get their own skill. +var skipCommands = map[string]bool{ + "version": true, +} + +// Generate writes SKILL.md files to outputDir for all registered schemas. +func Generate(outputDir string) error { + // Generate shared skill + commands := schema.List() + var entries []CommandEntry + for _, name := range commands { + if skipCommands[name] { + continue + } + s, err := schema.Get(name) + if err != nil { + continue + } + entries = append(entries, CommandEntry{Name: name, Description: s.Description}) + } + + if err := writeSharedSkill(outputDir, entries); err != nil { + return fmt.Errorf("writing shared skill: %w", err) + } + fmt.Fprintf(os.Stderr, " wrote glean-shared/SKILL.md\n") + + // Generate per-command skills + for _, name := range commands { + if skipCommands[name] { + continue + } + s, err := schema.Get(name) + if err != nil { + continue + } + if err := writeCommandSkill(outputDir, name, s); err != nil { + return fmt.Errorf("writing skill for %s: %w", name, err) + } + fmt.Fprintf(os.Stderr, " wrote glean-%s/SKILL.md\n", name) + } + + fmt.Fprintf(os.Stderr, "\nDone. Skills written to %s/\n", outputDir) + return nil +} + +func writeSharedSkill(outputDir string, commands []CommandEntry) error { + dir := filepath.Join(outputDir, "glean-shared") + if err := os.MkdirAll(dir, 0o755); err != nil { + return err + } + f, err := os.Create(filepath.Join(dir, "SKILL.md")) + if err != nil { + return err + } + defer f.Close() + + data := struct { + Commands []CommandEntry + }{Commands: commands} + return sharedTmpl.Execute(f, data) +} + +func writeCommandSkill(outputDir, name string, s schema.CommandSchema) error { + dir := filepath.Join(outputDir, "glean-"+name) + if err := os.MkdirAll(dir, 0o755); err != nil { + return err + } + f, err := os.Create(filepath.Join(dir, "SKILL.md")) + if err != nil { + return err + } + defer f.Close() + + data := buildSkillData(name, s) + return skillTmpl.Execute(f, data) +} + +func buildSkillData(name string, s schema.CommandSchema) SkillData { + desc := skillDescription[name] + if desc == "" { + desc = s.Description + } + + // Build flags + var flags []FlagInfo + for flagName, fs := range s.Flags { + def := "" + if fs.Default != nil { + def = fmt.Sprintf("%v", fs.Default) + } + typ := fs.Type + if len(fs.Enum) > 0 { + typ = strings.Join(fs.Enum, " \\| ") + } + flags = append(flags, FlagInfo{ + Name: flagName, + Type: typ, + Default: def, + Description: fs.Description, + Required: fs.Required, + }) + } + sort.Slice(flags, func(i, j int) bool { + return flags[i].Name < flags[j].Name + }) + + // Build subcommands from the subcommandMap + var subs []SubcommandInfo + for key, sdesc := range subcommandMap { + parts := strings.SplitN(key, ".", 2) + if parts[0] == name { + subs = append(subs, SubcommandInfo{Name: parts[1], Description: sdesc}) + } + } + sort.Slice(subs, func(i, j int) bool { + return subs[i].Name < subs[j].Name + }) + + hasDryRun := false + for _, fl := range flags { + if fl.Name == "--dry-run" { + hasDryRun = true + break + } + } + + return SkillData{ + Name: "glean-" + name, + Description: desc, + Command: name, + SchemaDesc: s.Description, + Flags: flags, + Subcommands: subs, + Example: s.Example, + HasDryRun: hasDryRun, + } +} diff --git a/skills/CONTEXT.md b/skills/CONTEXT.md deleted file mode 100644 index 7f9f9d3..0000000 --- a/skills/CONTEXT.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -name: glean-cli-context -description: CLI-wide guidance for using the glean command-line tool as an AI agent ---- - -# Glean CLI — Agent Context - -`glean` is a CLI for searching and interacting with Glean's company knowledge platform. - -## Key Principles - -1. **Schema-first**: Always call `glean schema ` before invoking a command to understand - current parameter types, required fields, and output format. Never guess at flag names. - -2. **JSON-in, JSON-out**: All commands accept `--json ` to pass a complete request body. - All commands output JSON by default — pipe to `jq` for filtering. - -3. **Dry-run before write**: Use `--dry-run` on create/update/delete operations to inspect the - request body before sending. - -4. **Ctrl+C-safe**: All commands respect context cancellation. Long-running operations can be - interrupted. - -## Authentication - -Three credential sources (priority order): -1. `GLEAN_API_TOKEN` + `GLEAN_HOST` env vars (preferred for CI/scripting) -2. OAuth token via `glean auth login` -3. `~/.glean/config.json` - -```bash -# CI/scripting (no interactive setup needed) -GLEAN_API_TOKEN=mytoken GLEAN_HOST=mycompany-be.glean.com glean search "test" -``` - -## Quick Start - -```bash -# Discover available commands and their schemas -glean schema -glean schema search - -# Search company knowledge -glean search "vacation policy" | jq '.results[0].title' -glean search --json '{"query":"Q1 reports","pageSize":5}' | jq '.results[].title' - -# Chat with Glean AI -glean chat "What are our engineering principles?" -``` - -## Output Formats - -- `--output json` (default): single JSON object, pipe-safe -- `--output ndjson`: one JSON line per result, good for streaming pipelines -- `--output text`: human-readable (avoid in agent pipelines) -- `--fields a,b.c`: project only specific dot-path fields - -## Error Handling - -All errors are written to stderr; stdout only contains structured output. -Exit code 0 = success, non-zero = error. diff --git a/skills/chat.md b/skills/chat.md deleted file mode 100644 index 7531562..0000000 --- a/skills/chat.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -command: chat -description: Have a conversation with Glean AI -required_flags: - - message (positional arg) OR --json -output_format: text (streaming response) ---- - -# glean chat - -Ask Glean AI a question. The response is streamed with stage indicators for searching and reading. - -## Basic Usage - -```bash -# Simple question -glean chat "What are the engineering principles?" - -# Full JSON payload (for multi-turn or custom agent config) -glean chat --json '{ - "messages": [ - {"author": "USER", "messageType": "CONTENT", "fragments": [{"text": "What is Glean?"}]} - ], - "agentConfig": {"agent": "DEFAULT", "mode": "DEFAULT"} -}' - -# See what would be sent without sending -glean chat --dry-run "test question" -``` - -## Non-Interactive Usage - -For scripting, `glean chat` streams text to stdout. Capture it with: - -```bash -# Capture response (blocks until complete) -ANSWER=$(glean chat "What is the vacation policy?" 2>/dev/null) -``` - -## Request Schema (components.ChatRequest) - -```json -{ - "messages": [ - { - "author": "USER", - "messageType": "CONTENT", - "fragments": [{"text": "your question here"}] - } - ], - "agentConfig": { - "agent": "DEFAULT", - "mode": "DEFAULT" - }, - "saveChat": true, - "timeoutMillis": 30000, - "stream": true -} -``` - -## Pitfalls - -- Output includes stage markers (✓ Searching:, ✓ Reading:) in text mode -- For machine-parseable output, use the MCP server (`glean mcp`) instead -- `--timeout` is the API timeout, not a local timeout diff --git a/skills/glean-activity/SKILL.md b/skills/glean-activity/SKILL.md new file mode 100644 index 0000000..31b59bb --- /dev/null +++ b/skills/glean-activity/SKILL.md @@ -0,0 +1,44 @@ +--- +name: glean-activity +description: "Report user activity and submit feedback to Glean. Use when logging user interactions or providing relevance feedback on search results." +--- + +# glean activity + +> **PREREQUISITE:** Read `../glean-shared/SKILL.md` for auth, global flags, and security rules. + +Report user activity and feedback. Subcommands: report, feedback. + +```bash +glean activity [flags] +``` + +## Subcommands + +| Subcommand | Description | +|------------|-------------| +| `feedback` | Submit feedback on search results | +| `report` | Report a user activity event | + +## Flags + +| Flag | Type | Default | Description | +|------|------|---------|-------------| +| `--dry-run` | boolean | false | | +| `--json` | string | | JSON request body (required) **(required)** | + +## Examples + +```bash +glean activity report --json '{"events":[{"action":"VIEW","url":"https://example.com"}]}' +``` + +## Discovering Commands + +```bash +# Show machine-readable schema for this command +glean schema activity + +# List all available commands +glean schema | jq '.commands' +``` diff --git a/skills/glean-agents/SKILL.md b/skills/glean-agents/SKILL.md new file mode 100644 index 0000000..79e1bb2 --- /dev/null +++ b/skills/glean-agents/SKILL.md @@ -0,0 +1,48 @@ +--- +name: glean-agents +description: "List, inspect, and run Glean AI agents. Use when discovering available agents, viewing agent schemas, or invoking agents programmatically." +--- + +# glean agents + +> **PREREQUISITE:** Read `../glean-shared/SKILL.md` for auth, global flags, and security rules. + +Manage and run Glean agents. Subcommands: list, get, schemas, run. + +```bash +glean agents [flags] +``` + +## Subcommands + +| Subcommand | Description | +|------------|-------------| +| `get` | Get details of a specific agent | +| `list` | List all available agents | +| `run` | Run an agent | +| `schemas` | Get input/output schemas for an agent | + +## Flags + +| Flag | Type | Default | Description | +|------|------|---------|-------------| +| `--dry-run` | boolean | false | | +| `--json` | string | | JSON request body | +| `--output` | json \| ndjson \| text | json | | + +## Examples + +```bash +glean agents list | jq '.[].id' +glean agents run --json '{"agentId":"my-agent","input":{"query":"test"}}' +``` + +## Discovering Commands + +```bash +# Show machine-readable schema for this command +glean schema agents + +# List all available commands +glean schema | jq '.commands' +``` diff --git a/skills/glean-announcements/SKILL.md b/skills/glean-announcements/SKILL.md new file mode 100644 index 0000000..7fbc2ee --- /dev/null +++ b/skills/glean-announcements/SKILL.md @@ -0,0 +1,46 @@ +--- +name: glean-announcements +description: "Manage time-bounded company announcements in Glean. Use when creating, updating, or deleting announcements that surface across the Glean UI." +--- + +# glean announcements + +> **PREREQUISITE:** Read `../glean-shared/SKILL.md` for auth, global flags, and security rules. + +Manage Glean announcements. Subcommands: create, update, delete. + +```bash +glean announcements [flags] +``` + +## Subcommands + +| Subcommand | Description | +|------------|-------------| +| `create` | Create a new announcement | +| `delete` | Delete an announcement | +| `update` | Update an existing announcement | + +## Flags + +| Flag | Type | Default | Description | +|------|------|---------|-------------| +| `--dry-run` | boolean | false | | +| `--json` | string | | JSON request body (required) **(required)** | +| `--output` | json \| ndjson \| text | json | | + +## Examples + +```bash +glean announcements create --json '{"title":"Company Update","body":"..."}' +``` + +## Discovering Commands + +```bash +# Show machine-readable schema for this command +glean schema announcements + +# List all available commands +glean schema | jq '.commands' +``` diff --git a/skills/glean-answers/SKILL.md b/skills/glean-answers/SKILL.md new file mode 100644 index 0000000..eaee218 --- /dev/null +++ b/skills/glean-answers/SKILL.md @@ -0,0 +1,48 @@ +--- +name: glean-answers +description: "Manage curated Q&A pairs in Glean. Use when creating, updating, or listing company-approved answers to common questions." +--- + +# glean answers + +> **PREREQUISITE:** Read `../glean-shared/SKILL.md` for auth, global flags, and security rules. + +Manage Glean answers. Subcommands: list, get, create, update, delete. + +```bash +glean answers [flags] +``` + +## Subcommands + +| Subcommand | Description | +|------------|-------------| +| `create` | Create a new answer | +| `delete` | Delete an answer | +| `get` | Get a specific answer | +| `list` | List all curated answers | +| `update` | Update an existing answer | + +## Flags + +| Flag | Type | Default | Description | +|------|------|---------|-------------| +| `--dry-run` | boolean | false | | +| `--json` | string | | JSON request body | +| `--output` | json \| ndjson \| text | json | | + +## Examples + +```bash +glean answers list | jq '.[].id' +``` + +## Discovering Commands + +```bash +# Show machine-readable schema for this command +glean schema answers + +# List all available commands +glean schema | jq '.commands' +``` diff --git a/skills/glean-api/SKILL.md b/skills/glean-api/SKILL.md new file mode 100644 index 0000000..bd542c7 --- /dev/null +++ b/skills/glean-api/SKILL.md @@ -0,0 +1,42 @@ +--- +name: glean-api +description: "Make raw authenticated HTTP requests to any Glean REST API endpoint. Use when no dedicated command exists or for advanced API access." +--- + +# glean api + +> **PREREQUISITE:** Read `../glean-shared/SKILL.md` for auth, global flags, and security rules. + +Make a raw authenticated HTTP request to any Glean REST API endpoint. + +```bash +glean api [flags] +``` + +## Flags + +| Flag | Type | Default | Description | +|------|------|---------|-------------| +| `--dry-run` | boolean | false | Same as --preview | +| `--input` | string | | Path to a JSON file to use as request body | +| `--method` | GET \| POST \| PUT \| DELETE \| PATCH | GET | HTTP method | +| `--no-color` | boolean | false | Disable colorized output | +| `--preview` | boolean | false | Print request details without sending | +| `--raw` | boolean | false | Print raw response without syntax highlighting | +| `--raw-field` | string | | JSON request body as a string | + +## Examples + +```bash +glean api search --method POST --raw-field '{"query":"test"}' --no-color | jq .results +``` + +## Discovering Commands + +```bash +# Show machine-readable schema for this command +glean schema api + +# List all available commands +glean schema | jq '.commands' +``` diff --git a/skills/glean-chat/SKILL.md b/skills/glean-chat/SKILL.md new file mode 100644 index 0000000..751d768 --- /dev/null +++ b/skills/glean-chat/SKILL.md @@ -0,0 +1,41 @@ +--- +name: glean-chat +description: "Chat with Glean Assistant from the command line. Use when asking questions, summarizing documents, or getting AI-powered answers about company knowledge." +--- + +# glean chat + +> **PREREQUISITE:** Read `../glean-shared/SKILL.md` for auth, global flags, and security rules. + +Have a conversation with Glean AI. Streams response to stdout. + +```bash +glean chat [flags] +``` + +## Flags + +| Flag | Type | Default | Description | +|------|------|---------|-------------| +| `--dry-run` | boolean | false | Print request body without sending | +| `--json` | string | | Complete JSON chat request body (overrides individual flags) | +| `--message` | string | | Chat message (positional arg) **(required)** | +| `--save` | boolean | true | Save the chat session | +| `--timeout` | integer | 30000 | Request timeout in milliseconds | + +## Examples + +```bash +glean chat "What are the company holidays?" +glean chat --json '{"messages":[{"author":"USER","messageType":"CONTENT","fragments":[{"text":"What is Glean?"}]}]}' +``` + +## Discovering Commands + +```bash +# Show machine-readable schema for this command +glean schema chat + +# List all available commands +glean schema | jq '.commands' +``` diff --git a/skills/glean-collections/SKILL.md b/skills/glean-collections/SKILL.md new file mode 100644 index 0000000..8ade6f6 --- /dev/null +++ b/skills/glean-collections/SKILL.md @@ -0,0 +1,50 @@ +--- +name: glean-collections +description: "Manage curated document collections in Glean. Use when creating, updating, or organizing themed sets of documents." +--- + +# glean collections + +> **PREREQUISITE:** Read `../glean-shared/SKILL.md` for auth, global flags, and security rules. + +Manage Glean collections. Subcommands: create, delete, update, add-items, delete-item. + +```bash +glean collections [flags] +``` + +## Subcommands + +| Subcommand | Description | +|------------|-------------| +| `add-items` | Add documents to a collection | +| `create` | Create a new collection | +| `delete` | Delete a collection | +| `delete-item` | Remove a document from a collection | +| `get` | Get a specific collection | +| `list` | List all collections | +| `update` | Update a collection | + +## Flags + +| Flag | Type | Default | Description | +|------|------|---------|-------------| +| `--dry-run` | boolean | false | | +| `--json` | string | | JSON request body | +| `--output` | json \| ndjson \| text | json | | + +## Examples + +```bash +glean collections create --json '{"name":"My Collection"}' +``` + +## Discovering Commands + +```bash +# Show machine-readable schema for this command +glean schema collections + +# List all available commands +glean schema | jq '.commands' +``` diff --git a/skills/glean-documents/SKILL.md b/skills/glean-documents/SKILL.md new file mode 100644 index 0000000..54428e2 --- /dev/null +++ b/skills/glean-documents/SKILL.md @@ -0,0 +1,47 @@ +--- +name: glean-documents +description: "Retrieve, summarize, and inspect documents indexed by Glean. Use when getting document content, summaries, permissions, or metadata by URL." +--- + +# glean documents + +> **PREREQUISITE:** Read `../glean-shared/SKILL.md` for auth, global flags, and security rules. + +Retrieve and summarize Glean documents. Subcommands: get, get-by-facets, get-permissions, summarize. + +```bash +glean documents [flags] +``` + +## Subcommands + +| Subcommand | Description | +|------------|-------------| +| `get` | Retrieve document metadata by URL or ID | +| `get-by-facets` | Retrieve documents matching facet filters | +| `get-permissions` | Inspect who has access to a document | +| `summarize` | Generate an AI summary of a document | + +## Flags + +| Flag | Type | Default | Description | +|------|------|---------|-------------| +| `--dry-run` | boolean | false | | +| `--json` | string | | JSON request body | +| `--output` | json \| ndjson \| text | json | | + +## Examples + +```bash +glean documents summarize --json '{"documentId":"DOC_ID"}' | jq .summary +``` + +## Discovering Commands + +```bash +# Show machine-readable schema for this command +glean schema documents + +# List all available commands +glean schema | jq '.commands' +``` diff --git a/skills/glean-entities/SKILL.md b/skills/glean-entities/SKILL.md new file mode 100644 index 0000000..17569cb --- /dev/null +++ b/skills/glean-entities/SKILL.md @@ -0,0 +1,44 @@ +--- +name: glean-entities +description: "Look up people, teams, and custom entities in Glean. Use when finding employees, org structure, team members, or expertise." +--- + +# glean entities + +> **PREREQUISITE:** Read `../glean-shared/SKILL.md` for auth, global flags, and security rules. + +List and read Glean entities and people. Subcommands: list, read-people. + +```bash +glean entities [flags] +``` + +## Subcommands + +| Subcommand | Description | +|------------|-------------| +| `list` | List entities by type and query | +| `read-people` | Get detailed people profiles | + +## Flags + +| Flag | Type | Default | Description | +|------|------|---------|-------------| +| `--json` | string | | JSON request body **(required)** | +| `--output` | json \| ndjson \| text | json | | + +## Examples + +```bash +glean entities read-people --json '{"query":"smith"}' | jq '.[].name' +``` + +## Discovering Commands + +```bash +# Show machine-readable schema for this command +glean schema entities + +# List all available commands +glean schema | jq '.commands' +``` diff --git a/skills/glean-insights/SKILL.md b/skills/glean-insights/SKILL.md new file mode 100644 index 0000000..9c230e0 --- /dev/null +++ b/skills/glean-insights/SKILL.md @@ -0,0 +1,44 @@ +--- +name: glean-insights +description: "Retrieve search and usage analytics from Glean. Use when analyzing search patterns, popular queries, or platform adoption metrics." +--- + +# glean insights + +> **PREREQUISITE:** Read `../glean-shared/SKILL.md` for auth, global flags, and security rules. + +Retrieve Glean usage insights. Subcommands: get. + +```bash +glean insights [flags] +``` + +## Subcommands + +| Subcommand | Description | +|------------|-------------| +| `get` | Get analytics data | + +## Flags + +| Flag | Type | Default | Description | +|------|------|---------|-------------| +| `--dry-run` | boolean | false | | +| `--json` | string | | JSON request body (required) **(required)** | +| `--output` | json \| ndjson \| text | json | | + +## Examples + +```bash +glean insights get --json '{"insightTypes":["SEARCH"]}' | jq . +``` + +## Discovering Commands + +```bash +# Show machine-readable schema for this command +glean schema insights + +# List all available commands +glean schema | jq '.commands' +``` diff --git a/skills/glean-messages/SKILL.md b/skills/glean-messages/SKILL.md new file mode 100644 index 0000000..6831a4a --- /dev/null +++ b/skills/glean-messages/SKILL.md @@ -0,0 +1,43 @@ +--- +name: glean-messages +description: "Retrieve indexed messages from Slack, Teams, and other messaging platforms via Glean. Use when searching for or reading specific messages." +--- + +# glean messages + +> **PREREQUISITE:** Read `../glean-shared/SKILL.md` for auth, global flags, and security rules. + +Retrieve Glean messages. Subcommands: get. + +```bash +glean messages [flags] +``` + +## Subcommands + +| Subcommand | Description | +|------------|-------------| +| `get` | Retrieve a specific message | + +## Flags + +| Flag | Type | Default | Description | +|------|------|---------|-------------| +| `--json` | string | | JSON request body (required) **(required)** | +| `--output` | json \| ndjson \| text | json | | + +## Examples + +```bash +glean messages get --json '{"messageId":"MSG_ID"}' | jq . +``` + +## Discovering Commands + +```bash +# Show machine-readable schema for this command +glean schema messages + +# List all available commands +glean schema | jq '.commands' +``` diff --git a/skills/glean-pins/SKILL.md b/skills/glean-pins/SKILL.md new file mode 100644 index 0000000..7215f1e --- /dev/null +++ b/skills/glean-pins/SKILL.md @@ -0,0 +1,48 @@ +--- +name: glean-pins +description: "Manage promoted search results (pins) in Glean. Use when pinning specific documents to appear first for certain queries." +--- + +# glean pins + +> **PREREQUISITE:** Read `../glean-shared/SKILL.md` for auth, global flags, and security rules. + +Manage Glean pins. Subcommands: list, get, create, update, remove. + +```bash +glean pins [flags] +``` + +## Subcommands + +| Subcommand | Description | +|------------|-------------| +| `create` | Create a new pin | +| `get` | Get a specific pin | +| `list` | List all pins | +| `remove` | Remove a pin | +| `update` | Update a pin | + +## Flags + +| Flag | Type | Default | Description | +|------|------|---------|-------------| +| `--dry-run` | boolean | false | | +| `--json` | string | | JSON request body | +| `--output` | json \| ndjson \| text | json | | + +## Examples + +```bash +glean pins list | jq '.[].id' +``` + +## Discovering Commands + +```bash +# Show machine-readable schema for this command +glean schema pins + +# List all available commands +glean schema | jq '.commands' +``` diff --git a/skills/glean-search/SKILL.md b/skills/glean-search/SKILL.md new file mode 100644 index 0000000..69bcbd6 --- /dev/null +++ b/skills/glean-search/SKILL.md @@ -0,0 +1,53 @@ +--- +name: glean-search +description: "Search across company knowledge with the Glean CLI. Use when finding documents, policies, engineering docs, or any information across enterprise data sources." +--- + +# glean search + +> **PREREQUISITE:** Read `../glean-shared/SKILL.md` for auth, global flags, and security rules. + +Search for content in your Glean instance. Results are JSON. + +```bash +glean search [flags] +``` + +## Flags + +| Flag | Type | Default | Description | +|------|------|---------|-------------| +| `--datasource` | []string | | Filter by datasource (repeatable) | +| `--disable-query-autocorrect` | boolean | false | Disable automatic query corrections | +| `--disable-spellcheck` | boolean | false | Disable spellcheck | +| `--dry-run` | boolean | false | Print request body without sending | +| `--facet-bucket-size` | integer | 10 | Maximum facet buckets per result | +| `--fetch-all-datasource-counts` | boolean | false | Return counts for all datasources | +| `--json` | string | | Complete JSON request body (overrides individual flags) | +| `--max-snippet-size` | integer | 0 | Maximum snippet size in characters | +| `--output` | json \| ndjson \| text | json | Output format | +| `--page-size` | integer | 10 | Number of results per page | +| `--query` | string | | Search query (positional arg) **(required)** | +| `--query-overrides-facet-filters` | boolean | false | Allow query operators to override facet filters | +| `--response-hints` | []string | [RESULTS QUERY_METADATA] | Response hints | +| `--return-llm-content` | boolean | false | Return expanded LLM-friendly content | +| `--tab` | []string | | Filter by result tab IDs (repeatable) | +| `--timeout` | integer | 30000 | Request timeout in milliseconds | +| `--type` | []string | | Filter by document type (repeatable) | + +## Examples + +```bash +glean search "vacation policy" | jq '.results[].document.title' +glean search --json '{"query":"Q1 reports","pageSize":5,"datasources":["confluence"]}' | jq . +``` + +## Discovering Commands + +```bash +# Show machine-readable schema for this command +glean schema search + +# List all available commands +glean schema | jq '.commands' +``` diff --git a/skills/glean-shared/SKILL.md b/skills/glean-shared/SKILL.md new file mode 100644 index 0000000..d6e76c0 --- /dev/null +++ b/skills/glean-shared/SKILL.md @@ -0,0 +1,88 @@ +--- +name: glean-shared +description: "Glean CLI: Shared patterns for authentication, global flags, output formatting, and security rules." +compatibility: Requires the glean binary on $PATH. Install via brew install gleanwork/tap/glean-cli +--- + +# glean — Shared Reference + +> **Read this first.** All other glean skills assume familiarity with auth, flags, and output formats described here. + +## Installation + +```bash +brew install gleanwork/tap/glean-cli +``` + +## Authentication + +```bash +# Browser-based OAuth (interactive — recommended) +glean auth login + +# Verify credentials +glean auth status + +# CI/scripting (no interactive setup needed) +export GLEAN_API_TOKEN=your-token +export GLEAN_HOST=your-company-be.glean.com +``` + +Credentials resolve in this order: environment variables → system keyring → ~/.glean/config.json. + +## CLI Syntax + +```bash +glean [subcommand] [flags] +``` + +### Global Flags + +| Flag | Description | +|------|-------------| +| --output | json (default), ndjson (one result per line), text | +| --fields | Dot-path field projection (e.g. results.document.title,results.document.url) | +| --json | Complete JSON request body (overrides all other flags) | +| --dry-run | Print request body without sending | + +## Schema Introspection + +Always call glean schema before invoking a command you haven't used before. + +```bash +glean schema | jq '.commands' # list all commands +glean schema search | jq '.flags' # flags for search +``` + +## Security Rules + +- **Never** output API tokens or secrets directly +- **Always** use --dry-run before write/delete operations in automated pipelines +- Prefer environment variables over config files for CI/CD + +## Error Handling + +All errors go to stderr; stdout contains only structured output. +Exit code 0 = success, non-zero = error. + +## Available Commands + +| Command | Description | +|---------|-------------| +| [glean activity](../glean-activity/SKILL.md) | Report user activity and feedback. Subcommands: report, feedback. | +| [glean agents](../glean-agents/SKILL.md) | Manage and run Glean agents. Subcommands: list, get, schemas, run. | +| [glean announcements](../glean-announcements/SKILL.md) | Manage Glean announcements. Subcommands: create, update, delete. | +| [glean answers](../glean-answers/SKILL.md) | Manage Glean answers. Subcommands: list, get, create, update, delete. | +| [glean api](../glean-api/SKILL.md) | Make a raw authenticated HTTP request to any Glean REST API endpoint. | +| [glean chat](../glean-chat/SKILL.md) | Have a conversation with Glean AI. Streams response to stdout. | +| [glean collections](../glean-collections/SKILL.md) | Manage Glean collections. Subcommands: create, delete, update, add-items, delete-item. | +| [glean documents](../glean-documents/SKILL.md) | Retrieve and summarize Glean documents. Subcommands: get, get-by-facets, get-permissions, summarize. | +| [glean entities](../glean-entities/SKILL.md) | List and read Glean entities and people. Subcommands: list, read-people. | +| [glean insights](../glean-insights/SKILL.md) | Retrieve Glean usage insights. Subcommands: get. | +| [glean messages](../glean-messages/SKILL.md) | Retrieve Glean messages. Subcommands: get. | +| [glean pins](../glean-pins/SKILL.md) | Manage Glean pins. Subcommands: list, get, create, update, remove. | +| [glean search](../glean-search/SKILL.md) | Search for content in your Glean instance. Results are JSON. | +| [glean shortcuts](../glean-shortcuts/SKILL.md) | Manage Glean shortcuts (go-links). Subcommands: list, get, create, update, delete. | +| [glean tools](../glean-tools/SKILL.md) | List and run Glean tools. Subcommands: list, run. | +| [glean verification](../glean-verification/SKILL.md) | Manage document verification. Subcommands: list, verify, remind. | + diff --git a/skills/glean-shortcuts/SKILL.md b/skills/glean-shortcuts/SKILL.md new file mode 100644 index 0000000..e096943 --- /dev/null +++ b/skills/glean-shortcuts/SKILL.md @@ -0,0 +1,49 @@ +--- +name: glean-shortcuts +description: "Manage Glean go-links (shortcuts). Use when creating, listing, updating, or deleting short URL aliases like go/wiki." +--- + +# glean shortcuts + +> **PREREQUISITE:** Read `../glean-shared/SKILL.md` for auth, global flags, and security rules. + +Manage Glean shortcuts (go-links). Subcommands: list, get, create, update, delete. + +```bash +glean shortcuts [flags] +``` + +## Subcommands + +| Subcommand | Description | +|------------|-------------| +| `create` | Create a new shortcut | +| `delete` | Delete a shortcut | +| `get` | Get a specific shortcut | +| `list` | List all shortcuts | +| `update` | Update an existing shortcut | + +## Flags + +| Flag | Type | Default | Description | +|------|------|---------|-------------| +| `--dry-run` | boolean | false | Print request without sending | +| `--json` | string | | JSON request body (see Glean API docs for shape) | +| `--output` | json \| ndjson \| text | json | | + +## Examples + +```bash +glean shortcuts list | jq '.results[].inputAlias' +glean shortcuts create --json '{"data":{"inputAlias":"test/link","destinationUrl":"https://example.com"}}' +``` + +## Discovering Commands + +```bash +# Show machine-readable schema for this command +glean schema shortcuts + +# List all available commands +glean schema | jq '.commands' +``` diff --git a/skills/glean-tools/SKILL.md b/skills/glean-tools/SKILL.md new file mode 100644 index 0000000..a6bb5b4 --- /dev/null +++ b/skills/glean-tools/SKILL.md @@ -0,0 +1,45 @@ +--- +name: glean-tools +description: "List and run Glean platform tools. Use when discovering available platform tools or executing them programmatically." +--- + +# glean tools + +> **PREREQUISITE:** Read `../glean-shared/SKILL.md` for auth, global flags, and security rules. + +List and run Glean tools. Subcommands: list, run. + +```bash +glean tools [flags] +``` + +## Subcommands + +| Subcommand | Description | +|------------|-------------| +| `list` | List available platform tools | +| `run` | Execute a platform tool | + +## Flags + +| Flag | Type | Default | Description | +|------|------|---------|-------------| +| `--dry-run` | boolean | false | | +| `--json` | string | | JSON request body | +| `--output` | json \| ndjson \| text | json | | + +## Examples + +```bash +glean tools list | jq '.[].name' +``` + +## Discovering Commands + +```bash +# Show machine-readable schema for this command +glean schema tools + +# List all available commands +glean schema | jq '.commands' +``` diff --git a/skills/glean-verification/SKILL.md b/skills/glean-verification/SKILL.md new file mode 100644 index 0000000..a4dc0b4 --- /dev/null +++ b/skills/glean-verification/SKILL.md @@ -0,0 +1,46 @@ +--- +name: glean-verification +description: "Manage document verification and review workflows in Glean. Use when verifying document accuracy, listing pending verifications, or sending review reminders." +--- + +# glean verification + +> **PREREQUISITE:** Read `../glean-shared/SKILL.md` for auth, global flags, and security rules. + +Manage document verification. Subcommands: list, verify, remind. + +```bash +glean verification [flags] +``` + +## Subcommands + +| Subcommand | Description | +|------------|-------------| +| `list` | List documents pending verification | +| `remind` | Send a verification reminder | +| `verify` | Mark a document as verified | + +## Flags + +| Flag | Type | Default | Description | +|------|------|---------|-------------| +| `--dry-run` | boolean | false | | +| `--json` | string | | JSON request body | +| `--output` | json \| ndjson \| text | json | | + +## Examples + +```bash +glean verification list | jq '.[].document.title' +``` + +## Discovering Commands + +```bash +# Show machine-readable schema for this command +glean schema verification + +# List all available commands +glean schema | jq '.commands' +``` diff --git a/skills/schema.md b/skills/schema.md deleted file mode 100644 index b57bbd9..0000000 --- a/skills/schema.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -command: schema -description: Runtime JSON schema introspection for any glean command -required_flags: none -output_format: json ---- - -# glean schema - -Machine-readable schema for any glean command. Call this before invoking a command to understand -parameter types, required fields, defaults, and example invocations. - -## Usage - -```bash -# List all commands with registered schemas -glean schema | jq .commands - -# Get full schema for a command -glean schema search | jq .flags -glean schema chat | jq .example -glean schema shortcuts | jq .description -``` - -## Output Shape - -```json -{ - "command": "search", - "description": "...", - "flags": { - "--query": {"type": "string", "required": true, "description": "..."}, - "--page-size": {"type": "integer", "default": 10, "description": "..."}, - "--json": {"type": "string", "description": "Complete JSON request body"}, - "--output": {"type": "enum", "values": ["json", "ndjson", "text"], "default": "json"}, - "--dry-run": {"type": "boolean", "default": false} - }, - "example": "glean search \"vacation policy\" | jq ..." -} -``` - -## Best Practice for Agents - -Always call `glean schema ` at the start of a session to understand current parameter -types. This eliminates guessing and works without documentation in context. diff --git a/skills/search.md b/skills/search.md deleted file mode 100644 index d08082b..0000000 --- a/skills/search.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -command: search -description: Search Glean company knowledge -required_flags: - - query (positional arg) OR --json -output_format: json (default) | ndjson | text ---- - -# glean search - -Search company knowledge indexed by Glean. Results include documents, snippets, and metadata. - -## Basic Usage - -```bash -# Simple query (JSON output by default) -glean search "vacation policy" | jq '.results[0].document.title' - -# Extract specific fields -glean search "Q1 reports" --fields "results.document.title,results.document.url" - -# NDJSON — one result per line -glean search "engineering docs" --output ndjson | head -3 | jq .document.title - -# Filter by datasource -glean search "deploy guide" --datasource confluence - -# Full JSON payload (overrides all flags) -glean search --json '{"query":"Q1 reports","pageSize":5,"datasources":["confluence","gdrive"]}' -``` - -## Dry Run - -```bash -# See what request would be sent -glean search --dry-run "test query" -``` - -## Request Schema (components.SearchRequest) - -```json -{ - "query": "string (required)", - "pageSize": 10, - "maxSnippetSize": 0, - "timeoutMillis": 30000, - "disableSpellcheck": false, - "requestOptions": { - "facetFilters": [{"fieldName": "datasource", "values": [{"value": "confluence", "relationType": "EQUALS"}]}], - "responseHints": ["RESULTS", "QUERY_METADATA"], - "facetBucketSize": 10, - "timezoneOffset": 0 - } -} -``` - -## Common Patterns - -```bash -# Search and extract document titles -glean search "vacation policy" | jq '[.results[].document.title]' - -# Search with datasource filter via flag -glean search "deploy guide" -d confluence | jq '.results | length' - -# Search and get URLs only -glean search "engineering handbook" | jq '[.results[].document.url]' -``` - -## Pitfalls - -- Results may be empty if the token doesn't have access to the datasource -- `pageSize` is a hint — the server may return more or fewer results -- Use `--fields` to limit output size when results are large diff --git a/skills/shortcuts.md b/skills/shortcuts.md deleted file mode 100644 index f9e2c06..0000000 --- a/skills/shortcuts.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -command: shortcuts -description: Manage Glean shortcuts (go-links) -required_flags: --json for create/update/delete -output_format: json (default) | ndjson | text ---- - -# glean shortcuts - -Manage Glean go-links (shortcuts). These are short aliases like `go/wiki` that redirect to URLs. - -## Usage - -```bash -# List all shortcuts -glean shortcuts list | jq '.results[].inputAlias' - -# Create a shortcut -glean shortcuts create --json '{ - "data": { - "inputAlias": "team/eng", - "destinationUrl": "https://wiki.company.com/engineering" - } -}' - -# Dry-run a create -glean shortcuts create --dry-run --json '{ - "data": {"inputAlias": "test/link", "destinationUrl": "https://example.com"} -}' - -# Delete a shortcut -glean shortcuts delete --json '{"id": 12345}' -``` - -## Request Shapes - -### Create: components.CreateShortcutRequest -```json -{ - "data": { - "inputAlias": "team/link", - "destinationUrl": "https://...", - "description": "Optional description", - "unlisted": false - } -} -``` - -### Delete: components.DeleteShortcutRequest -```json -{"id": 12345} -``` - -## Pitfalls - -- The `create` payload uses a `data` wrapper (`{"data": {...}}`), NOT a flat object -- `inputAlias` is the `go/` part after the prefix (e.g. `team/wiki` for `go/team/wiki`) From 9d3defac5d0f546b0b7ffba15d85e40fcc93346e Mon Sep 17 00:00:00 2001 From: Steve Calvert Date: Fri, 20 Mar 2026 08:24:18 -0700 Subject: [PATCH 2/2] fix: detect untracked skill files in CI change check git diff --quiet only sees modifications to tracked files. New skills (from new commands) would be untracked and silently ignored. Add git status --porcelain check to catch both cases. Co-Authored-By: Claude Opus 4.6 (1M context) --- .github/workflows/generate-skills.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/generate-skills.yml b/.github/workflows/generate-skills.yml index 4ed8be7..2c00f0c 100644 --- a/.github/workflows/generate-skills.yml +++ b/.github/workflows/generate-skills.yml @@ -39,7 +39,7 @@ jobs: - name: Check for changes id: diff run: | - if git diff --quiet skills/; then + if git diff --quiet skills/ && [ -z "$(git status --porcelain skills/)" ]; then echo "changed=false" >> "$GITHUB_OUTPUT" else echo "changed=true" >> "$GITHUB_OUTPUT"