AgentSkillsCN

openspec-authoring

强制执行OpenSpec编写规范，包括元数据块、章节排序、需求/场景结构和验证步骤。

SKILL.md
--- frontmatter
name: openspec-authoring
description: Enforces OpenSpec authoring conventions including metadata blocks, section ordering, requirement/scenario structure, and validation steps.
category: documentation

OpenSpec Authoring Patterns

Trigger Keywords: openspec, proposal, change-id, tasks.md, spec delta, requirement, scenario, validation, archive

Agent Integration: Used by spec-writer and planning agents when creating or updating OpenSpec proposals, tasks, and spec files.

Metadata & Frontmatter

  • •Proposals/Tasks: include Change ID, Status, Date, and Author near the top.
  • •Specs: start with # Spec: <Title> plus capability/status/related lines.
  • •Use verb-led, kebab-case change-id (e.g., add-doc-spec-writer-agent).
  • •Keep managed instruction blocks intact when present.

Required Section Ordering

  • •proposal.md: Executive Summary → Background → Goals → Scope/Non-Goals → Approach → Risks & Mitigations → Validation → Open Questions.
  • •tasks.md: Overview → Phase/Task grouping with checklists; include validation notes where possible.
  • •spec.md (delta): Overview → ## ADDED|MODIFIED|REMOVED Requirements → Scenarios per requirement with Given/When/Then.

Requirement & Scenario Patterns

  • •Each requirement MUST have at least one #### Scenario: block.
  • •Scenario steps use bolded Given/When/Then lines on their own lines.
  • •Keep requirements testable and behavior-focused; avoid solutions in "Then".
  • •Use backticks for capability or file references when helpful.

Validation Checklist

  • •✅ Run openspec validate <change-id> --strict when available.
  • •✅ Ensure every referenced skill/agent/capability exists or is added in the change.
  • •✅ Confirm paths use workspace-relative notation (openspec/specs/...).
  • •✅ Keep documentation generic and reusable across Python projects.

Archiving Notes

  • •Archive changes only after deployment, using date-prefixed folder under openspec/archive/.
  • •Use openspec archive <id> --skip-specs --yes only for tooling-only changes.