diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000000..246fb8d9af --- /dev/null +++ b/SKILL.md @@ -0,0 +1,92 @@ +--- +name: celestia-docs-maintainer +description: Use this skill when creating, updating, or reviewing content in the Celestia docs site (Next.js + Nextra + MDX), including style compliance, chain-id safety checks, link validation, and LLM markdown generation. +--- + +# Celestia docs maintainer + +Use this skill for any task in this repository involving docs content, structure, navigation, or docs QA. + +## Constraints first + +- Never edit auto-generated `.md` files directly. +- `.md` files are generated from `.mdx` sources at build time via `yarn generate:llms`. +- Make edits in `app/**/page.mdx` (and related source files), then regenerate output when needed. + +## Structural rules (high-stakes) + +These rules are structural. Violations can silently break UI behavior, search quality, or content correctness. + +- Tab order must be: Coffee Beta, Mocha, Arabica. +- Placeholders must use `` format (not `` or ``). +- Use network names/capitalization exactly, including: + - `Arabica devnet` + - `Coffee Beta` + +## Style rules (lower priority) + +These are important editorial standards but are lower risk than structural rules. + +- Use sentence case for headings. +- Avoid “click here” link text. +- Use international English. +- Use lowercase node types (for example, “bridge node”). +- Avoid “please” in instructional content. +- Ensure headings are unique within a page. +- Use italicized _i.e._ and _e.g._ +- Refer to celestia-app as plain text (not inline code formatting). + +## Variables and constants + +- Do not hardcode frequently changing version/network values inline. +- Use the constants-backed variable pattern from `constants/*.json` in MDX. +- Example: use `{{mainnetVersions['app-latest-tag']}}` instead of hardcoding a specific app tag. + +## Directory intent guide + +Place new pages in the section matching user intent: + +- `app/learn/`: conceptual and educational content. +- `app/build/`: developer, API, and RPC integration content. +- `app/operate/`: node operator and infrastructure operations content. + +## Chain-id footgun warning + +- Chain-id changes are a known footgun. +- When chain IDs change, run a comprehensive search across all MDX files before considering the task complete. +- Prefer repo-wide search patterns that catch variants (for example old/new chain IDs, code blocks, and inline references). + +## Link and path rules + +- Internal links should be root-relative: `[text](/path/to/page/#section-id)`. +- Whenever any link is added or modified, run: `yarn check-links -- --all`. +- For local assets, store under `public/` and reference with absolute site paths. + +## Repository facts + +- Framework: Next.js + Nextra (MDX), static export. +- Main content pages: `app/**/page.mdx`. +- Sidebar/navigation metadata: `app/**/_meta.js`. +- Shared constants: `constants/*.json` (resolved by `plugins/remark-replace-variables.mjs`). +- Key scripts: + - `yarn lint` + - `yarn check-links -- --all` + - `yarn generate:llms` + - `yarn build` (postbuild generates LLM files and Pagefind index) + +## Done criteria + +- Content is accurate, section placement is correct (`learn`/`build`/`operate`), and structural rules are satisfied. +- If any link was added or changed, `yarn check-links -- --all` has been run successfully. +- If chain IDs changed, comprehensive MDX search completed and all occurrences updated. +- Lint passes for touched files. +- Auto-generated `.md` files were not edited directly. + +## Workflow checklist (run at the end) + +1. Identify target pages in `app/**/page.mdx`. +2. Update content and matching `_meta.js` files if navigation changed. +3. Replace hardcoded version/network values with constants-backed variable syntax where applicable. +4. If links changed, run `yarn check-links -- --all`. +5. Run `yarn lint`. +6. Run `yarn generate:llms` or `yarn build` when output regeneration is required. diff --git a/skills/celestia-router/SKILL.md b/skills/celestia-router/SKILL.md new file mode 100644 index 0000000000..7ba3130b8a --- /dev/null +++ b/skills/celestia-router/SKILL.md @@ -0,0 +1,62 @@ +--- +name: celestia-router +description: Route Celestia tasks to the correct repository workflow (docs, celestia-app, celestia-node, cips), ask the minimum clarifying questions, and avoid doing work in the wrong repo. +--- + +# Celestia router + +Use this skill as the first step for broad "Celestia" requests that do not clearly belong to a single repository. + +## Routing map + +- `docs` repo: + - Documentation pages, tutorials, API docs prose, navigation, formatting/style fixes, link fixes. + - Keywords: "docs", "guide", "page", "MDX", "sidebar", "broken link", "wording". + +- `celestia-app` repo: + - Consensus params, staking/gov behavior, app modules, chain-level upgrades, chain-id and app version mechanics. + - Keywords: "app", "module", "params", "governance", "staking", "upgrade handler". + +- `celestia-node` repo: + - Node runtime, DA sampling behavior, p2p/networking, light/bridge/full node operations, RPC behavior in node implementation. + - Keywords: "node", "bridge node", "light node", "DAS", "p2p", "sync", "node RPC". + +- `cips` repo: + - Protocol proposals, rationale/design discussion, draft/final standards process. + - Keywords: "CIP", "proposal", "spec change", "rationale", "backward compatibility". + +## Decision rules + +1. If the task edits files and target repo is explicit, route there immediately. +2. If target repo is ambiguous, ask one short clarifying question before making edits. +3. If task spans multiple repos, split work by ownership: + - protocol/design in `cips` + - implementation in `celestia-app` or `celestia-node` + - user-facing explanation in `docs` +4. Never implement code changes in `docs` when the real issue is runtime/protocol behavior in app/node. + +## Minimal intake checklist + +- What outcome is needed: behavior change, documentation change, or proposal/spec change? +- Which network scope is involved: Coffee Beta, Mocha, Arabica, or mainnet? +- Is there a version/chain-id dependency that must be updated everywhere? + +## Handoff behavior + +- State selected repo and why in one sentence. +- Use that repo's local skill if available. +- Keep edits scoped to that repo's conventions and verification commands. + +## Safety footguns + +- Chain-id/version changes often require synchronized updates across `docs`, `celestia-app`, and `celestia-node`. +- For docs-only requests, avoid hardcoding versions; prefer constants/templating where available. +- For protocol-impacting requests, avoid "docs-only fixes" that mask an implementation mismatch. + +## Useful references + +- Docs site: `https://docs.celestia.org` +- DeepWiki (docs): `https://deepwiki.com/celestiaorg/docs` +- DeepWiki (cips): `https://deepwiki.com/celestiaorg/cips` +- DeepWiki (celestia-app): `https://deepwiki.com/celestiaorg/celestia-app` +- DeepWiki (celestia-node): `https://deepwiki.com/celestiaorg/celestia-node`