← All posts

Building My Personal Documentation and AI Toolkit

aimcpagent-skillsdocumentationautomation

Building My Personal Documentation and AI Toolkit

Today I designed the base of two connected projects:

  1. A personal documentation website
  2. A portable AI toolkit

I decided to keep them in separate repositories.

The documentation repository stores knowledge for people and AI agents. The AI toolkit repository stores skills, MCP servers, workflows, and safety rules.

The two projects can work together, but they do not depend on each other. I can change the documentation website without changing the AI toolkit. I can also use the AI toolkit with a different documentation source in the future.

Why Two Repositories?

At first, keeping everything in one repository looked easier. However, documentation and executable tools have different needs.

Documentation changes often. It contains notes, decisions, runbooks, architecture pages, and business information. It should be easy to read, search, review, and publish.

The AI toolkit contains code and automation. It needs tests, dependencies, permissions, releases, and security controls.

Separating them gives me a clearer model:

personal-docs  = knowledge and documentation
ai-toolkit     = skills, tools, workflows, and automation

This separation also gives me different access rules. An agent may have read access to documentation but no permission to change it. A developer may update an MCP server without needing access to private business notes.

Repository One: Personal Docs

The first repository is a private, Confluence-style documentation system.

I want it to be free, durable, searchable, and easy for AI agents to read. I do not want my knowledge to be locked inside one SaaS product.

For this reason, I chose:

  • Markdown for content
  • Git for version history
  • Material for MkDocs for the website
  • Cloudflare Pages for hosting
  • Cloudflare Access for authentication

Markdown is the main source. The website is only a view of that source.

If Cloudflare, MkDocs, or another service changes in the future, the Markdown files will still exist. I can build another website from the same files.

Personal Docs Structure

personal-docs/
├── docs/
│   ├── index.md
│   │
│   ├── personal/
│   │   ├── profile.md
│   │   ├── goals.md
│   │   ├── preferences.md
│   │   ├── writing-style.md
│   │   └── decisions.md
│   │
│   ├── companies/
│   │   ├── business-a/
│   │   │   ├── index.md
│   │   │   ├── products.md
│   │   │   ├── architecture.md
│   │   │   └── commercial-model.md
│   │   └── business-b/
│   │       ├── index.md
│   │       ├── products.md
│   │       ├── architecture.md
│   │       └── commercial-model.md
│   │
│   ├── engineering/
│   │   ├── kubernetes/
│   │   ├── kafka/
│   │   ├── cicd/
│   │   ├── terraform/
│   │   ├── cloud/
│   │   └── observability/
│   │
│   ├── security/
│   │   ├── controls/
│   │   ├── architecture/
│   │   ├── questionnaires/
│   │   ├── policies/
│   │   └── evidence/
│   │
│   ├── marketing/
│   │   ├── advertising/
│   │   ├── seo/
│   │   ├── analytics/
│   │   └── experiments/
│   │
│   ├── business/
│   │   ├── suppliers/
│   │   ├── customers/
│   │   ├── pricing/
│   │   └── sales-processes/
│   │
│   ├── runbooks/
│   ├── architecture-decisions/
│   ├── meeting-notes/
│   └── journal/
│
├── overrides/
├── assets/
├── mkdocs.yml
├── requirements.txt
├── Dockerfile
└── .github/
    └── workflows/
        └── deploy.yml

Why These Folders Exist

The personal/ folder stores stable information about my goals, preferences, and working style. An AI agent can use this information when it prepares content or plans.

The companies/ folder keeps information for each business separate. I can give an agent access to business-a without giving access to business-b.

The engineering/ folder stores architecture documents and technical guides. For example, it can explain how a Kubernetes cluster works or how a Kafka platform is configured.

The security/ folder stores security controls, policies, questionnaire answers, and evidence references. Secrets and passwords do not belong here.

The runbooks/ folder explains how to respond to known operational problems.

The architecture-decisions/ folder explains why an important technical decision was made. This is useful because the final configuration does not always explain the reason behind it.

Document Metadata

Each document should have simple metadata:

---
title: "Production Kubernetes Architecture"
description: "Architecture and operational model of the production platform."
domain: "infrastructure"
owners: ["platform-team"]
tags: ["kubernetes", "production", "architecture"]
status: "active"
visibility: "internal"
sensitivity: "confidential"
last_reviewed: "2026-08-25"
review_after: "2026-11-25"
---

This metadata helps people and agents find the correct document. It can also support access control and document review reminders.

Publishing with Cloudflare

The repository stays private. Cloudflare Pages builds the MkDocs website when a change is merged.

Private Git repository
        ↓
Material for MkDocs build
        ↓
Cloudflare Pages
        ↓
Cloudflare Access
        ↓
Authenticated reader

Cloudflare Pages is only the publishing layer. Git and Markdown remain the real source of truth.

How AI Agents Read the Docs

A local agent can read the repository directly.

A remote agent may not have filesystem access. For this case, the AI toolkit can provide a Knowledge MCP server. This server can clone or read the documentation repository and expose safe tools:

knowledge.list_documents
knowledge.search
knowledge.read_document
knowledge.read_section
knowledge.find_by_tag
knowledge.find_related

Read access should be the default. Writing should use a separate approval flow:

knowledge.create_draft
knowledge.propose_update
knowledge.apply_approved_update

Repository Two: AI Toolkit

The second repository is a portable AI capability platform.

It should work with ChatGPT, Codex, Claude, Gemini, and local AI models. Important logic should not depend on one provider.

The main parts are:

  • Skills
  • MCP servers
  • Workflows
  • Policies
  • Profiles
  • Shared packages
  • Tests

AI Toolkit Structure

ai-toolkit/
├── skills/
│   ├── infrastructure/
│   │   ├── troubleshoot-kubernetes/
│   │   ├── review-terraform/
│   │   ├── design-kafka/
│   │   └── investigate-incident/
│   ├── development/
│   │   ├── build-ci-pipeline/
│   │   ├── review-pull-request/
│   │   └── debug-application/
│   ├── security/
│   │   ├── answer-pentest-questionnaire/
│   │   ├── perform-security-review/
│   │   └── collect-security-evidence/
│   ├── marketing/
│   │   ├── create-ad-campaign/
│   │   ├── review-ad-performance/
│   │   ├── perform-keyword-research/
│   │   └── write-seo-blog-post/
│   ├── business/
│   │   ├── prepare-commercial-offer/
│   │   ├── research-supplier/
│   │   └── qualify-sales-lead/
│   └── personal/
│       ├── write-personal-blog-post/
│       └── prepare-weekly-plan/
│
├── mcp-servers/
│   ├── knowledge/
│   ├── kubernetes/
│   ├── github/
│   ├── gitlab/
│   ├── cloud/
│   ├── cloudflare/
│   ├── domain-provider/
│   ├── google-ads/
│   ├── meta-ads/
│   ├── tiktok-ads/
│   ├── analytics/
│   ├── search-console/
│   └── cms/
│
├── workflows/
│   ├── infrastructure/
│   ├── development/
│   ├── security/
│   ├── marketing/
│   ├── business/
│   └── personal/
│
├── policies/
│   ├── default.yaml
│   ├── production.yaml
│   ├── marketing.yaml
│   ├── security.yaml
│   └── documentation.yaml
│
├── profiles/
│   ├── devops.yaml
│   ├── security.yaml
│   ├── marketing.yaml
│   ├── business.yaml
│   └── personal.yaml
│
├── packages/
│   ├── agent-runtime/
│   ├── workflow-engine/
│   ├── mcp-client/
│   ├── policy-engine/
│   ├── approval-engine/
│   └── audit-log/
│
├── adapters/
│   ├── codex/
│   ├── claude/
│   ├── gemini/
│   └── local/
│
├── templates/
├── scripts/
├── tests/
├── pyproject.toml
├── uv.lock
├── Taskfile.yml
└── .env.example

Skills: How the Agent Works

A skill explains how an agent should perform a task. It does not connect to an external API by itself.

For example, troubleshoot-kubernetes explains the troubleshooting process:

  1. Read the related architecture and runbook documents.
  2. Find the affected cluster and workload.
  3. Check events, pod status, logs, and metrics.
  4. Compare the live state with the expected state.
  5. Find the root cause from evidence.
  6. Suggest the lowest-risk solution.
  7. Require approval before changing production.

Each skill uses the common SKILL.md format:

troubleshoot-kubernetes/
├── SKILL.md
├── scripts/
├── references/
└── assets/

The skill should stay short. Detailed company and infrastructure information belongs in the documentation repository.

MCP Servers: Access to External Systems

An MCP server connects the agent to an external platform.

I do not need one MCP server for every action. I need one MCP server for each external system or clear platform boundary.

For example, the Kubernetes MCP server can provide:

kubernetes.list_pods
kubernetes.get_events
kubernetes.get_logs
kubernetes.get_manifest
kubernetes.get_metrics
kubernetes.rollout_restart

The Google Ads MCP server can provide:

google_ads.campaigns.list
google_ads.campaigns.create
google_ads.metrics.query
google_ads.budgets.update
google_ads.campaigns.pause

The MCP server provides the tools. The skill explains how to use them.

Workflows: Connecting Several Units

A workflow connects skills and MCP calls into a repeatable process.

For example, a daily advertising workflow can:

  1. Read yesterday's advertising results.
  2. Read analytics and conversion data.
  3. Compare spend, CPA, CTR, and ROAS.
  4. Use a review skill to find problems.
  5. Create safe actions.
  6. Apply low-risk changes.
  7. Request approval for high-risk changes.
  8. Save the report.

A Kubernetes incident workflow can:

  1. Search the documentation repository.
  2. Read the relevant architecture and runbook.
  3. Inspect the live cluster through Kubernetes MCP.
  4. Create an evidence-based diagnosis.
  5. Open an issue or incident record.
  6. Request approval before remediation.

Policies: Safe Automation

Agents should not have unlimited permission.

Low-risk operations can run automatically:

  • Read documentation
  • Read logs and metrics
  • Create reports
  • Create drafts

Medium-risk operations can run with limits:

  • Open an issue
  • Pause one bad keyword
  • Reduce an ad budget by a small amount

High-risk operations require approval:

  • Change production
  • Delete infrastructure
  • Publish an ad campaign
  • Increase a budget
  • Publish an article
  • Send a commercial offer

Policies should be enforced by code. They should not depend only on an AI prompt.

Profiles: Access for Each Type of Work

A profile selects the skills, MCP servers, documents, and policies for one purpose.

A DevOps profile can access infrastructure skills, Kubernetes MCP, cloud MCP, engineering documents, and production runbooks.

A marketing profile can access advertising skills, ad platform MCP servers, analytics, and marketing documents.

A security profile can access security review skills, security controls, questionnaire documents, and evidence references.

This reduces unnecessary access and keeps the agent context smaller.

Example Use Cases

Kubernetes Troubleshooting

User request
    ↓
Kubernetes troubleshooting skill
    ↓
Knowledge MCP reads architecture and runbooks
    ↓
Kubernetes MCP reads the live cluster
    ↓
Agent compares expected and live state
    ↓
Diagnosis and safe remediation proposal

CI Pipeline Builder

The CI pipeline skill reads the repository, detects the language and build system, selects a template, creates the pipeline, and validates it. GitHub or GitLab MCP is only needed when the agent must open a pull request or change the remote repository.

This means I do not need a special CI pipeline MCP server. Pipeline creation is a skill. GitHub access is an MCP integration.

Pentest Questionnaire

The questionnaire skill extracts the questions and searches the documentation for evidence. It must not invent an answer when evidence is missing. It marks the answer as complete, partial, or unknown and gives document references.

Personal Blog Post

The writing skill reads my writing style and previous decisions from the documentation repository. It can use analytics, search data, and CMS tools. The final article is created as a draft and requires approval before publishing.

Why Python and uv?

I do not need a pnpm workspace at the beginning.

Most MCP servers, workflow code, validation scripts, and the Knowledge MCP can be written in Python. I can use uv for dependency and workspace management.

If I later add a Next.js dashboard or TypeScript services, I can add pnpm only for those projects.

Portability

The system should not keep important logic inside Codex, Claude, or Gemini configuration.

The portable source remains:

SKILL.md files      = agent procedures
MCP servers         = external integrations
YAML workflows      = repeatable processes
Markdown documents  = knowledge
YAML policies       = safety rules

Provider adapters only install or generate the required client configuration.

This design allows me to change the AI model without rebuilding my tools and documentation.

Final Architecture

personal-docs
    ├── Markdown knowledge
    ├── MkDocs website
    └── Cloudflare publishing

ai-toolkit
    ├── Agent skills
    ├── MCP servers
    ├── Workflows
    ├── Policies
    └── Provider adapters

Knowledge MCP
    └── Connects ai-toolkit to personal-docs

The final result is not only a group of prompts. It is a portable system for technical work, business tasks, marketing, security, documentation, and personal automation.

The documentation repository stores what I know. The AI toolkit defines how agents can use that knowledge and act safely.