主题和 Skill

这篇文章只记录主题和 agent skill 的维护边界。整体链路看 整体工作流，技术栈原因看 技术选型，搭建流程看 实施步骤。

Lucode 主题

站点使用 lucode-starlight 作为 Starlight 主题层。它负责：

• 左侧侧边栏。
• 搜索、目录、分页和页脚样式。
• Markdown、代码块和文档组件的视觉风格。

核心配置在 astro.config.mjs：

lucode({
  footerText: 'NeuroStack',
})

顶部不再放分类菜单，统一使用左侧目录切换。

侧边栏规则

侧边栏使用 Lucode 主题内置实现，不维护 src/components/Sidebar.astro。

astro.config.mjs 中只维护结构：

• AI 自动化个人知识库：这个主题下的概览和文章。
• 其他：raw HTML 页面和暂不适合归入具体主题的入口。

公开 Wiki 不再使用“项目”这种通用大分类。长期知识主题可以直接成为侧边栏大分类；写作、发布和模板说明不作为公开文章维护，而是进入全局 skill。

标题规则

页面 title 会同时影响：

• 页面 H1。
• 浏览器标题。
• Starlight/Lucode 侧边栏文本。
• 搜索结果显示。

因此标题要短，避免在侧边栏换行挤压布局。上下文放在 description 或正文开头。

推荐：

---
title: 技术选型
description: 记录 AI 自动化个人知识库为什么选择当前技术栈。
---

不推荐：

---
title: AI 自动化个人知识库：技术选型
---

内容 Schema

src/content.config.ts 使用 Starlight 的 docsSchema，并通过 Lucode 的 ExtendDocsSchema 扩展。

普通文章保持最小 frontmatter：

---
title: 标题
description: 一句话说明内容。
---

只有使用 Lucode 主题特定能力时，才增加额外字段。

自定义页面入口

复杂页面不要塞进普通 Markdown：

• 需要组件：用 MDX。
• 需要页面级布局：放 src/pages/custom/。
• 需要完全自定义 HTML：放 src/pages/raw-html/。

raw HTML 页面必须在侧边栏中有入口。

全局 Skill

全局 skill 位于：

/Users/ryanchen/.codex/skills/personal-wiki-publish/

触发场景：

• 用户明确说要保存到笔记、知识库、文章或主题记录。
• agent 判断某段知识值得长期保存。

skill 的职责是保证 agent 写入内容时遵守仓库约定：选目录、写中文 frontmatter、保持导航一致、构建验证。

Guardrails

• 默认写中文。
• 普通文章优先放进现有主题分类；没有合适分类时再创建清晰的新主题分类。
• 不发布隐私、密钥、账号或未确认可公开的材料。
• 不为普通文章手动加侧边栏条目。
• 不新增 Header 或 Sidebar override，除非主题配置无法表达需求。
• 没有明确要求发布时，不提交、不推送、不触发线上部署。