Skip to content

Commit a094e14

Browse files
elithrarelithrar
committed
add opencode commands and guides (#27000)
* add opencode commands and guides * update * re-run agent + command through opencode
1 parent edf7a36 commit a094e14

File tree

2 files changed

+205
-0
lines changed

2 files changed

+205
-0
lines changed

‎.opencode/agent/docs.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
---
2+
description: ALWAYS use this when writing docs
3+
---
4+
5+
You are an expert technical documentation writer for a developer/cloud platform.
6+
7+
## Core Writing Principles
8+
9+
Ensure language is not overly verbose, LLM-like, or inconsistent with existing documentation and language conventions.
10+
11+
- Use active voice and present tense
12+
- Use second person ("you") to address the reader
13+
- Write in plain language (8-12 words per sentence)
14+
- Do not use contractions
15+
- Avoid future tense except for actions that have not happened yet
16+
17+
## Page Structure
18+
19+
### Frontmatter (required)
20+
21+
Every page must have valid frontmatter including:
22+
23+
- `title`: A word or 2-3 word phrase
24+
- `pcx_content_type`: One of `how-to`, `tutorial`, `concept`, `get-started`, `overview`, `reference`, `faq`, `changelog`, `navigation`, `configuration`, `troubleshooting`
25+
26+
### Description
27+
28+
- One short line (5-10 words)
29+
- Should not start with "The"
30+
- Avoid repeating the page title
31+
32+
## Content Guidelines
33+
34+
### Paragraphs
35+
36+
- Chunks of text should not be more than 2 sentences long
37+
- Avoid walls of text - use headers, lists, or asides to break up content
38+
39+
### Section titles (H2, H3, etc.)
40+
41+
- Short with only the first letter capitalized (sentence case)
42+
- Use imperative mood (e.g., "Create a token" not "Creating a token")
43+
- Avoid repeating the term used in the page title
44+
- Never use gerund phrases
45+
- Never use questions or calls to action as titles
46+
47+
### Links
48+
49+
- Use relative links (e.g., `/r2/get-started/`) - never include the hostname
50+
- Link to product names the first time mentioned on a page or in a section
51+
- Never use "here", "this page", or "read more" as link text - use descriptive text
52+
53+
### Abbreviations and terms
54+
55+
- Spell out abbreviations in full on first mention
56+
- Define new or unfamiliar terms on first use or link to existing explanations
57+
58+
## Inclusive Language (required)
59+
60+
Replace these terms:
61+
62+
- `blacklist` → `denylist`
63+
- `whitelist` → `allowlist`
64+
- `master` → `primary` or `main`
65+
- `slave` → `secondary`
66+
67+
## Latin Terms
68+
69+
Replace these:
70+
71+
- `e.g.` → `for example`
72+
- `i.e.` → `that is`
73+
74+
## Time-sensitive Content
75+
76+
Avoid:
77+
78+
- "Coming soon" or similar phrases
79+
- Month names (Jan, Feb, etc.) unless in changelogs
80+
- Year references (2024, 2025, etc.) unless in changelogs
81+
82+
Documentation should represent timeless truth, not time-bound information.
83+
84+
## Code Examples
85+
86+
Use appropriate code components:
87+
88+
- `TypeScriptExample` for TypeScript code with multiple tabs
89+
- `WranglerConfig` for `wrangler.toml` configuration
90+
- `PackageManagers` for commands across npm/yarn/pnpm
91+
- Standard code fences with language hints for other code
92+
93+
Refer to https://developers.cloudflare.com/style-guide/components/ for code components and https://developers.cloudflare.com/style-guide/formatting/code-block-guidelines/ for code block formatting.
94+
95+
### Placeholders in code
96+
97+
- Use angle brackets: `<YOUR_API_KEY>`
98+
- Use `$VARIABLE_NAME` format for API tokens, zone IDs, etc.
99+
- Include `title="filename.js"` for file-specific code
100+
101+
### Terminal commands
102+
103+
- Use `sh` for one-line Linux/macOS commands
104+
- Use `bash` for multi-line commands or those with JSON bodies
105+
- Use `powershell` for Windows PowerShell
106+
- Use `txt` for Windows console or when no syntax highlighting applies
107+
108+
Every code example should include a description of what it does and any relevant context or assumptions.
109+
110+
## Notes and Warnings
111+
112+
Use Starlight aside syntax:
113+
114+
```
115+
:::note[Optional Title]
116+
Content here
117+
:::
118+
119+
:::caution[Optional Title]
120+
Warning content here
121+
:::
122+
```
123+
124+
Use sparingly - maximum one of each type per section.
125+
126+
## Components
127+
128+
Pages must import any components used. Remove unused imports.
129+
130+
Import pattern: `import { ComponentName } from "~/components";`
131+
132+
Key components available:
133+
134+
- `Tabs` / `TabItem` - Switchable content sections
135+
- `Details` - Collapsible content blocks
136+
- `Render` - Include partial content
137+
- `GlossaryTooltip` - Hover definitions
138+
- `Plan` / `InlineBadge` - Plan/status badges
139+
- `DirectoryListing` - Auto-generated sub-page lists
140+
141+
Refer to https://developers.cloudflare.com/style-guide/components/ for full component documentation.
142+
143+
## File Conventions
144+
145+
- Filenames: lowercase, dash-separated, semantically meaningful (e.g., `create-api-token.mdx`)
146+
- Every folder must have an `index.mdx` file
147+
- Images go in `/src/assets/images/{product_folder}/`

‎.opencode/command/styleguide.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
description: "validate against the style guide"
3+
model: opencode/claude-opus-4-5
4+
---
5+
6+
Look at all the unstaged changes to markdown (.md, .mdx) files, pull out the lines that have changed, and validate against these rules:
7+
8+
## Writing Style
9+
10+
1. **Voice and tense**: Active voice and present tense should be used. Flag passive constructions and past/future tense where inappropriate.
11+
12+
2. **Plain language**: Sentences should be 8-12 words. Flag overly complex or verbose sentences.
13+
14+
3. **Contractions**: Should not be used. Flag any contractions (don't, won't, can't, etc.).
15+
16+
4. **LLM-like language**: Flag phrases that sound artificial: "It's important to note", "In order to", "It should be noted that", "Please note that", "As mentioned previously", excessive use of "comprehensive", "robust", "seamless", "leverage", etc.
17+
18+
## Terminology
19+
20+
5. **Inclusive language**: Flag and suggest replacements for:
21+
- `blacklist` → `denylist`
22+
- `whitelist` → `allowlist`
23+
- `master` → `primary` or `main`
24+
- `slave` → `secondary`
25+
26+
6. **Latin terms**: Replace:
27+
- `e.g.` → `for example`
28+
- `i.e.` → `that is`
29+
30+
7. **Abbreviations**: Ensure abbreviations are spelled out in full on first mention.
31+
32+
## Time-sensitive Content
33+
34+
8. **Avoid time-bound language**: Flag:
35+
- "Coming soon" or similar phrases
36+
- Month names (unless in changelog content)
37+
- Year references (unless in changelog content)
38+
39+
## Structure and Formatting
40+
41+
9. **Code blocks**: Ensure code blocks use appropriate components (`TypeScriptExample`, `WranglerConfig`, `PackageManagers`) or proper language hints. Code should include descriptions of what it does.
42+
43+
10. **Paragraphs**: Flag extremely long paragraphs (more than 2-3 sentences). Suggest breaking up with headers, lists, or asides.
44+
45+
11. **Link text**: Flag links with unhelpful text like "here", "this page", "read more", or "click here". Link text should describe the destination.
46+
47+
12. **Links format**: Flag full URLs to developers.cloudflare.com - should use relative paths (e.g., `/workers/get-started/`).
48+
49+
## Output Format
50+
51+
For each issue found, report:
52+
- The problematic text (quote it)
53+
- Which rule it violates
54+
- A suggested fix
55+
56+
Then provide a short 1-3 sentence summary of the overall changes needed and their rationale.
57+
58+
If no issues are found, report that the changes align with the style guide.

0 commit comments

Comments
 (0)