Skip to content

Commit 3076fcf

Browse files
aspiersaspiers
committed
chore(ai): add SKILL.md for writing changesets
1 parent 476abbc commit 3076fcf

2 files changed

Lines changed: 173 additions & 25 deletions

File tree

‎.claude/skills/writing-changesets/SKILL.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
---
2+
name: writing-changesets
3+
description:
4+
Create changeset files for user-facing changes. Use when making API changes, modifying types, adding features, or any
5+
change that affects package consumers.
6+
---
7+
8+
# Writing Changesets
9+
10+
Create a changeset file to document user-facing changes for release.
11+
12+
## When to Use
13+
14+
Add a changeset when making changes that affect consumers:
15+
16+
- Adding new SDK methods or operations (createProject, addEvidence, etc.)
17+
- Modifying existing API signatures (breaking or non-breaking)
18+
- Changing TypeScript type exports or interfaces
19+
- Adding new React hooks or components
20+
- Renaming any exported constants, types, functions, or hooks
21+
- Changing behavior of existing operations
22+
- Bug fixes that affect external behavior
23+
- Any change that requires a version bump or affects package consumers
24+
25+
Skip changesets for internal changes (build scripts, tests, refactoring, documentation only).
26+
27+
## Packages
28+
29+
The SDK has two publishable packages:
30+
31+
- `@hypercerts-org/sdk-core` - Core SDK
32+
- `@hypercerts-org/sdk-react` - React hooks etc.
33+
34+
## Format
35+
36+
Create in `.changeset/` a Markdown file with a descriptive kebab-case name (e.g., `fix-collection-type-alignment.md`) in
37+
this format:
38+
39+
```markdown
40+
---
41+
"@hypercerts-org/sdk-core": minor
42+
---
43+
44+
Align collection/project CRUD types with lexicon definitions
45+
```
46+
47+
For changes affecting both packages:
48+
49+
```markdown
50+
---
51+
"@hypercerts-org/sdk-core": minor
52+
"@hypercerts-org/sdk-react": minor
53+
---
54+
55+
Add comprehensive project support to SDK
56+
57+
**Core SDK (`@hypercerts-org/sdk-core`):**
58+
59+
- Add project CRUD operations (createProject, getProject, listProjects)
60+
- Add project events (projectCreated, projectUpdated, projectDeleted)
61+
- Support for avatar and banner blob uploads
62+
63+
**React SDK (`@hypercerts-org/sdk-react`):**
64+
65+
- Add useProjects and useProject hooks
66+
- Project query keys for cache management
67+
- TypeScript types for projects
68+
```
69+
70+
### Frontmatter Fields
71+
72+
There should be a frontmatter field for each package being changed. The field name should be the package name, and the
73+
field value should be one of the following change types:
74+
75+
- `patch` - Bug fixes, non-breaking changes
76+
- `minor` - New features, non-breaking additions (also breaking changes if the version in `package.json` is still 0.x.y)
77+
- `major` - Breaking changes (_ONLY_ use if the version in `package.json` is already greater than 0.x.y)
78+
79+
**Current versions are 0.x.y, so use `minor` for breaking changes.**
80+
81+
### Description
82+
83+
In the body after the frontmatter field(s), write a clear, concise description following conventional commit style.
84+
Focus on what changed and why. For multi-package changes, use sections to separate changes.
85+
86+
## Example Changesets
87+
88+
**New SDK feature:**
89+
90+
```markdown
91+
---
92+
"@hypercerts-org/sdk-core": minor
93+
---
94+
95+
Add project CRUD operations to repository interface
96+
```
97+
98+
**API signature change:**
99+
100+
```markdown
101+
---
102+
"@hypercerts-org/sdk-core": minor
103+
---
104+
105+
Evidence records are now created separately instead of being embedded inline in hypercerts
106+
107+
**Breaking Changes:**
108+
109+
- Evidence is no longer embedded in the hypercert record - use `result.evidenceUris` to access evidence record URIs
110+
- `addEvidence()` now accepts a single `CreateHypercertEvidenceParams` object instead of
111+
`(uri: string, evidence: HypercertEvidence[])`
112+
```
113+
114+
**Type/interface change:**
115+
116+
```markdown
117+
---
118+
"@hypercerts-org/sdk-core": minor
119+
---
120+
121+
Align collection/project CRUD types with lexicon definitions
122+
123+
- Update CreateCollectionParams to match lexicon schema
124+
- Add CreateCollectionResult type with optional location URI
125+
- Simplify project operations to delegate to collection operations
126+
```
127+
128+
**React hook addition:**
129+
130+
```markdown
131+
---
132+
"@hypercerts-org/sdk-react": minor
133+
---
134+
135+
Add useProjects and useProject hooks for project management
136+
```
137+
138+
**Bug fix:**
139+
140+
```markdown
141+
---
142+
"@hypercerts-org/sdk-core": patch
143+
---
144+
145+
Fix SDS routing for organization endpoints
146+
```
147+
148+
## Key Files
149+
150+
- `.changeset/config.json` - Changeset configuration
151+
- Existing changeset files in `.changeset/` - Reference for naming and format
152+
- `package.json` - Contains version and release scripts
153+
- `packages/sdk-core/package.json` - Core SDK version
154+
- `packages/sdk-react/package.json` - React SDK version

‎AGENTS.md‎

Lines changed: 19 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -247,23 +247,33 @@ Each entrypoint outputs:
247247

248248
Uses [Changesets](https://github.com/changesets/changesets) for versioning.
249249

250-
**Flow:** `feature` → `develop` (beta) → `main` (stable)
250+
**Branch flow:** `feature` → `develop` (beta) → `main` (stable)
251251

252-
### Commands
252+
### Creating Changesets
253253

254-
```bash
255-
pnpm changeset # Add changeset (required for package changes)
256-
pnpm version-packages # Apply changesets locally
257-
pnpm release # Build and publish
258-
```
254+
**REQUIRED: All user-facing changes must include a changeset.**
255+
256+
To create a changeset, use the `writing-changesets` skill.
257+
258+
**The skill is the single source of truth for:**
259+
260+
- When changesets are required vs optional
261+
- How to format changeset files correctly
262+
- Which packages to include in the frontmatter
263+
- Changeset type selection (patch/minor/major)
264+
- Examples for different types of changes
265+
266+
Do not attempt to create changesets without consulting this skill first.
259267

260-
### Branches
268+
### Release Branches
261269

262270
- **develop**: Auto-publishes `@beta` tag (e.g., `0.2.0-beta.0`)
263271
- **main**: Creates Release PR → merge to publish `@latest`
264272

265273
### Before merging develop → main
266274

275+
You should never do this unless explicitly requested by the user:
276+
267277
```bash
268278
pnpm changeset pre exit
269279
git add .changeset/pre.json
@@ -357,27 +367,11 @@ git commit -m "feat(hypercerts): add project CRUD operations"
357367
# - Block commit if build fails
358368

359369
# 6. If prompted, add changeset for user-facing changes
360-
pnpm changeset
370+
# See "Release Process" section - use the writing-changesets skill
361371
git add .changeset/*.md
362372
git commit -m "chore: add changeset for project operations"
363373
```
364374

365-
### When to Add a Changeset
366-
367-
Run `pnpm changeset` before pushing if your changes include:
368-
369-
- New features or API changes
370-
- Bug fixes that affect users
371-
- Breaking changes
372-
- Performance improvements
373-
374-
Skip changesets for:
375-
376-
- Internal refactoring
377-
- Test-only changes
378-
- Documentation updates
379-
- Development tooling changes
380-
381375
## Key Files Reference
382376

383377
### sdk-core

0 commit comments

Comments
 (0)