Skip to content

Commit 25c951e

Browse files
claudeclaude
committed
Address Copilot review comments on checkpoint skills
- Add `checkpoint: true` to spec 4.4.2 required schema fields so the self-identifying marker is normative rather than skill-only - Add `## How to Invoke` section to create-checkpoint/SKILL.md and restore-checkpoint/SKILL.md for consistency with all other skills - Add SKILL.validation.md for both new skill folders - Remove unverifiable "not modified since last_updated" check from restore-rules.md; keep checkpoint: true validation (now spec-backed) - Replace "Press Enter" in conflict prompt with platform-neutral wording https://claude.ai/code/session_01QTwxzD9j8ds3W1kq6dQ2UX
1 parent 0c6dd04 commit 25c951e

6 files changed

Lines changed: 201 additions & 4 deletions

File tree

‎skills/create-checkpoint/SKILL.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,10 @@ allowed-tools: [Read, Write]
1010
## Purpose
1111
Capture the active session state as a structured Markdown checkpoint artifact so the session can be restored in a future conversation.
1212

13+
## How to Invoke
14+
15+
Load or attach this file's contents into your AI session to activate the workflow (paste, upload, or reference with `#file:skills/create-checkpoint/SKILL.md` in VS Code Copilot Chat). In Claude Projects, add it to project knowledge. See [Invoking Skills](../../README.md#invoking-skills) in the README for full platform guidance.
16+
1317
## When To Use
1418
- When the user signals they are ending the session and want to resume later.
1519
- When the user explicitly requests a checkpoint.

‎skills/create-checkpoint/SKILL.validation.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# Skill Validation Report
2+
3+
**File:** skills/create-checkpoint/SKILL.md
4+
**Skill:** create-checkpoint
5+
**Validated:** 2026-05-12
6+
7+
---
8+
9+
## Overall Status: ✅ PASS
10+
11+
**Compliance Score:** 97/100
12+
13+
---
14+
15+
## Phase 1: Presence, Structure, And Frontmatter
16+
**Status:** ✅ PASS
17+
18+
### Findings:
19+
- SKILL.md exists with valid frontmatter.
20+
- Required fields (`name`, `description`, `version`, `allowed-tools`) are present and syntactically valid.
21+
- `allowed-tools` correctly scoped to `[Read, Write]`.
22+
23+
### Recommendations:
24+
- None.
25+
26+
---
27+
28+
## Phase 2: Field Constraints And Naming Parity
29+
**Status:** ✅ PASS
30+
31+
### Findings:
32+
- `name` matches folder name and naming constraints.
33+
- Description is trigger-appropriate and includes explicit do-not-use guard.
34+
35+
---
36+
37+
## Phase 3: Instruction Quality And Completeness
38+
**Status:** ✅ PASS
39+
40+
### Findings:
41+
- Workflow is sequenced correctly: collect → draft → present → approve → write.
42+
- Approval gate is explicit: file must not be written without user confirmation.
43+
- Schema reference is externalised to `references/checkpoint-schema.md`.
44+
- Sensitive data exclusion constraint is explicit.
45+
46+
---
47+
48+
## Phase 4: Resource References And Safety
49+
**Status:** ✅ PASS
50+
51+
### Findings:
52+
- `references/checkpoint-schema.md` path is relative and resolves correctly.
53+
- Storage constraint (outside instruction layer) is explicit.
54+
- Null-value handling for optional fields is specified.
55+
56+
---
57+
58+
## Phase 5: Neutrality And Portability
59+
**Status:** ✅ PASS
60+
61+
### Findings:
62+
- Provider-neutral wording throughout.
63+
- Invocation guidance covers all supported platforms.
64+
65+
---
66+
67+
## Summary
68+
69+
### Strengths:
70+
- Strong approval gate prevents silent writes.
71+
- Schema externalisation keeps the workflow file concise.
72+
73+
### Critical Issues (Must Fix):
74+
- None.
75+
76+
### Warnings (Should Fix):
77+
- None.
78+
79+
### Enhancements (Optional):
80+
- Consider a post-write step that suggests adding the checkpoint path to `.gitignore` if the file contains private context.
81+
82+
---
83+
84+
## Recommendations
85+
86+
### Immediate Actions:
87+
1. None.
88+
89+
### Suggested Improvements:
90+
1. Revalidate after any spec section 4.4.2 schema changes.
91+
92+
---
93+
94+
**Validation completed successfully.**

‎skills/restore-checkpoint/SKILL.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,10 @@ allowed-tools: [Read]
1010
## Purpose
1111
Load a checkpoint artifact and restore the session state it describes, surfacing any conflicts with active instruction files before any work begins.
1212

13+
## How to Invoke
14+
15+
Load or attach this file's contents into your AI session to activate the workflow (paste, upload, or reference with `#file:skills/restore-checkpoint/SKILL.md` in VS Code Copilot Chat). In Claude Projects, add it to project knowledge. See [Invoking Skills](../../README.md#invoking-skills) in the README for full platform guidance.
16+
1317
## When To Use
1418
- At the start of a session when the user provides a checkpoint file.
1519
- Do not apply checkpoint state mid-session or without the user explicitly providing the artifact.

‎skills/restore-checkpoint/SKILL.validation.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# Skill Validation Report
2+
3+
**File:** skills/restore-checkpoint/SKILL.md
4+
**Skill:** restore-checkpoint
5+
**Validated:** 2026-05-12
6+
7+
---
8+
9+
## Overall Status: ✅ PASS
10+
11+
**Compliance Score:** 97/100
12+
13+
---
14+
15+
## Phase 1: Presence, Structure, And Frontmatter
16+
**Status:** ✅ PASS
17+
18+
### Findings:
19+
- SKILL.md exists with valid frontmatter.
20+
- Required fields (`name`, `description`, `version`, `allowed-tools`) are present and syntactically valid.
21+
- `allowed-tools` correctly scoped to `[Read]` — no writes during restore.
22+
23+
### Recommendations:
24+
- None.
25+
26+
---
27+
28+
## Phase 2: Field Constraints And Naming Parity
29+
**Status:** ✅ PASS
30+
31+
### Findings:
32+
- `name` matches folder name and naming constraints.
33+
- Description is trigger-appropriate and limits use to session-start only.
34+
35+
---
36+
37+
## Phase 3: Instruction Quality And Completeness
38+
**Status:** ✅ PASS
39+
40+
### Findings:
41+
- Workflow is sequenced correctly: validate → compare → surface conflicts → resolve → confirm → proceed.
42+
- Confirmation gate is explicit: no task work begins until user confirms restored state.
43+
- Conflict resolution logic and examples are externalised to `references/restore-rules.md`.
44+
- Instruction-file-wins default is explicitly stated.
45+
46+
---
47+
48+
## Phase 4: Resource References And Safety
49+
**Status:** ✅ PASS
50+
51+
### Findings:
52+
- `references/restore-rules.md` path is relative and resolves correctly.
53+
- Cross-reference to `skills/create-checkpoint/references/checkpoint-schema.md` is accurate.
54+
- Mid-session guard is explicit.
55+
56+
---
57+
58+
## Phase 5: Neutrality And Portability
59+
**Status:** ✅ PASS
60+
61+
### Findings:
62+
- Provider-neutral wording throughout.
63+
- Conflict prompt language is platform-neutral (no terminal-specific cues).
64+
- Invocation guidance covers all supported platforms.
65+
66+
---
67+
68+
## Summary
69+
70+
### Strengths:
71+
- Read-only allowed-tools scope is a strong safety constraint.
72+
- Explicit instruction-file-wins default prevents silent state overwrite.
73+
74+
### Critical Issues (Must Fix):
75+
- None.
76+
77+
### Warnings (Should Fix):
78+
- None.
79+
80+
### Enhancements (Optional):
81+
- Consider logging resolved conflicts to a short inline summary the user can copy for their records.
82+
83+
---
84+
85+
## Recommendations
86+
87+
### Immediate Actions:
88+
1. None.
89+
90+
### Suggested Improvements:
91+
1. Revalidate after any spec section 4.4.3 restore rule changes.
92+
93+
---
94+
95+
**Validation completed successfully.**

‎skills/restore-checkpoint/references/restore-rules.md‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,8 @@ Source: spec section 4.4.3.
1212
## Validation Checks
1313

1414
Before restoring, confirm the artifact:
15-
- Contains `checkpoint: true` in frontmatter.
16-
- Contains all required schema fields (see `skills/create-checkpoint/references/checkpoint-schema.md`).
17-
- Was not modified since `last_updated` in a way that would make the state inconsistent.
15+
- Contains `checkpoint: true` in frontmatter (spec section 4.4.2 required field; reject if absent).
16+
- Contains all other required schema fields (see `skills/create-checkpoint/references/checkpoint-schema.md`).
1817

1918
Flag any missing fields and ask the user to supply values or confirm the instruction file default before proceeding.
2019

@@ -31,7 +30,7 @@ Surface it as:
3130
> **Conflict — role:**
3231
> Checkpoint: `Developer`
3332
> AGENTS.md default: `Architect`
34-
> Which should apply? (Press Enter or no response = AGENTS.md default)
33+
> Which should apply? (If you don't answer, I will apply the AGENTS.md default.)
3534
3635
If no response: apply `Architect` from AGENTS.md.
3736

‎specs/context_aware_ai_session_spec.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,7 @@ A checkpoint artifact must include the following fields:
121121

122122
| Field | Description |
123123
|-------|-------------|
124+
| `checkpoint` | Always `true` — identifies this file as a checkpoint artifact |
124125
| `project` | Active project name |
125126
| `role` | Active role at session end |
126127
| `phase` | Active phase at session end |

0 commit comments

Comments
 (0)