识海 · knowledge-ocean

A shareable skill that guides an agent to help a person build their second brain — a personal Obsidian knowledge base designed around how they think and work, not around a template.

The core identity is the principle structure follows use, never convention: the structure grows out of the person's purpose, habits, and domains — discovered by asking, never assumed.

knowledge-ocean is written to the agentskills spec, so it works across Claude Code, Codex, Gemini CLI, and Copilot CLI. It describes actions, never harness-specific tool names.

What it does

The skill runs in one of two modes, chosen by detecting the situation:

• Setup mode — the vault is empty (or has no instruction file and no notes). The agent interviews the person (purpose, capture habits, domains, organization preference, frequency, self-knowledge, language), designs a structure from the answers, scaffolds folders and templates, and generates the operating manual. Six steps: detect → interview → design → scaffold → generate instruction file(s) → handoff.
• Adapt mode — the vault already has content or a structure. The agent detects what exists and writes an instruction file that matches reality. It never restructures, renames, moves, or deletes anything; improvements are offered only as proposals the person can approve.

Install

Install by symlinking the skill into your runtime's skills directory, so edits to the repo are picked up immediately.

# Claude Code
ln -sfn <repo>/skills/knowledge-ocean ~/.claude/skills/knowledge-ocean

# Codex / Copilot CLI / Gemini CLI (cross-runtime alias)
ln -sfn <repo>/skills/knowledge-ocean ~/.agents/skills/knowledge-ocean

# Gemini CLI (native location)
ln -sfn <repo>/skills/knowledge-ocean ~/.gemini/skills/knowledge-ocean

Replace <repo> with where you cloned this repository — e.g. ~/code/knowledge-ocean.

The skill can be installed into more than one of these locations at once; pick whichever your runtime reads. Gemini CLI can use either ~/.agents/skills/ or ~/.gemini/skills/.

How to use

Open a terminal in (or point your agent at) the Obsidian vault you want to work on, then just ask:

• First run on an empty vault — say something like "I want to build a personal knowledge base, help me set it up." The skill detects the empty vault and runs setup mode: it interviews you a question or two at a time, designs a structure from your answers, scaffolds it, and generates your operating manual.
• On an existing vault — say something like "Look at this vault and give me an operating manual." The skill detects the existing structure and runs adapt mode: it writes the manual to match what's already there, and offers workflow modules without touching your notes.

What gets generated

Depending on the mode and runtime:

• CLAUDE.md — the operating manual for Claude Code sessions.
• AGENTS.md — the same manual, for Codex / Copilot / Cursor, and as the cross-runtime standard. Generated alongside CLAUDE.md.
• GEMINI.md — the same manual, additionally, when the session runs under Gemini CLI.

The body of the manual is identical across runtimes; only the filename differs. It contains the vault's structure map, the enabled workflows, note conventions (naming, frontmatter, wikilinks, tags, status), the don'ts, and the vault's absolute path.

• .kb/ — the hidden folder where enabled workflow modules are copied. The skill ships six optional modules — capture, digest, retrieve, organize, reflect, self-interview — enabled per your needs, never all at once by default. The manual points at these copies.

Note on language: the six workflow modules ship in Chinese (Chinese-first content, per the v1 scope), while the interview and the generated manual follow the user's language.

Documentation

• Design spec: docs/superpowers/specs/2026-09-01-knowledge-ocean-design.md
• Implementation plan: docs/superpowers/plans/2026-09-01-knowledge-ocean.md
• Scenario suite (how to test the skill): test/README.md