add skills/docs

skills/docs/README.md

@@ -0,0 +1,9 @@
+# Docs Skill
+
+This directory defines the rules and workflow for maintaining documentation under `docs/`.
+
+- Source of truth for structure: `docs/schema.md`
+- Skill definition: `skills/docs/skill.md`
+- Workflow: `skills/docs/workflow.md`
+- Rules: `skills/docs/rules.md`
+- Examples: `skills/docs/examples.md`

skills/docs/examples.md

@@ -0,0 +1,29 @@
+# Examples
+
+## Example 1: Update a specific doc file
+
+Input:
+- User: "Update `docs/usage/config.md` to match current config keys."
+
+Expected behavior:
+- Read `docs/schema.md`.
+- Edit only `docs/usage/config.md`.
+- Use evidence from `config/` and `internal/rag/config/`.
+
+## Example 2: Insufficient information
+
+Input:
+- User: "Document the new streaming API."
+
+Expected behavior:
+- Search the repo for evidence of a streaming API.
+- If not found, respond: missing implementation evidence; request the source file or clarify.
+
+## Example 3: Schema constraint
+
+Input:
+- User: "Add a new doc at docs/how-to/streaming.md."
+
+Expected behavior:
+- Refuse, citing `docs/schema.md` as the only allowed structure.
+- Ask the user to update schema first if needed.

skills/docs/rules.md

@@ -0,0 +1,9 @@
+# Hard Rules
+
+1. Do not change `docs/` structure.
+2. Do not add files not listed in `docs/schema.md`.
+3. Do not edit documentation files the user did not explicitly specify.
+4. Do not invent features, APIs, or behavior.
+5. Do not rely on external sources.
+6. Do not modify code or non-doc files.
+7. Use minimal necessary changes only.

skills/docs/schema.md

@@ -0,0 +1,61 @@
+# Docs Structure Source
+
+The documentation structure is defined **only** by `docs/schema.md` in the repository root. This skill does not redefine or override that schema.
+
+Rules:
+
+- Treat `docs/schema.md` as immutable.
+- Do not add, remove, rename, or move files under `docs/`.
+- Do not create documentation files that are not listed in `docs/schema.md`.
+
+这是唯一合法的文档结构来源。不得新增、删除、重命名任何目录或文件。
+
+docs/
+├─ README.md
+├─ getting-started/
+│  ├─ introduction.md
+│  ├─ quickstart.md
+│  ├─ installation.md
+│  └─ concepts.md
+├─ architecture/
+│  ├─ overview.md
+│  ├─ components.md
+│  ├─ design-decisions.md
+│  └─ roadmap.md
+├─ usage/
+│  ├─ cli.md
+│  ├─ config.md
+│  ├─ deployment.md
+│  └─ examples.md
+├─ api/
+│  ├─ overview.md
+│  ├─ auth.md
+│  ├─ endpoints.md
+│  └─ errors.md
+├─ integrations/
+│  ├─ databases.md
+│  ├─ cloud.md
+│  └─ ai-providers.md
+├─ advanced/
+│  ├─ performance.md
+│  ├─ security.md
+│  ├─ scalability.md
+│  └─ customization.md
+├─ development/
+│  ├─ contributing.md
+│  ├─ dev-setup.md
+│  ├─ testing.md
+│  └─ code-structure.md
+├─ operations/
+│  ├─ logging.md
+│  ├─ monitoring.md
+│  ├─ backup.md
+│  └─ troubleshooting.md
+├─ governance/
+│  ├─ license.md
+│  ├─ security-policy.md
+│  └─ release-process.md
+└─ appendix/
+   ├─ faq.md
+   ├─ glossary.md
+   └─ references.md

skills/docs/skill.md

@@ -0,0 +1,49 @@
+# Documentation Maintainer Skill
+
+## Purpose (Scope)
+This skill defines how the AI maintains documentation under `docs/` **without** changing its structure. It exists to keep `docs/` accurate and consistent with the current repository while following `docs/schema.md` as the only source of truth for allowed files and layout.
+
+## Out of Scope
+- Creating, deleting, renaming, or moving files in `docs/`
+- Writing product marketing content or future plans
+- Modifying code or non-documentation files
+- Inferring features not present in the repository
+
+## Inputs
+- User request describing what docs need updating or clarifying
+- Repository files that provide evidence for documentation changes
+- `docs/schema.md` (structure constraint)
+
+## Outputs
+- Updated Markdown content **only** in user-specified documentation files
+- A short report of what was changed and which sources in the repo were used
+- If blocked: a clear statement of missing information and what evidence is needed
+
+## Workflow
+1. **Confirm constraints**
+   - Read `docs/schema.md` and treat it as immutable structure.
+   - Identify which doc files the user explicitly asked to change.
+
+2. **Collect evidence**
+   - Locate relevant code/config files using repository search.
+   - Do not use external sources.
+
+3. **Draft minimal changes**
+   - Update only the user-specified doc files.
+   - Keep changes minimal and strictly factual.
+
+4. **Verify consistency**
+   - Ensure every new statement can be traced to the repo.
+   - Check that the doc structure matches `docs/schema.md`.
+
+5. **Deliver**
+   - Provide a brief change summary and cite repo file paths used as evidence.
+   - If information is insufficient, stop and request the missing sources.
+
+## Hard Rules (Must Not Do)
+- Do not modify `docs/` structure (no add/delete/rename/move).
+- Do not create files not listed in `docs/schema.md`.
+- Do not edit docs files the user did not explicitly specify.
+- Do not invent or extrapolate features, APIs, or behavior.
+- Do not use or reference external systems/tools not present in the repo.
+- Do not change code or non-doc files.

skills/docs/workflow.md

@@ -0,0 +1,27 @@
+# Workflow
+
+Follow this process for any documentation maintenance request.
+
+1. **Read constraints**
+   - Open `docs/schema.md` and confirm the allowed structure.
+   - Identify which doc files the user explicitly requested to change.
+
+2. **Collect evidence**
+   - Locate relevant code/config files in the repository.
+   - Do not use external sources.
+
+3. **Plan minimal edits**
+   - Change only user-specified doc files.
+   - Avoid unrelated formatting or wording changes.
+
+4. **Apply changes**
+   - Update content with strictly factual statements supported by the repo.
+   - Keep the changes minimal and local to the request.
+
+5. **Verify**
+   - Ensure every new statement can be traced to repository evidence.
+   - Ensure no schema violations were introduced.
+
+6. **Report**
+   - Summarize changes and list evidence files used.
+   - If blocked, state what is missing and stop.