Skip to content

Commit d164737

Browse files
elithrarask-bonk[bot]
elithrar
and
ask-bonk[bot]
authored
Move changelog command to agent skill (#28348)
* move changelog command to agent skill * Add curated changelog reference folders Co-authored-by: elithrar <elithrar@users.noreply.github.com> --------- Co-authored-by: ask-bonk[bot] <ask-bonk[bot]@users.noreply.github.com> Co-authored-by: elithrar <elithrar@users.noreply.github.com>
1 parent a851a2c commit d164737

2 files changed

Lines changed: 105 additions & 67 deletions

File tree

‎.agents/skills/changelog/SKILL.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
---
2+
name: changelog
3+
description: Creates, updates, and reviews product changelog entries for the Cloudflare documentation site. Load when generating changelog MDX files, editing existing entries, reviewing changelog style, or validating frontmatter.
4+
---
5+
6+
Use this skill when creating, editing, or reviewing changelog entries under `src/content/changelog/`.
7+
8+
## Prerequisites
9+
10+
You need three things before writing:
11+
12+
1. A **product name** (for example, Workers, KV, Hyperdrive, Containers, R2)
13+
2. A **description of the change** being documented
14+
3. Enough context to explain the "why" and use cases
15+
16+
If any are missing, ask for clarification. Do not proceed without all three.
17+
18+
## Determine the product folder
19+
20+
Use the product name to find the correct folder under `src/content/changelog/{product}/`. Check existing folders for valid product names — do not guess.
21+
22+
## Create the changelog file
23+
24+
Path format:
25+
26+
```
27+
src/content/changelog/{product}/{YYYY-MM-DD}-{useful-short-name}.mdx
28+
```
29+
30+
Use today's date and a concise, hyphenated slug describing the change.
31+
32+
## Frontmatter
33+
34+
```yaml
35+
---
36+
title: <TITLE>
37+
description: <ONE_SENTENCE_SUMMARY>
38+
products:
39+
- <PRODUCT>
40+
date: <YYYY-MM-DD>
41+
---
42+
```
43+
44+
## Writing style
45+
46+
- Imperative mood, active voice
47+
- Opening sentence: what the feature/change is and what problem it solves
48+
- Expand on usage, use cases, and the "why" in subsequent paragraphs
49+
- Assume a technical developer/cloud audience
50+
- Keep sentences concise (8-12 words where possible)
51+
- Do not use contractions
52+
- Do not use LLM-like phrases ("It's important to note", "leverage", "seamless", etc.)
53+
- Replace `e.g.` with "for example" and `i.e.` with "that is"
54+
55+
## Code examples
56+
57+
Include a code example when the changelog describes an API, SDK, or configuration change.
58+
59+
- Include a code block demonstrating usage of the new feature
60+
- Use plain JavaScript/TypeScript code blocks (`js` or `ts`)
61+
- Use `jsonc` for wrangler.json config
62+
- Keep snippets short and focused on the new feature
63+
- Minimize boilerplate
64+
- Add imports if using components: `import { Render, TypeScriptExample, WranglerConfig } from "~/components";`
65+
66+
## Documentation links
67+
68+
End the changelog with a link to relevant documentation:
69+
70+
- Use relative paths (for example, `/workers/configuration/placement/`)
71+
- Link text must describe the destination — never "click here" or "read more"
72+
- Check for uncommitted/staged `.md`/`.mdx` files that might be the related documentation
73+
74+
## Reference examples
75+
76+
Review these existing changelogs for style and format guidance:
77+
78+
- `src/content/changelog/workers/` - Workers changelogs with code examples
79+
- `src/content/changelog/kv/` - KV changelogs
80+
- `src/content/changelog/hyperdrive/` - Hyperdrive changelogs
81+
- `src/content/changelog/containers/` - Container changelogs
82+
83+
Read 2-3 entries from the target product's changelog folder before writing to match style and depth. If the target folder has fewer than 2 entries, read from the folders listed above as a reference.
84+
85+
## Editing existing entries
86+
87+
When updating an existing changelog entry, preserve the original structure and voice. Apply only the requested changes — do not rewrite surrounding content.
88+
89+
## Reviewing changelog entries
90+
91+
When reviewing, validate against every section above: frontmatter fields, file path conventions, writing style, code example quality, and documentation links. Flag issues by severity:
92+
93+
- **Error**: Missing required frontmatter fields, wrong product folder, broken links
94+
- **Warning**: Style violations, missing code examples for API changes, vague descriptions
95+
- **Nit**: Minor phrasing improvements
96+
97+
## Output
98+
99+
Create or update the changelog file and show the complete file path and content.

‎.opencode/command/changelog.md‎

Lines changed: 6 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,73 +1,12 @@
11
---
22
description: Generate a product changelog entry
3+
agent: docs
34
---
45

5-
Generate a changelog entry for the Cloudflare documentation site based on the user's request.
6+
Load the `changelog` skill and follow its instructions to generate a changelog entry.
67

7-
## User Request
8+
Request: $ARGUMENTS
89

9-
$ARGUMENTS
10-
11-
## Instructions
12-
13-
1. **Validate the request**: Ensure the user has provided:
14-
- A clear product name (for example, Workers, KV, Hyperdrive, Containers, R2, etc.)
15-
- A description of the change or feature being documented
16-
- Enough context to explain the "why" and use-cases
17-
18-
If any of these are missing or unclear, ask the user for clarification before proceeding.
19-
20-
2. **Determine the product folder**: Use the product name to identify the correct changelog folder under `src/content/changelog/{product}/`. Refer to existing folders for valid product names.
21-
22-
3. **Create the changelog file**: Create a new file at:
23-
```
24-
src/content/changelog/{product}/{YYYY-MM-DD}-{useful-short-name}.mdx
25-
```
26-
Use today's date and a concise, hyphenated slug describing the change.
27-
28-
4. **Frontmatter format**:
29-
```yaml
30-
---
31-
title: {Concise title describing the change}
32-
description: {One-sentence summary of what changed and why it matters}
33-
products:
34-
- {product}
35-
date: {YYYY-MM-DD}
36-
---
37-
```
38-
39-
5. **Writing style guidelines**:
40-
- Use imperative mood and active voice
41-
- The opening sentence must clearly explain what the new feature/change is and what problem it solves
42-
- Expand on usage, use-cases, and the "why" in subsequent paragraphs
43-
- Assume a technical developer/cloud audience
44-
- Keep sentences concise (8-12 words where possible)
45-
- Avoid contractions
46-
- Avoid LLM-like phrases ("It's important to note", "leverage", "seamless", etc.)
47-
- Replace `e.g.` with "for example" and `i.e.` with "that is"
48-
49-
6. **Code examples for Developer Platform products**:
50-
For products in the Developer Platform group (Workers, Durable Objects, Pipelines, KV, Hyperdrive, R2, D1, Queues, Containers, etc.):
51-
- Include a code block demonstrating usage of the new feature
52-
- Use plain JavaScript/TypeScript code blocks (```js or ```ts)
53-
- If showing wrangler.json config, use ```jsonc
54-
- Keep code snippets short and focused on the new feature
55-
- Minimize boilerplate and unnecessary code
56-
- Add imports at the top if using components: `import { Render, TypeScriptExample, WranglerConfig } from "~/components";`
57-
58-
7. **Documentation links**: End the changelog with a link to relevant documentation:
59-
- Use relative paths (for example, `/workers/configuration/placement/`)
60-
- Link text should describe the destination, not "click here" or "read more"
61-
- Check for any uncommitted/staged .md/.mdx files that might be the related documentation
62-
63-
## Reference Examples
64-
65-
Review these existing changelogs for style and format guidance:
66-
- `src/content/changelog/workers/` - Workers changelogs with code examples
67-
- `src/content/changelog/kv/` - KV changelogs
68-
- `src/content/changelog/hyperdrive/` - Hyperdrive changelogs
69-
- `src/content/changelog/containers/` - Container changelogs
70-
71-
## Output
72-
73-
Create the changelog file and show the user the complete file path and content.
10+
If no product or description is provided, check for staged or uncommitted `.mdx` files
11+
to infer context. If still unclear, ask for clarification. Read 2-3 existing entries in
12+
the target product's changelog folder before writing.

0 commit comments

Comments
 (0)