AGENT SKILL

ghl-knowledge-base

Build and manage GoHighLevel knowledge bases — the content that feeds both Conversation AI and Voice AI. Covers rich-text documents, FAQs, web crawling, files, tables, Google Drive/Sheets and Internal Data (products) sources, plus the trigger conditions that tell an agent WHEN to use each knowledge base. Use when the user says 'add a knowledge base', 'train the bot on this', 'the AI isn't using my KB', 'add FAQs', 'crawl my website', 'upload docs for the agent', or asks why an agent answers from the wrong source. Internal API — six of the nine source types have no public equivalent.

License 许可
MIT
最近更新
2026-11-13
Stars
★ 12
Forks
5

01 前言 Front Matter

name
ghl-knowledge-base
description
Build and manage GoHighLevel knowledge bases — the content that feeds both Conversation AI and Voice AI. Covers rich-text documents, FAQs, web crawling, files, tables, Google Drive/Sheets and Internal Data (products) sources, plus the trigger conditions that tell an agent WHEN to use each knowledge base. Use when the user says 'add a knowledge base', 'train the bot on this', 'the AI isn't using my KB', 'add FAQs', 'crawl my website', 'upload docs for the agent', or asks why an agent answers from the wrong source. Internal API — six of the nine source types have no public equivalent.

03 SKILL.md 正文

GHL Knowledge Base

The shared content layer. Both Voice AI (knowledgeBaseIds) and Conversation AI (knowledgeBaseIds + knowledgeBaseTriggers) point at the same knowledge bases, so a change here affects every agent attached to it. Check GET /knowledge-base/associated-entities before editing one.

Base: services.leadconnectorhq.com/knowledge-base.

Why this is an internal-rail skill

Nine source types exist in the enum; the UI offers five tabs (Web crawler · FAQ · Tables · Rich text · Files, with Google Drive/Sheets and Internal Data behind flags). Web search has no screen at build 683 (hard-coded off). The public API documents FAQs, the crawler, files and the knowledge-base record itself (the public file upload is documented, not yet proven live). Five source types have no public equivalent, and web_search has neither a screen nor a public operation:

faq  ·  web_crawler  ·  file                                        ← public reaches these too
rich_text  ·  table  ·  google_drive  ·  google_sheet  ·  internal_data   ← internal only
web_search                                                          ← no screen, no public op

rich_text is the one that matters most in practice: it is how you give an agent authored prose rather than scraped pages, and there is no way to create one through the public API.

Which rail, per job

The singular internal /knowledge-base/* paths still answer after GHL's 2026-08-18 rename; on the sandbox they returned the same knowledge bases as the public plural /knowledge-bases (2026-10-29).

<!-- rail-ledger:knowledge-base --> generated from the rail ledger (mcp-internal/catalog/rail-ledger.json) — do not edit; the whole ledger is ghl-orientation/references/rail-ledger.md.

Job Decision Routed today Internal Public
read both internal raw_request:GET /knowledge-base/all, raw_request:GET /knowledge-base/{knowledgeBaseId} knowledge-base-v3__listAllKnowledgeBasesPaginated, knowledge-base-v3__getKnowledgeBaseById
create undecided internal raw_request:POST /knowledge-base/ knowledge-base-v3__createKnowledgeBase, knowledge-base-v3__create
edit undecided internal raw_request:PUT /knowledge-base/{knowledgeBaseId} knowledge-base-v3__updateKnowledgeBase, knowledge-base-v3__update
delete undecided internal raw_request:DELETE /knowledge-base/{knowledgeBaseId} knowledge-base-v3__deleteKnowledgeBase, knowledge-base-v3__delete
  • read: The internal rail reaches source types the public one lacks; whether its singular paths still answer after the rename is unverified.
  • create: The internal rail reaches source types the public one lacks; whether its singular paths still answer after the rename is unverified.
  • edit: The internal rail reaches source types the public one lacks; whether its singular paths still answer after the rename is unverified.
  • delete: The internal rail reaches source types the public one lacks; whether its singular paths still answer after the rename is unverified.

Internal only: rich_text, table, google and internal_data sources; gaps. Public only: FAQs; crawler sitemap preview; files. <!-- /rail-ledger:knowledge-base -->

The endpoints

All 25 are in the endpoint catalogue — search_endpoints, then describe_endpoint. The corpus page ai-agents/20-api/knowledge-base.md carries the source-type enum, the analytics vocabulary that reveals the per-plan caps, and the training routes.

The shape worth holding in your head: a knowledge base is a record with sources attached to it. POST /knowledge-base/ makes the record (body {locationId, name, description?}, name ≤ 50). Every source kind has its own sub-resource — /faqs, /rich-text/, /crawler, /files, /table/… (a multi-step upload → schema → select-columns → status pipeline), /google-sheets/*, /google-drive/*, /internal-data/*. There is no generic "attach a source" call: the POST to a bare KB id and its /bulk variant that older notes listed are the translation client's calls, not the KB's. Creation is asynchronous — poll each source's status. 15 knowledge bases per sub-account.

The record (all live-proven 2026-09-26 on a test sub-account, each read back on a separate request)

Operation Call Notes
Create POST /knowledge-base/ {locationId, name, description?} keep the trailing slash. → 201 {data:{id, name, nameLowerCase, kbMetadata{faqs, urls, richText, webSearches, files, tables, firstQueryAt, lastQueryAt, lastSourceAddedAt}}}. The editor caps the name at 50 characters and the description at 175; the server stored a 56-character name, so the name cap is client-only
Read GET /knowledge-base/{id}?locationId= carries description and the kbMetadata source counts
List GET /knowledge-base/all?locationId= → {data:{knowledgeBases[{id, name, createdAt, updatedAt}], activeCount}}. activeCount is what the editor's "Knowledge base quota n / 15" reads; the 15 is editor-side (not pushed past on the test account)
Rename / describe PUT /knowledge-base/{id} {locationId, knowledgeBaseId, name, description} → 200; the editor's header pencil opens "Edit knowledge base"
Who uses it GET /knowledge-base/associated-entities?locationId=&knowledgeBaseId= → {entities, blockingEntities, advisoryEntities, unverifiedSources, partial}; an unused KB reads all empty with partial:false
Delete DELETE /knowledge-base/{id}?locationId= → {success}; afterwards GET answers 400 "Knowledge base not found". The editor refuses while agents use it: "This knowledge base cannot be deleted … Agents using this knowledge base" lists each agent (Conversation AI / Voice AI) with Open and a Re-check button. Read associated-entities yourself before deleting through the API, which does not stop you
Default KB POST /knowledge-base/default {locationId, migrateDocs:true} → 201 {data:{id}}, the same id every time: the location's default KB. The list page fires it on every load

Read-back list of a KB's rich-text docs: GET /knowledge-base/rich-text/knowledge-base/{kbId} → {data: [{id, title, content, contentMarkdown, status, …}]}.

The traps

1. Rich-text create is asynchronous. POST /knowledge-base/rich-text/ returns before the document is usable — there is a status poll. Do not attach the KB to an agent and report success on the create response alone.

2. Opening the Knowledge Base screen writes. POST /knowledge-base/default fires on page load and returns 201. If you are replaying captured traffic, that call is expected behaviour, not something you triggered.

3. Attaching a KB is not enough — the agent needs to know WHEN to use it. On Conversation AI:

"knowledgeBaseTriggers": [
  { "mode": "all",    "knowledgeBaseIds": ["…"], "triggerCondition": "",  "priority": 2 },
  { "mode": "custom", "knowledgeBaseIds": ["…"], "triggerCondition": "<when to use this>", "priority": 1 }
]

The editor labels the text "Instructions (Optional)", and it is optional: with no text the agent decides by itself when to use the KB (mode: "all", one such trigger, ≤ 7 KBs); with text the trigger is mode: "custom" (≤ 5 KBs). The editor caps the text at 1000 characters, but the server stored 1001. The server allows at most 4 triggers ("knowledgeBaseTriggers.4.priority must not be greater than 4"). A trial chat on a bot with a KB answered from that KB (live-proven 2026-09-26). An older version of this skill said the text was required, 10–500 characters, labelled "When to use this knowledge base": that was wrong.

4. Gaps are a dated log of misses, not an inventory of what is missing now. 🔴 A row stays open after the answering content is added — proven by differential (documents added, the questions re-asked live and answered from them, the list re-read unchanged, lastAskedAt unmoved) — and a question the KB answers is never logged, so every row looks current until you read its dates. List: GET /knowledge-base/gaps?locationId=&knowledgeBaseId=&status=open (AI rail).

  1. Read the knowledge base first — content present ⇒ the row is stale; do not change the agent.
  2. Check lastAskedAt against the window you are judging.
  3. Write the knowledge to match topQueryTexts (the customer's own wording).
  4. Never filter by categories — a genuine product question was filed under Noise / Gibberish / Chitchat. The DISMISS write is PATCH /knowledge-base/gaps/{gapId}/state {locationId, state:"archived"} — live-proven 2026-09-08, reversible with state:"active". The write says active, the read says open. Fields and counts endpoint: knowledge/corpus/ai-agents/20-api/knowledge-base.md → "Gaps".

5. Editing a rich-text doc is a PUT, not delete-and-recreate. PUT /knowledge-base/rich-text/:id is a live-verified full-replace (2026-08-28, the designated test sub-account): same body shape as create — {locationId, knowledgeBaseId, title, content} — 200, response carries status: "training", and a read-back of the sent content came back byte-identical. It re-chunks and re-embeds automatically, exactly like create: poll GET /knowledge-base/rich-text/:id/status until "trained" (a full retrain took ~4.6s in the proving run) — there is no separate retrain call.

Do not delete-and-recreate a doc to edit it, and do not add a second doc alongside the old one as a workaround: both orphan or duplicate content — a delete drops any id another object references, and a second doc leaves stale content the agent can still draw from, which is a worse failure than the one you were trying to fix. PUT the existing id instead.

content is HTML; the server derives contentMarkdown from it. A direct contentMarkdown write 200s and changes nothing — measured in both a contentMarkdown-only body and an unchanged-content-plus-contentMarkdown body. kb-compiler.mjs's compileRichTextUpdate(id, doc, {locationId}) builds this PUT descriptor, and throws rather than silently no-opping if the caller's IR carries a contentMarkdown key — a caller supplying that key believes something false about this API.

6. The retrieval test needs the editor's body. POST /knowledge-base/chunks {query, knowledgeBaseIds, locationId, rerankChunks: true, threshold: 0, topK: 5, subCaller} returns up to 5 chunks with score and category (bulk = crawled page, finetuned = FAQ, rich_text, files, table). Without those parameters it returned one chunk, which looks like "the KB only knows one thing". The editor's ⌘K "Test retrieval" drawer keeps a history: POST /knowledge-base/retrieval-test/conversations/entries {locationId, knowledgeBaseId, query, agentLayer, chunks, totalChunks, latencyMs, idempotencyKey} → {conversationId, entryId, isNew, isDuplicate}; GET …/retrieval-test/conversations?locationId=&knowledgeBaseId= lists them, GET …/conversations/{id}?locationId= reads one, DELETE the same removes it (then 404 "Conversation not found").

7. The crawler judges what the CDN serves, refuses thin pages, and obeys robots.txt. Status Restricted with error: "Insufficient content (174 chars)". A page you just edited can be judged on its stale cached copy. 🔴 The crawler reads robots.txt as user agent AITrainingBot. A blocked page still gets 201 status: "Processing" on the POST, then status: "Restricted", error.code: "ROBOTS_TXT_BLOCKED", retryable: false, and no URL is stored. GHL's own app.gohighlevel.com/v2/preview/{pageId} URLs are blocked this way (proven live 2026-09-29). A 201 is not a crawl: read GET /knowledge-base/crawler/status?locationId=&knowledgeBaseId= for operationDetails.status and .error, and point the user to Rich Text when robots.txt blocks the page.

Sources — what ran live (2026-09-26 / 28)

Each was built in an own test KB, read back on separate requests, retrieved through /chunks, and deleted by exact id. Full shapes: corpus ai-agents/20-api/knowledge-base.md → "Sources executed live".

Source Create Read Remove Traps
FAQ POST /knowledge-base/faqs {locationId, knowledgeBaseId, question, answer, metadata?} → {faq{…, id}} GET /knowledge-base/faqs?locationId=&knowledgeBaseIds=&limit=&offset= → {faqs, count, hasMore} — a duplicate question → 409 "A FAQ with this question already exists in this knowledge base"; the 1000-character answer cap is client-only (1001 stored)
Rich text POST /knowledge-base/rich-text/ {locationId, knowledgeBaseId, title, content (HTML)} → status:"training" GET /knowledge-base/rich-text/{id}/status?locationId= → {sourceType, status, stages[CHUNKING, EMBEDDING]{state, durationMs}} DELETE /knowledge-base/rich-text/{id} trained in ~3 s; the server adds generated questions to the chunk; edit with PUT (Trap 5); the editor also offers bulk delete (/rich-text/bulk) and a per-document cancel (/rich-text/{id}/cancel), neither executed
Web crawler POST /knowledge-base/crawler {locationId, url, option: "Exact" | "Path" | "Domain", knowledgeBaseId} → {operationId, status:"Processing"} GET /knowledge-base/crawler?locationId=&knowledgeBaseId= → {count, urls[]}; GET …/crawler/status = the latest operation only; GET …/crawler/pages/content?locationId=&urlId=&knowledgeBaseId= → the scraped text DELETE /knowledge-base/crawler {locationId, urlIds, deleteAll:false, knowledgeBaseId} → {deletedCount} Exact mode trains with no separate train call; sitemap-preview refuses Exact (400); the URL refresh PUT /knowledge-base/crawler?locationId=&knowledgeBaseId= {urlIds, refreshAll, urlIdsToSkip} answered 200 and changed nothing within 8 s, so its effect is unproven; Path / Domain, cancel and retry are unexercised
URL auto-refresh POST /knowledge-base/crawler/automation {knowledgeBaseId, refreshFrequency: DAILY | WEEKLY | MONTHLY} → an ACTIVE WEBSITE_RETRAIN task, first run a week out for WEEKLY GET …/crawler/automation/latest?knowledgeBaseId= DELETE …/crawler/automation/{id} (then latest → data:null) the update PUT …/automation/{id} needs taskId = the automation's own id (422 "taskId must be a string" without it)
File multipart POST /knowledge-base/files GET /knowledge-base/files/{id}; …/{id}/status stages CONVERSION → EXTRACTION → CHUNKING → EMBEDDING DELETE /knowledge-base/files/{id} (then 400 "Invalid file ID") ≤ 10 MB, .pdf .doc .docx .md; trained in ~3 s
Table (CSV) multipart POST /knowledge-base/table/location/{loc}/kb/{kb}/upload, then POST …/{fileId}/select-columns {selectedColumns[{name, originalType, selectedType, isSelected, sampleValue, displayName, searchable, required}]} GET …/{fileId}, …/status (ANALYZING → PROCESSING → INDEXING), …/data?page=&limit= DELETE …/{fileId} (then 404) ≤ 50 MB; trained in ~48 s

🔴 Files and tables are multipart uploads. raw_request sends JSON only, so neither can be created through this plugin today: point the user to the editor's Files / Tables tab.

The scraped text of a crawled page is edited through View scraped content → Save: PUT /knowledge-base/crawler/pages/content?locationId=&urlId=&knowledgeBaseId= {content} → 200 with an empty body. The row retrains and reads back status: "Successful", contentEditedByUser: true, and retrieval returns the edited text (proven live 2026-09-29). Retraining the URL from the website reverts the edit (the editor's warning). The URL list's content field is a storage URL to the text file, not the text itself. The /conversations-ai/train/chunk/content route older notes gave is not called by the Knowledge Base app.

Gaps: GET /knowledge-base/gaps/counts?locationId= → {data[{knowledgeBaseId, gapCount}]} for the whole location; GET /knowledge-base/gaps?locationId=&knowledgeBaseId=&status=open&page=&perPage= → {gaps[], stats{openGaps, queriesAffected, resolvedThisMonth, archivedGaps}, total}. The editor's tabs are Needs answers · Answered · Archived. POST /knowledge-base/gaps/{gapId}/fill {title, answer, locationId} writes into the KB itself and has not been executed.

What GHL can do that this plugin cannot reach on the test account

If the user wants one of these, GHL can do it — say so and point to the screen.

Capability Where in GHL Why not here
Import files from Google Drive, daily Drive sync KB → Files → "Import from Google Drive" (flag knowledgeBase.googleSheets) needs a connected Google account (GET /knowledge-base/oauth?locationId=&type=google); the only one on the test account is a person's own, so it was not used
Google Sheet as a table, auto / scheduled sync KB → Tables → "Import from Google Sheets" same
Internal Data (sync the sub-account's Products) KB source behind flag knowledgeBase.internalData GET /knowledge-base/internal-data/sources answered 403 "Forbidden resource" on the test account
Web search as a source no screen: the editor hard-codes it off the client ships the module, but GET /knowledge-base/web-search/kb/{id} answered 404 "Cannot GET"
Create with AI (Beta) KB list → "Create with AI" it opens the Ask AI copilot ("Create a knowledge base from brand voice") and makes no KB call of its own
Open the KB screen at all AI Agents → Knowledge Base the page sits behind the conversation_AI billing opt-in (config.optIn), not enabled

Writing FAQs from real conversations

When the job is to fill a knowledge base from what customers already asked, keep only the questions a customer asked to get facts (products, services, prices, hours, policies, how things work). Drop greetings, bookings, one-word replies, staff-only notes and system lines. Take the question from the customer's side and the answer from the business's side. Remove anything personal (names, numbers, addresses, billing details) and anything only true on one day ("closed today", a slot time). Rewrite colloquial questions so each one stands alone and names its product. Answers the bot gave that said it did not know are the most useful candidates: complete them where the facts are known. Where a value is unknown and changes (a price, hours, a phone number), write a clear placeholder such as [price] instead of inventing it or leaving the answer empty. Merge questions that ask the same thing into one pair, then save them in one bulk call and read back how many were created, updated or failed.

Limits

Files ≤ 10 MB (.pdf .doc .docx .md) · table CSV ≤ 50 MB · rich text ≤ 25,000 characters and 512 KiB of HTML (richTextBlockedByLimit fires on the character cap, not on a document count) · FAQ answer ≤ 1000 (client-only) · KB name ≤ 50 (client-only) and description ≤ 175 · ≤ 7,000 crawled pages per KB · 15 KBs per sub-account · ≤ 4 knowledge-base triggers per bot (server) · at least one KB must be selected where a bot requires one.

Proof status — read before trusting a write

Live-proven (executed on a test sub-account and read back on a separate request): the KB record's create, read, list, rename, delete and associated-entities read; FAQ, rich text (create, full-replace PUT, delete), web crawler (Exact mode, delete, auto-refresh create/update/delete), file and table sources (uploaded from the editor, then read and deleted through the API); retrieval and its history; the gap list and the gap archive/restore write. Also live-proven (2026-09-29): the scraped-text edit, and a robots.txt-blocked crawl's status and error. Not proven: the crawl refresh's effect; Path / Domain crawls; crawl cancel / retry (an Exact crawl of one page finishes in about 2 s, and anything longer needs a multi-page crawl); gap fill; and everything in the table above. Treat a first write of an unproven operation as a throwaway validation run on a test sub-account.

Scope

Knowledge bases only. The agents that consume them are ghl-voice-ai (internal) and Conversation AI (lists its bots and configures them on the internal rail — see ghl-conversation-ai).

04 同仓库更多 Skills

uxieee
uxieee/uxie-ghl-factory

ghl-workflow-specialist

Senior GoHighLevel workflow architect — designs automations (nurture, speed-to-lead, no-show recovery, internal ops, data hygiene, routing) grounded in the full trigger/action catalog and known anti-patterns, and reviews or fixes live workflows. Use when the user asks what automation to set up for X, wants a workflow designed, or asks why a live workflow is not getting through, is failing, or whether an A/B test is done. Recons + reads the client brief before proposing anything. Once approved, the build itself goes to create-ghl-workflow.

★ 12
uxieee
uxieee/uxie-ghl-factory

ghl-workflow-fast-forward

Fast-forward contacts parked at a GoHighLevel / HighLevel workflow WAIT step to the next step — the builder's "Action statistics → move to next step" control, driven via the internal API. Use to accelerate end-to-end workflow testing (drive a multi-day wait ladder to completion in minutes instead of waiting real time), to unstick contacts stranded at a wait, or when the user says "fast-forward this wait", "skip the wait", "move parked/stuck contacts to the next step", "requeue stuck contacts", "test this long delay without waiting days", or gives an app.gohighlevel.com workflow URL and asks to push contacts past a wait. This MUTATES live enrollments (it fires whatever steps come next, i.e. real SMS/email to real people) — it is a WRITE skill and follows the plugin's write-rails. It is the mutating counterpart to the read-only get-ghl-workflow-logs.

★ 12
uxieee
uxieee/uxie-ghl-factory

ghl-voice-ai

Build and configure GoHighLevel Voice AI phone agents — the prompt, the voice, the actions (appointment booking, call/agent transfer, contact-field extraction, SMS, workflows, custom API), knowledge bases, MCP servers, working hours, and outbound consent. Use when the user says 'set up a voice agent', 'build a phone agent', 'my AI should answer calls', 'book appointments over the phone', 'outbound calling', 'the agent isn't transferring calls', 'change the voice', or names a Voice AI agent. Internal API — the public rail exposes only how the agent sounds, not what it does.

★ 12
uxieee
uxieee/uxie-ghl-factory

ghl-system-conventions

House conventions for building GoHighLevel systems — workflow naming and structure, tag/field/custom-value discipline, pipeline and opportunity decisions, copy rules, and the pre-build approval document the operator signs off before anything gets created. Account-agnostic, for ANY GHL sub-account. Use whenever designing, building, editing, reviewing, or discussing GHL workflows, automations, pipelines, stages, opportunities, tags, custom fields, custom values, calendars, or AI agents — even if the user never says "conventions" or "standards". Load it BEFORE proposing a design or creating any GHL object, so the proposal already looks the way the operator wants it.

★ 12
uxieee
uxieee/uxie-ghl-factory

ghl-snapshots

GoHighLevel snapshots — capturing a sub-account's assets into a reusable snapshot, refreshing one, curating what it carries, and checking load conflicts. Use when a task involves creating or updating a snapshot, deciding what an account template should include, asking why a snapshot came out empty or is stuck processing, or planning a rollout onto other sub-accounts. Read it BEFORE calling any /snapshots path by raw_request — two of the write endpoints silently do the wrong thing.

★ 12
uxieee
uxieee/uxie-ghl-factory

ghl-reverse-engineering

Map a GoHighLevel internal surface exhaustively — enumerate every screen, panel, control and save path a feature has, capture the real request behind each one, prove what each field does by differential, and write the result into the corpus. Use when the user wants to understand how a GHL feature works under the hood, extend an engine to an object the public API can't reach, re-sweep a surface that already has partial coverage, or asks to reverse-engineer / sniff / capture / trace anything internal. GHL permits inspecting your own account's traffic. This is a MAPPING skill, not a lookup: it finishes when the surface is exhausted, not when the first endpoint is found.

★ 12