Knowledge Base Administration

This skill activates when an admin or architect needs to set up or manage Salesforce Lightning Knowledge — covering the one-time enablement decision, record type design on the Knowledge__kav object, Data Category configuration for dual-purpose organization and access control, and publishing workflow design using native statuses, Validation Status, and optional approval processes.

---

Before Starting

Gather this context before working on anything in this domain:

• Lightning Knowledge enabled? Navigate to Setup > Knowledge Settings. If the toggle is OFF, understand that enabling it is irreversible — once turned on, Classic Knowledge article types are permanently replaced by Lightning Knowledge record types on the single Knowledge__kav object. There is no undo path. <!-- UNVERIFIED (2026-09-04): irreversibility is not stated in the extracted Metadata API or Object Reference PDFs, where `enableLightningKnowledge` is documented as a plain boolean. The claim rests on Salesforce Help (Set Up Lightning Knowledge), which cannot be fetched from the authoring environment. Nothing here depends on it being wrong — plan the enablement as one-way — but do not quote "Salesforce documents this as irreversible" to a stakeholder without opening that Help article yourself. -->
• Most common wrong assumption: Practitioners often assume Data Categories are purely organizational (like tags). In reality, they serve dual duty: content categorization AND access control. A user must have visibility to at least one category in every Data Category Group assigned to an article in order to see that article. Misconfigured visibility silently hides articles from users who expect to see them.
• Platform constraints: The Metadata API guide caps a group at 100 categories and 5 hierarchy levels. The org-level cap on how many groups can be active for Knowledge is 5, with 3 active by default. <!-- UNVERIFIED (2026-09-04): the 100-categories / 5-levels cap is stated in the Metadata API Developer Guide under DataCategoryGroup. The "5 groups, 3 active by default" org cap is not in the Metadata API PDF, the Object Reference, or the App Limits cheat sheet (which documents no Knowledge limits at all) — it is carried by architect/knowledge-taxonomy-design, which is the authority for taxonomy sizing. Verify against your org's Setup before designing a fourth group. -->
• What is the knowledge object actually called? Knowledge__kav is only the default. The Object Reference notes the prefix can be renamed in Object Manager, and the rename propagates to Knowledge__DataCategorySelection, to ChannelLayout field references, and to every metadata path and query. Read the real API name before writing any of them.

---

Questions to Ask Before Configuring

Ask these before touching Knowledge Settings. Each one maps to a documented behaviour that is expensive to reverse, and an assistant that skips them produces a knowledge base that deploys cleanly and shows nobody any articles.

Ask	Why it matters	What a good answer adds
"Is Lightning Knowledge already on, and if not, who signs off on turning it on?"	enableKnowledge plus enableLightningKnowledge is the fork between one Knowledge__kav object and per-type Classic __kav objects; the Classic path needs admin/knowledge-classic-to-lightning instead of this skill	A named approver, and the sandbox the design was proved in
"Which audiences read articles, and does any of them sit outside the role hierarchy?"	Category visibility is granted per role, and per profile via categoryGroupVisibilities; guest and community users need the profile route	The audience × category matrix that becomes the Profile XML
"Which classification axes are genuinely independent — and how many groups is that?"	Each axis is a DataCategoryGroup, capped at 100 categories and 5 levels, and the org caps how many can be active	A group list sized against architect/knowledge-taxonomy-design, before any XML exists
"Do articles need more than one language?"	defaultLanguage and the languages block are set once in the settings file, and each language carries its own default assignee and reviewer	The language list with a queue per language rather than a named user
"Does anything need to block publication, or only signal quality?"	Native PublishStatus has no gate; ValidationStatus signals without blocking; an approval process blocks and needs "Manage Articles" to submit	The chosen workflow and who holds the submit permission
"Who gets the Knowledge User feature licence, and how many are there?"	The Object Reference is explicit that internal Knowledge users need it in addition to the View Articles permission — it is a checkbox on the User record, not a permission set	A licence count checked against what the org owns, before go-live
"Will this configuration be deployed from a sandbox, or built in production?"	Deploying a DataCategoryGroup permanently deletes any category the XML omits and re-parents its articles; Salesforce's own guidance is to make category changes in Setup	An explicit decision, with the deploy path restricted to settings, record types, and profiles

What a proper configuration adds over just enabling Knowledge: articles are findable by the audience they were written for on the day they are published, the taxonomy can be changed later without silently re-parenting articles, and the publish workflow is a reviewed gate rather than an author's one-click habit.

---

Core Concepts

Lightning Knowledge and the Knowledge__kav Object

Lightning Knowledge consolidates all article content onto a single standard Salesforce object: Knowledge__kav (the Knowledge Article Version object). Unlike Classic Knowledge, which used separate custom objects for each article type, Lightning Knowledge uses standard record types on Knowledge__kav to differentiate content types (e.g., FAQ, How-To, Known Issue). This means page layouts, field sets, and Lightning record pages are configured per record type — the same tooling used for any other Salesforce object.

Enabling Lightning Knowledge is a one-way migration. The Setup toggle activates the feature and converts existing Classic article types into record types. There is no disable path and no rollback. Once enabled, Classic Knowledge Setup options disappear and the Knowledge__kav object is the permanent storage layer.

Each Knowledge Article has a parent Knowledge__ka (Knowledge Article) record that acts as the container, while Knowledge__kav records represent individual versions. Published articles always have exactly one published version. Archiving a published article creates a new Archived version rather than modifying the Published version in place.

Data Categories: Dual-Purpose Organization and Access Control

Data Categories are hierarchical category groups that admins attach to Knowledge articles. Their dual role is critical:

1. Organization: Categories allow agents and customers to browse or filter articles by topic. A support team might use a "Products" category group with subcategories for each product line.
2. Access Control: Salesforce evaluates category visibility before showing articles to any user. Visibility is granted through Role Hierarchy, Profiles, or Permission Sets. If a user has no visibility into any category in a group that is assigned to an article, that article is invisible to them — regardless of object-level permissions.

The visibility model is additive: users inherit visibility from their role hierarchy. An admin must explicitly deny visibility to restrict access downward. Default visibility for unauthenticated guest users must be set separately via the Guest User Category Visibility settings.

Unclassified articles (articles with no category assigned from a group) are visible only to users with "View All Data" or explicit "Manage Categories" permissions — a common cause of articles disappearing immediately after creation.

Publishing Workflow: Statuses, Validation Status, and Approval Processes

Every Knowledge article version moves through three native platform statuses:

• Draft: Article is being authored or edited. Not visible to end users.
• Published: Article is live. Exactly one published version can exist per article at any time. Publishing a new version automatically archives the previous published version.
• Archived: Article is retired from public view but preserved for history and potential restoration.

On top of native statuses, admins can enable a Validation Status picklist on Knowledge__kav. This is an admin-customizable picklist (values like "Validated", "Not Validated", "In Review") that signals content quality. Validation Status is separate from publish status — an article can be Published but flagged as "Not Validated." Agents can filter article searches by Validation Status to surface only quality-assured content.

For organizations requiring formal review before publishing, Salesforce supports standard Approval Processes on Knowledge__kav. An approval process can require sign-off from a subject-matter expert before a Draft article can transition to Published. Approval processes on Knowledge articles use the same Process Builder/Flow-backed approval framework as other objects, with the constraint that only the record owner or users with "Manage Articles" permission can submit articles for approval.

Channels and Languages: The Two Switches Outside the Category Model

Data category visibility decides which articles a user may see. Two other switches decide where an article can appear at all, and neither is a category:

Switch	Where it lives	What it controls
IsVisibleInApp	Field on the article version	Article appears on the Articles tab
IsVisibleInCsp	Field on the article version	Article appears in the Customer Portal
IsVisibleInPrm	Field on the article version	Article appears in the partner portal
IsVisibleInPkb	Field on the article version	Article appears in the public knowledge base
ChannelLayout	channelLayouts/ metadata	Which article fields get shared inline into Email, Chat, Messaging, and Social publishers, optionally per record type

All four IsVisibleIn* fields are marked Required in the Object Reference and default on create, so a bulk-loaded article has channel flags whether the loader set them or not. An internal-only record type is not protected by its layout — it is protected by leaving IsVisibleInPkb and IsVisibleInCsp false and by field permissions on the internal fields.

Languages are set once, in the settings file: a required defaultLanguage plus a languages block where each entry carries name, active, and a default assignee and reviewer that may be a User or a Queue. On the article side, Language, IsMasterLanguage, and IsOutOfDate carry the translation state, and every article query should filter on Language as well as PublishStatus.

---

Common Patterns

Pattern: Record Type per Content Audience

When to use: When different teams produce different content types that need distinct field sets and layouts. For example, a support team authoring detailed technical Known Issue articles needs different fields than a marketing team writing FAQ articles for customers.

How it works:

1. Enable Lightning Knowledge in Setup > Knowledge Settings.
2. Navigate to Setup > Object Manager > Knowledge > Record Types.
3. Create a record type for each content type (e.g., "FAQ", "How-To", "Known Issue", "Release Note").
4. Assign page layouts per record type — hide internal-only fields (e.g., "Root Cause") from the customer-facing layout.
5. Assign record types to profiles so authors only see record types relevant to their role.

Why not the alternative: Using a single record type with all fields visible causes layout clutter and risks exposing internal fields (root cause analysis, workaround notes) to customer-facing surfaces. Record types enforce the separation cleanly without custom Apex.

Pattern: Data Category Groups for Layered Visibility

When to use: When the org serves multiple audiences (internal agents, partners, customers via Experience Cloud) who should see overlapping but distinct article sets.

How it works:

1. Create Data Category Groups in Setup > Data Category Groups, and assign each to KnowledgeArticleVersion — the group's objectUsage element. Size the group count against architect/knowledge-taxonomy-design before building.
2. Design the hierarchy to reflect your content taxonomy (e.g., "Products > Product A > Feature X").
3. In Setup > Roles, assign category visibility per role: "Include subcategories" to inherit the tree downward, or "Exclude" to explicitly block.
4. Test visibility by logging in as a representative user from each role before go-live.
5. For guest/unauthenticated users, set the default category visibility under Knowledge Settings > Guest User Category Access.

Why not the alternative: Using only object-level sharing or permission sets for article access bypasses the Data Category visibility check — articles remain invisible even if the user has object read access unless category visibility is also configured.

---

Decision Guidance

Situation	Recommended Approach	Reason
Single article type, small team, no approval needed	One record type + native Draft/Published/Archived statuses	Lowest overhead; sufficient for simple use cases
Multiple content types with different field requirements	Separate record type per content type with distinct page layouts	Record types are the standard mechanism for layout differentiation on a single object
Content quality signal needed without blocking publish	Enable Validation Status picklist; train authors to mark status	Non-blocking; lets agents filter by quality without stopping publication
Regulated content requiring sign-off before publishing	Approval Process on Knowledge__kav + Validation Status	Approval processes enforce the gate; Validation Status surfaces the approval outcome
Multiple audiences with different article visibility needs	Data Category Groups with role-based visibility assignments	The only platform-native mechanism for audience-scoped article visibility
Migrating from Classic Knowledge	Plan record types before enabling Lightning Knowledge; enablement is irreversible	Post-enablement reconfiguration is possible but article type recategorization requires bulk data updates

---

Recommended Workflow

1. Establish the object name and current state — read the knowledge object's real API name in Object Manager (Knowledge__kav is only the default), and retrieve Settings:Knowledge to see whether enableKnowledge and enableLightningKnowledge are already true. A Classic org routes to admin/knowledge-classic-to-lightning before anything here applies.
2. Answer the seven questions above and size the taxonomy — the audience × category matrix and the group count come from architect/knowledge-taxonomy-design; do not write DataCategoryGroup XML before that number is agreed, because the group is expensive to split later.
3. Write the five artefacts together — settings, category groups, record types and fields, the profile blocks that carry categoryGroupVisibilities, and the author permission set. references/metadata-examples.md has the deployable shape of each plus the manifest that names the three types a wildcard will not retrieve.
4. Check before deploying — run python3 scripts/check_knowledge_base_administration.py --manifest-dir force-app/main/default. It catches the four silent failures: an inactive group, a group with no objectUsage, a Classic settings file (enableKnowledge true with enableLightningKnowledge false), and a profile granting visibility to a category group that is not in the package.
5. Deploy settings, record types, and profiles — but make category structure changes in Setup — the Metadata API guide states plainly that deploying category changes between orgs "permanently removes categories and record categorizations that are not specified in your XML file" and recommends Setup instead (references/gotchas.md #6).
6. Prove visibility per audience, not per config screen — publish one article per record type and per language, classify it, then query it as a representative user of each audience with WHERE PublishStatus = 'Online' AND Language = '<code>' and confirm the rows in Knowledge__DataCategorySelection. Both queries are in references/metadata-examples.md §7.
7. Record the runbook — object API name, record type list, group and category developer names (which the guide says cannot be changed later), which profiles hold category visibility, and who holds "Manage Articles". templates/knowledge-base-administration-template.md is the shape.

---

Review Checklist

Run through these before marking Knowledge setup work complete:

• Lightning Knowledge enablement decision documented and acknowledged as irreversible
• Record types created with appropriate page layouts per content type
• Record types assigned to correct author profiles
• Data Category Groups created, active true, and each assigned to KnowledgeArticleVersion (Setup → Data Category Group Assignments)
• Group count within the org's active limit, sized per architect/knowledge-taxonomy-design
• Category visibility assigned per audience on roles and profiles — permission sets carry no categoryGroupVisibilities; guest user defaults set if applicable
• Knowledge User feature licence granted to every internal author and agent, in addition to the View Articles permission
• Unclassified article visibility tested — confirm articles without categories behave as expected
• Publishing workflow configured (native statuses, Validation Status, and/or Approval Process)
• At least one test article created, published, and verified visible to each intended audience
• Archived version behavior verified (previous published version archived on re-publish)
• Verification queries run: Knowledge__kav filtered on PublishStatus + Language, and Knowledge__DataCategorySelection for the classifications
• scripts/check_knowledge_base_administration.py --manifest-dir <dir> run clean against the retrieved metadata

---

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Lightning Knowledge enablement is irreversible — Once you enable Lightning Knowledge in Setup, there is no disable toggle. Classic Knowledge article types are permanently converted to record types on Knowledge__kav. Do not enable in production without a complete design review and stakeholder sign-off.
2. Unclassified articles are invisible by default — If an article has no Data Category assigned from any active Knowledge Category Group, it is only visible to users with "View All Data" or "Manage Articles" permission. New authors who forget to assign categories inadvertently publish invisible articles, leading to "I can't find the article I just published" support requests.
3. Publishing a new version archives the previous one immediately — Clicking Publish transitions the currently published version to Archived at once, and there is no in-place undo. The documented recovery is KbManagement.PublishingService.restoreOldVersion(articleId, versionNumber), which builds a new draft from an archived version rather than reinstating it. Note that scheduling does exist programmatically even though the Setup button is immediate: scheduleForPublication and archiveOnlineArticle both accept a date, and dates are GMT.
4. Data Category visibility is additive from role hierarchy, not subtractive — Administrators cannot use role hierarchy to restrict visibility downward using inheritance alone. A child role inherits parent role visibility. If you need a child role to see fewer categories than the parent, you must explicitly configure that child role's visibility separately, not rely on inheritance.
5. Approval Processes on Knowledge__kav require "Manage Articles" to submit — Only the article owner or a user with the "Manage Articles" permission can submit a Knowledge article for approval. If authors lack this permission, they cannot trigger the approval workflow, breaking the publishing gate. Assign "Manage Articles" to author profiles intentionally.
6. A DataCategoryGroup deploy is a replace, not a merge — every category absent from the XML is deleted and its articles are re-parented; every objectUsage entry absent from the XML is unassigned. Salesforce's own guidance is to make category structure changes in Setup rather than deploy them between orgs.
7. categoryGroupVisibilities exists on Profile only — the Metadata API PermissionSet type has no equivalent, so a profile-to-permission-set migration silently strips article visibility while leaving object access intact.
8. A wildcard manifest retrieves none of it — * on CustomObject does not match standard objects (and Knowledge__kav is standard), RecordType does not accept * at all, and Settings needs the member named Knowledge.
9. Article SOQL has two rules of its own — PublishStatus or Id must appear in the WHERE clause, and bind variables are a compile error against article objects (use Database.query). The status value is Online, not "Published".

Full treatment, with the guide passages each rests on, is in references/gotchas.md.

---

Output Artifacts

Artifact	Description
Knowledge Setup Decision Document	Records the Lightning Knowledge enablement decision, confirming it is irreversible and that stakeholders have approved
Record Type Taxonomy	Table of record types, associated layouts, and profile assignments
Data Category Group Map	Hierarchy diagram of category groups with role/profile visibility matrix per audience
Publishing Workflow Decision	Documents choice of native statuses / Validation Status / Approval Process and the rationale
Admin Runbook	Operational procedures for ongoing Knowledge management (creating article types, updating categories, managing approvals)
settings/Knowledge.settings-meta.xml	Feature enablement, default language, active languages with assignee/reviewer queues, Validation Status switch
datacategorygroups/<Name>.datacategorygroup-meta.xml	The taxonomy tree with active and objectUsage on KnowledgeArticleVersion
objects/Knowledge__kav/ record types and fields	Article types and their custom fields, dot-qualified as Knowledge__kav.<Field>__c
profiles/<Name>.profile-meta.xml	The categoryGroupVisibilities blocks — the only place article visibility can be deployed
Verification query output	Knowledge__kav rows by PublishStatus + Language, and the matching Knowledge__DataCategorySelection rows

---

Reference Files

File	Read it when
references/metadata-examples.md	Writing deployable KnowledgeSettings, DataCategoryGroup, Knowledge__kav record type and field, Profile / PermissionSet XML, the package.xml, the retrieve/deploy commands, the verification SOQL, and the KbManagement.PublishingService snippet
references/gotchas.md	Eleven platform behaviours behind most Knowledge incidents — silent category deletion on deploy, missing objectUsage, visibility stranded on the profile, wildcard manifests that retrieve nothing, and the article-SOQL rules
references/examples.md	Worked multi-audience visibility design, the approval-process layering, and the permission-sets-alone anti-pattern
references/well-architected.md	Pillar mapping, the native-status vs Validation Status vs approval tradeoff, and the source list behind every claim in this package
references/llm-anti-patterns.md	Self-checking generated output — the ways an assistant gets Lightning Knowledge wrong
templates/knowledge-base-administration-template.md	Capturing the design before building it: context, record type matrix, category matrix, workflow choice, and the build checklist
scripts/check_knowledge_base_administration.py	Linting a retrieved metadata directory before deploy (--manifest-dir)

---

Related Skills

• architect/knowledge-taxonomy-design — Owns taxonomy sizing and shape (how many groups, how deep, which axes). Read it before writing any DataCategoryGroup XML; this skill owns the deployable metadata that results
• admin/knowledge-classic-to-lightning — Use instead of this skill when the org is still on Knowledge in Salesforce Classic with per-type __kav objects that must become record types
• data/knowledge-article-import — Use when articles arrive in bulk from an external help centre; imported articles land in Draft and need an explicit publish before any visibility design takes effect
• admin/record-types-and-page-layouts — Use for the record type and layout mechanics themselves, including why a record type is not an access control
• architect/knowledge-vs-external-cms — Use when deciding whether to use Salesforce Knowledge or an external CMS for content management
• agentforce/einstein-copilot-for-service — Knowledge article quality directly bounds Einstein Service Replies grounding quality; review both skills when deploying AI-assisted service
• admin/delegated-administration — Use alongside this skill when Knowledge article management responsibilities are delegated to non-admin users

Taxonomy design or audit for a whole org is the job of the /design-knowledge-taxonomy run-time agent (agents/knowledge-article-taxonomy-agent/AGENT.md), which cites this skill for the admin setup and deployable shapes.