AgentSkillsCN

dot-ai-changelog-fragment

在首次推送至PR时，在/prd-done工作流中创建变更日志片段。在需要编写发布说明时调用此功能。

SKILL.md
--- frontmatter
name: dot-ai-changelog-fragment
description: Create changelog fragment for release notes. Invoke during /prd-done workflow during the first push to the PR.
user-invocable: true

Create Changelog Fragment

Create a towncrier changelog fragment for release notes when completing PRD work. This should be included in the PR so the fragment is reviewed along with the code changes.

Workflow

Step 1: Identify the PRD

If not already known from context, ask: "Which PRD should I create release notes for?"

Look for:

  • •PRD mentioned in recent conversation
  • •PRD referenced in current branch name (e.g., feature/prd-320-*)
  • •PRD file path provided by user

Step 2: Read the PRD Thoroughly

Read the entire PRD file to extract:

  • •Problem Statement: What user pain point was solved, why it mattered
  • •Solution Overview: What the feature does, how it works
  • •User Impact: Specific benefits, what users can now do
  • •Key Capabilities: Individual features, options, or modes added
  • •Technical Details: Configuration options, environment variables, commands
  • •Documentation Updates: Which docs were added or updated (check Milestones section)

Step 3: Determine Fragment Type

Read pyproject.toml to see the available fragment types. Each [[tool.towncrier.type]] section has:

  • •A comment above it describing when to use that type
  • •A directory field (the type identifier used in the filename, e.g., feature for .feature.md)

Choose the type that best matches the PRD based on those descriptions.

Step 4: Write the Fragment

Create file: changelog.d/[issue-id].[type].md

IMPORTANT: Use flat structure, NOT subdirectories!

  • •✅ Correct: changelog.d/329.feature.md
  • •❌ Wrong: changelog.d/feature/329.md

Naming convention:

  • •issue-id: GitHub issue number from PRD (e.g., 320)
  • •type: Type identifier from step 3 (e.g., feature, bugfix, misc)

Content format:

markdown
## [Feature Title]

[Opening sentence: What this feature is and the problem it solves]

[Key capabilities paragraph: Specific things users can now do, with concrete examples]

[Configuration/usage paragraph if applicable: How to enable or use the feature]

[Documentation link if docs were updated]

Documentation links: If the PRD includes documentation updates, link to the relevant page on devopstoolkit.ai. The URL pattern is:

  • •https://devopstoolkit.ai/docs/{project}/{path}
  • •Where {project} is: ai-engine (dot-ai), controller (dot-ai-controller), ui (dot-ai-ui), or stack (dot-ai-stack)
  • •And {path} maps from the docs folder (e.g., docs/ai-engine/tools/recommend.md → tools/recommend)

Example: changelog.d/142.feature.md

markdown
## Multi-Cluster Management

Manage multiple Kubernetes clusters from a single dot-ai instance. Previously, each cluster required its own dot-ai deployment, making it difficult to compare configurations or apply consistent patterns across environments.

The `query` tool now accepts a `--cluster` flag to target specific clusters, and results indicate which cluster each resource belongs to. The `recommend` tool can generate manifests targeting different clusters with environment-specific customizations. Cross-cluster searches let you find resources across all connected clusters simultaneously—useful for tracking down where a particular workload is deployed. Cluster health aggregation shows a unified view of all clusters in the `version` output.

Configure additional clusters by adding kubeconfig contexts to `ADDITIONAL_KUBECONFIGS` (comma-separated paths). Each context becomes available as a cluster target. The default cluster remains the current kubeconfig context when no `--cluster` flag is specified.

See the [Multi-Cluster Setup Guide](https://devopstoolkit.ai/docs/ai-engine/setup/multi-cluster-setup) for configuration details and examples.

Step 5: Confirm Creation

Show the user:

  1. •The fragment file path created
  2. •The content written
  3. •Reminder to commit and push with the PR

Guidelines

  • •User-focused: Describe what users gain, not implementation details
  • •Specific: Include concrete examples of what each capability does
  • •Complete: Cover all major features added, not just the headline
  • •Present tense: "Tools now return..." not "Added support for..."
  • •No diary style: "Multi-Cluster Management" not "Added multi-cluster support"
  • •Include configuration: Mention environment variables, commands, or setup steps
  • •Link to docs: If PRD updated documentation, link to the specific page on devopstoolkit.ai