From pgedge-skills
Use this skill whenever the user wants to write, edit, review, or structure pgEdge documentation. This includes: creating new documentation files, editing existing docs, setting up MkDocs project structure from the pgEdge template, writing README files, formatting markdown content, creating changelogs, structuring navigation, or reviewing docs for style compliance. Trigger whenever the user mentions writing docs, documentation, README, mkdocs, changelog, or asks to review/fix doc formatting. Also trigger when setting up a new project's documentation scaffolding. Do NOT trigger for code-only changes that happen to be in markdown (e.g., editing a CLAUDE.md or DESIGN.md with development guidelines).
How this skill is triggered — by the user, by Claude, or both
Slash command
/pgedge-skills:pgedge-docsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill ensures all pgEdge documentation follows consistent style,
This skill ensures all pgEdge documentation follows consistent style, formatting, and structural conventions. These rules apply across all pgEdge projects and repositories.
When setting up documentation for a new pgEdge project, copy the
template files from the template/ directory alongside this SKILL.md
file into the target project. Use cp -r to copy the entire template
directory tree in one operation so that all subdirectories are created
automatically.
The template provides a minimal MkDocs Material configuration with pgEdge branding:
template/
mkdocs.yml # MkDocs Material config
LICENSE.md # Root copy of PostgreSQL License
docs/
index.md # Landing page
changelog.md # Keep a Changelog format
LICENSE.md # PostgreSQL License (for MkDocs)
img/
favicon.ico # pgEdge favicon
logo-dark.png # Dark mode logo
logo-light.png # Light mode logo
overrides/
partials/
logo.html # Light/dark logo switcher
stylesheets/
extra.css # Light/dark mode CSS
When creating documentation scaffolding for a new project:
template/ contents into the project root.mkdocs.yml, replace <PROJECT NAME> with the actual project
name and <PROJECT REPO> with the GitHub repository name. Strip a
leading "pgEdge " (case-insensitive) from the project name before
substituting — the theme already renders the pgEdge logo, and
site_name: pgEdge X would double it up next to the logo. The
GitHub repo name (<PROJECT REPO>) is whatever the user actually
uses for the repository slug; do not normalize that.docs/index.md, replace <PROJECT NAME> with the project name.docs/changelog.md, replace <PROJECT NAME> with the project
name.nav: section in mkdocs.yml to match the project's
documentation structure..md files in the docs/ directory.The template mkdocs.yml uses MkDocs Material with:
admonition, pymdownx.details, and pymdownx.superfences
markdown extensions.The nav: section defines the left-hand table of contents. Keep it
synchronized with the actual files in docs/.
The primary pgEdge documentation site (the pgedge-docs repository,
published at docs.pgedge.com) uses the MkDocs multirepo plugin to
import documentation from individual project repositories. Each
project is imported via a !import directive in the primary site's
mkdocs.yml referencing the project's GitHub repo and branch:
- v1.0: '!import https://github.com/pgEdge/project.git?branch=v1.0'
This means each project's mkdocs.yml and docs/ folder must be
self-contained and valid on their own. Do not add configuration that
only works in the primary site context (e.g., multirepo plugin,
redirects plugin, analytics, consent banners, nav_categories,
or versioned_docsets).
The following product names are proper nouns; treat them as such. As a rule, omit "the" in front of the name unless using it as an adjective to describe software, files, or other artifacts:
The exception is "the Control Plane" which always takes the article.
my_file.md (lowercase,
underscores).docs/ folder or its subdirectories.README.md,
CONTRIBUTING.md).LICENSE.md file must be stored inside the docs/ folder;
aliases from other folders do not work properly with MkDocs.Each project should have:
docs/
index.md # Main landing page
changelog.md # Release notes in Keep a Changelog format
LICENSE.md # PostgreSQL License
img/ # Images and branding assets
overrides/ # MkDocs Material overrides
stylesheets/ # Custom CSS
[text](URL) must remain unbroken on a single line, even if
it exceeds 79 characters. Break prose before or after the link.# is added to the navigation pane on the upper-right
side of the documentation page.#).##) for sections.Correct example:
The view includes:
- the total entries and expired entries.
- the total cache size in megabytes.
- the average access count per entry.
Incorrect example:
The view includes the following metrics:
- The view shows the total entries and expired entries.
- The view shows the total cache size in megabytes.
- The view shows the average access count.
Use an explanatory sentence before every code block that ends with a colon, identifying the command and describing what it does.
Use single backticks for a single command or line of code:
`SELECT * FROM my_table;`
Use fenced code blocks with a language tag for multi-line code:
```sql
SELECT * FROM code;
```
stdio, stdin, stdout, and stderr should always be in
backticks (courier font).
Capitalize command keywords; use lowercase for variables.
Include links to third-party software installation and documentation pages where referenced.
Include links to the pgEdge GitHub repo when referring to cloning the repo or working on the project.
Do not create links to github.io.
[text](URL) syntax must stay on one line.If a page has a "Features" or "Overview" section after the introductory paragraph, do not start with a heading. Instead, use a sentence like: "The MCP Server includes the following features:", followed by a bulleted list.
## Next Steps) at the end of
tutorial and conceptual guide documents.Every public repository should have a README.md with the following
structure.
#) with the project name.## Table of Contents heading.docs/.The following section titles are exceptions to the gerund rule:
Top-level entries should mirror the mkdocs.yml nav and link to the
same .md files; second-level links may reference anchors within a
file (docs/file_name.md#section_name):
Include a short introduction describing the project, what it does, and why someone might use it.
The following sections should appear in order:
## Installation - An introductory sentence, then:
## Configuration - An introductory sentence, then:
## Using <Project Name> - An introductory sentence, then:
## Documentation - An introductory sentence, then:
## Support & Resources:
## Contributing (if applicable):
Include a link to docs.pgedge.com: "For more information, visit docs.pgedge.com."
## License (at the end):
Copyright years appear in three template files: mkdocs.yml,
LICENSE.md, and docs/LICENSE.md. All three use the
<CURRENT YEAR> placeholder. When setting up a new project or
editing an existing one, replace every <CURRENT YEAR> placeholder
with the actual current year.
Use the Keep a Changelog format with
Semantic Versioning. The
template file at template/docs/changelog.md provides the starting
structure.
The nav: section in mkdocs.yml defines the left-hand navigation
pane. It should mirror the README TOC and may include:
nav:
- Architecture Guide
- Best Practices Guide
- Installing this Project:
- Getting Started/Quick Start
- Building the Project:
- Prerequisites
- Installation
- Configuring this Project:
- Advanced Configuration
- Upgrading the Project
- Using the Project:
- Connecting to the Project
- Project Usage Instructions
- Using Project Management Features:
- Modifying the Installation
- Monitoring/Logging
- Performance
- Function Reference
- API Reference
- Troubleshooting
- FAQ
- Release Notes
- Developer Resources
Nested details can be in the same file as the parent section (e.g., Prerequisites can live in the same file as Installation).
After writing or editing documentation, launch a sub-agent to verify that the documentation accurately and completely reflects what the code actually implements. This verification step is mandatory; do not skip it.
The sub-agent should read the relevant source code and confirm:
After completing documentation changes, launch a sub-agent with a prompt that identifies the documentation file(s) and the corresponding source file(s), and asks the sub-agent to:
Fix all discrepancies before considering the documentation complete.
When reviewing documentation, verify:
# heading per fileThese rules apply when authoring help content rendered inside an
application's help panel. The section activates when the user mentions
"in-app help", "online help", "help panel", "help content", or "help
pages", or when the working project contains
client/src/components/HelpPanel/pages/ (an artifact of the
pgedge-webapp skill).
Each help page is one Markdown file under
client/src/components/HelpPanel/pages/ paired with a thin React
wrapper that imports the Markdown and feeds it to a shared renderer.
The Markdown filename is kebab-case matching the page's route key.
Register every page in pages/index.ts with
{ key, title, component }. When adding a page, add the markdown,
the wrapper, and the registry entry in a single change.
In-app help follows the same writing rules as user-facing docs (one
# heading, intro paragraph after every heading, lead-in colons before
lists, product names as proper nouns, line wrap at 79), with three
differences appropriate to the in-app context:
[label](page:<key>). The renderer
rewrites these links to navigate within the panel.The Help panel uses react-markdown plus remark-gfm. This means:
<Alert severity="info"> inside the wrapper, not in Markdown.<style> and
<script> will not render.react-syntax-highlighter.Use [label](page:<key>) for in-panel links. Do not use
https://docs.pgedge.com/... from in-app help; if depth is needed,
summarize and link with target="_blank" rel="noopener".
Images live alongside the markdown in
client/src/components/HelpPanel/pages/img/<page-key>/ and are bundled
by Vite. Provide alt text on every image.
The verification rule from the user-facing-docs section also applies to in-app help. After authoring or editing any page, launch a sub-agent that confirms documented behavior matches the actual code.
When the working project ships a REST API and a docs/api/openapi.json
file (auto-detected via .pgedge-webapp.json from the pgedge-webapp
skill, or any project with docs/api/openapi.json plus a
docs/api/browser.md page).
Mirror the pattern used by pgedge-postgres-mcp and ai-dba-workbench.
The mkdocs.yml declares the redoc-tag plugin in its plugins: list
(no version pin):
plugins:
- search
- redoc-tag
The browser page lives at docs/api/browser.md. It uses a
hide: [toc, navigation] frontmatter and inline CSS to hide the
mkdocs chrome around the embedded Redoc iframe; the body is a single
<redoc src="openapi.json"/> tag plus a small script that re-applies
inherited colors inside the iframe. The full page is shipped verbatim
in the pgedge-webapp template at
template/docs/api/browser.md — copy it as-is.
The OpenAPI specification lives at docs/api/openapi.json and is
regenerated from the server binary by make openapi:
make openapi
This invokes <binary> --generate-openapi-spec (or -openapi,
matching the project's flag name) and redirects stdout to the file. The
file should be committed; CI re-runs make openapi and diffs against
the committed copy to catch drift.
When pgedge-docs scaffolds a docs site for a project that has
docs/api/openapi.json:
redoc-tag to the plugins: list in mkdocs.yml.- For Developers:
- API Browser: api/browser.md
docs/api/browser.md exists (it ships with
pgedge-webapp templates).mkdocs build --strict to verify the page renders without
warnings.Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub pgedge/pgedge-skills --plugin pgedge-skills