work.studio Public Documentation Knowledge Organization

This directory contains metadata for organizing work.studio customer documentation into Knowledge Bases (KB) and Skills for AI agent consumption.

Overview

public-docs/ serves two purposes:

Static Website — Published to docs.workstudio.ai (Retype static site)
AI Knowledge Source — Indexed by platform for RAG and skill extraction

KB vs Skill Classification

Knowledge Bases (Reference Material)

Type: Conceptual documentation that explains "what" and "how things work"
Format: Markdown documents
Use Case: AI agents query for understanding, not step-by-step execution

Categories:

Platform Overview (getting-started/platform-overview.md, getting-started/concepts.md)
User Guide (user-guide/*.md) — Feature reference material
Use Cases (use-cases/) — Example scenarios and patterns
API Reference (api-reference/) — API documentation
FAQ (faq.md) — Common questions
Glossary (glossary.md) — Terminology

Skills (Step-by-Step Procedures)

Type: Actionable tutorials with specific steps
Format: Skill templates extracted from tutorials
Use Case: AI agents execute or guide users through procedures

Categories:

Getting Started Tutorials (getting-started/quick-start.md)
Integration Tutorials (tutorials/*.md)
Troubleshooting Procedures (troubleshooting.md)

File Structure

public-docs/docs/
├── knowledge-bases/              # This metadata directory
│   ├── README.md                 # This file
│   ├── kb-registry.json          # KB catalog
│   └── skill-mapping.json        # Skill extraction mapping
│
├── getting-started/              # KB + Skills mix
│   ├── index.md                  # KB - Overview
│   ├── platform-overview.md      # KB - Concepts
│   ├── concepts.md               # KB - Core concepts
│   └── quick-start.md            # SKILL - Extracted to platform-resources/skills
│
├── user-guide/                   # All KB (reference)
│   ├── index.md                  # KB
│   ├── automations.md            # KB
│   ├── connections.md            # KB
│   ├── apps.md                   # KB
│   ├── dashboards.md             # KB
│   ├── data-explorer.md          # KB
│   ├── customers.md              # KB
│   ├── portal.md                 # KB
│   ├── releases.md               # KB
│   ├── resources.md              # KB
│   └── settings/                 # KB
│       ├── workspace.md
│       ├── team.md
│       └── api-keys.md
│
├── tutorials/                    # All SKILLS (extracted to platform-resources/skills)
│   ├── index.md                  # KB - Tutorial index
│   ├── first-automation.md       # → SKILL: create-first-automation
│   ├── slack-notifications.md    # → SKILL: setup-slack-integration
│   ├── email-notifications.md    # → SKILL: setup-email-integration
│   ├── rest-api.md               # → SKILL: setup-rest-api
│   └── scheduled-reports.md      # → SKILL: create-scheduled-workflow
│
├── use-cases/                    # All KB (examples)
│   ├── index.md
│   ├── policy-compliance/
│   ├── security-platform/
│   └── vulnerability-scanning/
│
├── api-reference/                # All KB (API docs)
│   └── ...
│
├── faq.md                        # KB
├── glossary.md                   # KB
├── troubleshooting.md            # SKILL: troubleshoot-workflow
├── pricing.md                    # KB (not indexed - marketing content)
└── index.md                      # KB (welcome/overview)

KB Registry

See: kb-registry.json

KB Categories:

platform-concepts — What work.studio is, core concepts
user-guide — How to use features (reference)
use-cases — Example scenarios
api-reference — API documentation
faq-glossary — Quick reference

Skill Mapping

See: skill-mapping.json

Skills Extracted to platform-resources/skills/:

quick-start ← getting-started/quick-start.md
create-first-automation ← tutorials/first-automation.md
setup-slack-integration ← tutorials/slack-notifications.md
setup-email-integration ← tutorials/email-notifications.md
setup-rest-api ← tutorials/rest-api.md
create-scheduled-workflow ← tutorials/scheduled-reports.md
troubleshoot-workflow ← troubleshooting.md

Usage by AI Agents

Knowledge Retrieval (RAG)

AI agents use semantic search on KB documents when users ask:

"What is a workflow?" → user-guide/automations.md
"How do connections work?" → user-guide/connections.md
"What are the pricing plans?" → pricing.md

Skill Execution

AI agents invoke skills when users request action:

"Create a Slack automation" → setup-slack-integration skill
"Set up scheduled reports" → create-scheduled-workflow skill
"My automation isn't working" → troubleshoot-workflow skill

Indexing Configuration

For platform indexing (future implementation):

# Example KB definition YAML
apiVersion: work.studio/v1
kind: KnowledgeBase
metadata:
  name: customer-user-guide
  source: public-docs
spec:
  sourceType: DIRECTORY
  path: docs/user-guide/
  embeddingModel: cohere.embed-english-v3
  chunkSize: 512
  chunkOverlap: 50
  purpose: CUSTOMER_SUPPORT
  classification: PUBLIC

Maintenance

When Adding New Documentation

Conceptual Docs → Add to user-guide/, update kb-registry.json
Step-by-Step Tutorials → Add to tutorials/, extract to platform-resources/skills/, update skill-mapping.json
Example Scenarios → Add to use-cases/, update kb-registry.json

When Updating Existing Docs

KB Docs → Update markdown, KB auto-refreshes on next index
Tutorial Docs → Update markdown AND corresponding SKILL.md in platform-resources/skills/

Platform Resources KB: ../../platform-resources/knowledge-bases/ — Technical KB for platform features
Platform Resources Skills: ../../platform-resources/skills/ — Extracted customer skills
Internal Docs KB: ../../internal-docs/kb/ — Platform architecture KB
Internal Docs Skills: ../../internal-docs/skills/ — Development skills

Source Control

Files Generated:

kb-registry.json — KB metadata catalog
skill-mapping.json — Tutorial → Skill mapping

Files to Keep in Sync:

public-docs tutorials ↔ platform-resources/skills SKILL.md
When tutorial changes, update corresponding skill