Skip to content

DO NOT MERGE - for reference only #17

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
kevinslin wants to merge 2 commits into from
Closed

DO NOT MERGE - for reference only #17

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
15e8a63
docs(technical-documentation): specialize for OpenClaw
kevinslin May 16, 2026
bf1b624
docs(technical-documentation): avoid private memory references
kevinslin May 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 84 additions & 27 deletions skills/technical-documentation/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,50 +1,107 @@
---
name: technical-documentation
description: Build and review high-quality technical docs as well as agent instruction files in your repository.
description: Build and review OpenClaw documentation, docs IA, source-backed docs diffs, and repo governance docs.
license: AGPL-3.0-only
metadata:
source: "https://github.com/vincentkoc/dotskills"
---

# Technical Documentation
# OpenClaw Technical Documentation

## Purpose

Produce and review technical documentation that is clear, actionable, and maintainable for both humans and agents, including contributor-governance files and agent instruction files.
Produce and review OpenClaw documentation that is accurate, helpful, concise,
maintainable, and source-backed. Use this skill for product docs, docs IA,
docs preservation audits, OpenClaw governance docs, and docs-as-code
validation.

## When to use

- Creating or overhauling docs in an existing product/codebase (brownfield).
- Building evergreen docs meant to stay accurate and reusable over time.
- Reviewing doc diffs for structure, clarity, and operational correctness.
- Updating or reviewing AGENTS.md and/or CONTRIBUTING.md to keep agent and contributor workflows aligned with current repo practices.
- Improving repository onboarding/docs that include contribution instructions, issue templates, PR flow, and review gates.
- Designing governance documentation strategy for repos with alias instruction files (for example `CLAUDE.md`, `AGENT.md`, `.cursorrules`, `.cursor/rules/*`, `.agent/`, `.agents/`, `.pi/`) where `CLAUDE.md` is treated as a canonical policy source and `AGENTS.md` should be kept as compatibility alias if present.
- Writing or reviewing OpenClaw docs under `docs/**`, including plugin,
provider, channel, CLI, SDK, Gateway, migration, setup, troubleshooting, and
reference pages.
- Reviewing docs navigation and routing in `docs/docs.json`, redirects,
generated references, and published docs URLs.
- Refactoring docs while preserving source coverage from older pages, PRs,
code comments, specs, or current implementation.
- Reviewing docs diffs for the OpenClaw rubric: accurate, helpful, concise,
complete within scope, maintainable, and findable.
- Updating OpenClaw repository governance docs such as root or scoped
`AGENTS.md`, `CONTRIBUTING.md`, `CODEOWNERS`, docs-related
`.github/labeler.yml`, or docs-facing changelog entries.
- Aligning docs with current behavior, shipped behavior, tests, source
contracts, or upstream dependency docs.
- Producing a report-only docs review, or applying high-confidence
documentation fixes when the user asks for implementation.

## Workflow

1. Classify task: `build` or `review`; context: `brownfield` or `evergreen`.
2. Read `references/agent-and-contributing.md` for agent instruction and `CONTRIBUTING.md` workflow rules (inventory, canonical/alias mapping, dual-mode balance, deliverable standards, and precedence/conflict handling).
3. Read `references/principles.md` for the governing ruleset (Matt Palmer & OpenAI).
4. For build tasks, follow `references/build.md`.
5. For review tasks, follow `references/review.md`.
6. Use `references/tooling.md` when platform/tooling choices affect recommendations.
7. In brownfield mode, prioritize compatibility with current docs IA, tooling, and release state.
8. In evergreen mode, prioritize timeless wording, update strategy, and durable structure.
9. Return deliverables plus validation notes and remaining gaps.
1. Classify the task: `write`, `review`, `refactor`, `ia`, `audit`, or
`governance`.
2. Read scoped OpenClaw instructions before subtree work. For docs/user-visible
work, run `pnpm docs:list`, then read only the relevant docs and source
surfaces.
3. Identify the reader and page type before writing: overview, quickstart, topic
page, guide, API/SDK/CLI reference, testing guide, troubleshooting page,
maintainer note, or governance file.
4. Read `references/principles.md` for OpenClaw docs principles and page-type
rules.
5. For build/refactor/IA tasks, follow `references/build.md`.
6. For review tasks, follow `references/review.md`.
7. For AGENTS/CONTRIBUTING/governance work, follow
`references/agent-and-contributing.md`.
8. Use `references/tooling.md` when docs platform, Mintlify routing, generated
references, or validation commands affect the outcome.
9. Verify claims against source, tests, current behavior, shipped behavior, or
upstream dependency contracts. Accuracy is a hard gate.
10. For moved or rewritten docs, run a preservation-minded audit: identify
source units, destination ownership, moved sections, dropped sections, and
any missing coverage.
11. Apply high-confidence fixes only when the user asked for implementation. For
report-only requests, return findings and validation gaps without editing.
12. Return the changed draft or review findings with exact validation notes and
any relevant `https://docs.openclaw.ai/...` URL(s).

## Sub-agent orchestration guidance

Use sub-agents only when explicitly available and the docs task is broad enough
to benefit from parallel discovery. Merge all outputs into one OpenClaw-specific
recommendation or patch plan.

- `inventory-agent` -> `agents/inventory-agent.md`: map OpenClaw docs files,
`docs/docs.json`, generated references, redirects, and missing paths.
- `governance-agent` -> `agents/governance-agent.md`: review OpenClaw
`AGENTS.md`, `CONTRIBUTING.md`, `CODEOWNERS`, labeler, changelog, and
scoped-instruction alignment.
- `docs-framework-agent` -> `agents/docs-framework-agent.md`: verify
Mintlify/file/URL routing, main-reader-path versus `Reference` placement, and
generated-doc visibility.
- `synthesis-agent` -> `agents/synthesis-agent.md`: merge findings into one
prioritized OpenClaw docs fix plan.

## Inputs

- Doc type (tutorial, how-to, reference, explanation) and audience.
- Task class and desired mode (`apply-fixes` or `report-only`).
- OpenClaw reader: user, operator, plugin author, contributor, maintainer, or
release owner.
- Page type and docs surface (`docs/**`, `docs/docs.json`, README, generated
reference, AGENTS, CONTRIBUTING, labeler, changelog).
- File scope or diff scope.
- Docs framework/tooling constraints (Fern, Mintlify, Sphinx, etc.).
- Build/review mode and brownfield/evergreen intent.
- Target agent and human compatibility intent.
- Source-of-truth contracts: code path, command output, tests, shipped behavior,
upstream docs/types, spec, or prior page.
- Validation expectations: docs-list, MDX, links, glossary, formatting,
diff check, generated-doc checks, or behavior tests.
- Preservation requirements for rewrites: source ref, destination pages,
keep/drop/move matrix, and audit depth.

## Outputs

- Updated draft or review findings with clear next actions.
- Validation notes (what was checked, what remains).
- Navigation/maintenance recommendations for long-term quality.
- Governance-doc alignment summary when AGENTS/CONTRIBUTING were touched.
- Agent instruction-surface map (primary file, alias files, Codex/Claude/Cursor handling plan).
- Updated OpenClaw draft or source-backed review findings.
- For reviews: blocking findings first, then non-blocking improvements, then
validation notes.
- For docs IA/refactors: page-type classification plus
keep/drop/move/destination matrix.
- For preservation audits: source coverage summary, mapped destinations, gaps,
and any unsupported drops.
- For governance work: scoped-instruction and contributor-flow alignment summary.
- Validation notes with exact commands run, commands not run, and why.
6 changes: 3 additions & 3 deletions skills/technical-documentation/agents/openai.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
interface:
display_name: "Technical Documentation"
short_description: "Build and review technical documentation for brownfield and evergreen systems."
display_name: "OpenClaw Documentation"
short_description: "Build and review OpenClaw docs, docs IA, source-backed diffs, and governance docs."
icon_small: "./assets/icon.jpg"
icon_large: "./assets/icon.jpg"
brand_color: "#111827"
default_prompt: "Build or review technical documentation with a clear, maintainable, and production-ready workflow."
default_prompt: "Build or review OpenClaw docs with source-backed accuracy and docs-as-code validation."

policy:
allow_implicit_invocation: true
197 changes: 86 additions & 111 deletions skills/technical-documentation/references/agent-and-contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,111 +1,86 @@
# AGENT and CONTRIBUTING Principles

This reference consolidates the core rules for agent-policy and contributor-governance docs.

You must:
1. Discover repo-level and nested instruction files with:
`rg --files -g 'AGENTS.md' -g 'CONTRIBUTING.md' -g 'CLAUDE.md' -g 'AGENT.md' -g '.cursor/rules/*' -g '.cursorrules' -g '.agent/**' -g '.agents/**' -g '.pi/**' -g 'AGENTS.*.md'`
2. Read the root and nearest-scope `AGENTS.md`/`CONTRIBUTING.md` pair before editing.
3. If alias files exist, normalize to one canonical source (`AGENTS.md` preferred when present; otherwise nearest alias), plus compatibility pointers or explicit symlink notes.
4. Document conflicting instructions and precedence decisions.

## GitHub + AGENTS baseline

Source: https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors
Source: https://agents.md/
Source: https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/
Source: https://cobusgreyling.substack.com/p/what-is-agentsmd
Source: https://www.infoq.com/news/2025/08/agents-md/

Use these as default operating principles:

1. Keep `CONTRIBUTING.md` discoverable and actionable (`.github`, root, or `docs`).
2. Keep agent instructions concrete: real commands, real paths, clear boundaries.
3. Use explicit behavior boundaries for agents: `Always`, `Ask first`, `Never`.
4. Keep contributor and agent rules aligned with actual repository workflows.
5. Ensure clear guidance is provided to agents on if, when and how to raise issues and pull requests.

## Canonical and alias policy

Source: https://agents.md/
Source: https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/

1. Treat `AGENTS.md` as canonical when present.
2. If `AGENTS.md` is absent, treat the nearest alias file as canonical.
3. Keep compatibility surfaces explicit: `AGENTS.md`, `AGENT.md`, `.cursorrules`, `.cursor/rules/*`, `.agent/`, `.agents/`, `.pi/`.
4. If aliases are used, document how they map back to canonical policy (or symlink when supported).

## Context-awareness by agent platform

Source: https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md
Source: https://github.com/openai/codex/blob/main/AGENTS.md

1. For Cursor and Claude-style glob consumers, keep rule files narrow and bounded.
2. Avoid over-referencing large path sets that inflate context for glob-based agents.
3. For Codex-style workflows, prefer explicit file references and deterministic commands.
4. Keep long runbooks outside top-level policy files; link to scoped docs.
5. Ensure all agents have a happy path regardless so ensuring everything works across Codex, Claude and other coding agents.

## Dual-mode and deliverable standards

Source: https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/
Source: https://agents.md/
Source: https://github.com/openai/codex/blob/main/AGENTS.md
Source: https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md

1. Author one shared policy core (same commands, boundaries, and precedence) for all agents.
2. For Cursor/Claude-style agents, expose that core through glob-driven and bounded files (small `AGENTS.md`/rule surface).
3. For Codex, expose that same core through explicit file references with precise scope.
4. Where styles diverge, prefer the smallest common structure that satisfies both and avoid duplicating policy text.
5. Treat AGENTS/CONTRIBUTING as first-class deliverables when in scope.
6. Preserve required structure, constraints, and examples from existing files.
7. Align wording and commands with active repository instructions.

## Discovery

1. Agents prefer simple terminal commands so having a well defined `make *` or `npm run *` is ideal
2. Agents can discover terminal commands through shell completion so providing shell completion helps

## CONTRIBUTING size and scope control

Source: https://contributing.md/how-to-build-contributing-md/
Source: https://blog.codacy.com/best-practices-to-manage-an-open-source-project
Source: https://mozillascience.github.io/working-open-workshop/contributing/
Source: https://github.com/openclaw/openclaw/blob/main/CONTRIBUTING.md

1. Keep root `CONTRIBUTING.md` focused on setup, issue flow, PR flow, testing, and review gates.
2. Use issue/PR template links instead of embedding every process detail inline.
3. When the file grows too large, split by domain and link from root.
4. Move any large content into docs if avalible (for example Mintlify/Fern/Sphinx workflows) to avoid large contributor guide.
5. Optimize for agent/machine readability as well as humans.

## Example repos to emulate

Source: https://github.com/openclaw/openclaw/blob/main/AGENTS.md
Source: https://github.com/openclaw/openclaw/blob/main/CONTRIBUTING.md
Source: https://github.com/openclaw/openclaw/blob/main/VISION.md
Source: https://github.com/openai/codex/blob/main/AGENTS.md
Source: https://github.com/processing/p5.js/blob/main/AGENTS.md
Source: https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md
Source: https://github.com/agentsmd/agents.md/blob/main/AGENTS.md
Source: https://github.com/rails/rails/blob/main/CONTRIBUTING.md
Source: https://github.com/kubernetes/kubernetes/blob/master/CONTRIBUTING.md
Source: https://github.com/atom/atom/blob/master/CONTRIBUTING.md
Source: https://github.com/github/docs/blob/main/CONTRIBUTING.md
Source: https://github.com/facebook/react/blob/main/CONTRIBUTING.md

1. OpenClaw: strong real-world alias policy and AGENTS/CONTRIBUTING/VISION cohesion.
2. OpenAI Codex: strict command discipline and explicit scope control.
3. p5.js: explicit AI-policy guardrails in agent instructions.
4. Vercel + agentsmd spec: compact, context-efficient AGENTS patterns.
5. Rails/Kubernetes/Atom/GitHub Docs/React: contributor guidance patterns at different project scales.

## Practical merge policy

When these rules conflict:

1. Preserve contributor and reader task success first.
2. Preserve instruction clarity and unambiguous boundaries second.
3. Preserve long-term maintainability and context-efficiency third.
4. Add extra agent optimization only if it does not reduce human clarity or there is explict need.
5. Use your judgement as the expert.
# OpenClaw Agent and Contributor Docs

Use this reference for OpenClaw `AGENTS.md`, `CONTRIBUTING.md`, CODEOWNERS,
labeler, changelog, and adjacent governance documentation.

## Required discovery

Before editing governance docs, discover the relevant instruction scope:

```bash
rg --files -g 'AGENTS.md' -g 'CLAUDE.md' -g 'CONTRIBUTING.md' -g 'CODEOWNERS' -g '.github/labeler.yml'
```

Then read:

1. root `AGENTS.md`
2. nearest scoped `AGENTS.md` for the files being edited
3. `CONTRIBUTING.md` when contributor workflow is affected
4. `CODEOWNERS`, labeler, changelog, or workflow docs when the change touches
ownership, labels, PR flow, releases, channels, plugins, apps, or docs
surfaces

## OpenClaw source of truth

- `AGENTS.md` is canonical for Codex repository instructions.
- Scoped `AGENTS.md` files narrow or add rules for their subtree.
- When creating a new `AGENTS.md`, add a sibling `CLAUDE.md` symlink and edit
`AGENTS.md` only.
- Do not treat `CLAUDE.md`, `.cursor`, `.cursorrules`, or other generic
agent-file conventions as canonical unless the active OpenClaw instructions
explicitly say so.
- Do not add `.cursor -> .agents` compatibility symlinks as a default OpenClaw
docs operation.

## Governance writing rules

- Telegraph style for root policy: short, concrete, repo-specific.
- Keep long runbooks out of root policy; route them to scoped repo docs or
dedicated bundled references.
- Include real commands and real repo paths.
- Prefer boundaries over broad advice: what is allowed, what needs owner review,
and what is never allowed.
- Keep product/docs/UI wording aligned with OpenClaw root policy: use
"plugin/plugins"; `extensions/` is internal except in file paths.
- Never print secrets, credentials, live config, real phone numbers, or private
artifacts.

## Contributor workflow checks

For `CONTRIBUTING.md` or contributor-facing guidance:

- Verify setup, install, build, test, lint, docs, and PR commands match current
repo wrappers.
- Keep issue triage, PR expectations, review gates, and validation commands
actionable.
- Link to deeper docs instead of embedding every domain runbook in the root
contributor guide.
- Do not contradict scoped `AGENTS.md`, CODEOWNERS, or release/security policy.

## Labeler, ownership, and changelog impact

- New channel/plugin/app/doc surfaces may require `.github/labeler.yml` and
GitHub label updates.
- Larger behavior/product/security/ownership changes need owner review.
- Docs changes tied to behavior/API/CLI/config changes should align with the
changelog policy for that change.
- Contributor PR authors should not add OpenClaw changelog entries unless the
maintainer workflow explicitly asks for it.

## Conflict handling

When governance sources disagree:

1. Prefer the active root `AGENTS.md`.
2. Apply nearest scoped `AGENTS.md` rules for files under that scope.
3. Prefer current repo commands and source behavior over stale prose.
4. If a rule would cause unsafe git mutation, credential exposure, broad cleanup,
or owner-boundary violations, stop and ask.
5. Record the conflict and the smallest proposed fix.

## Deliverables

- State which governance files were read.
- Summarize any policy conflicts and the selected precedence.
- For edits, include exact validation commands run or skipped.
- For report-only reviews, list blocking policy drift first, then cleanup items.
Loading