From 0be3795eabe4f922a7a84e487f1cb169c3705bc2 Mon Sep 17 00:00:00 2001 From: Yogesh Rao Date: Thu, 4 Jun 2026 16:29:34 +0530 Subject: [PATCH] =?UTF-8?q?feat:=20improve=20openspec-apply-change=20skill?= =?UTF-8?q?=20score=2074%=20=E2=86=92=2090%?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Hey @benkli01 👋 I ran your skills through `tessl skill review` at work and found some targeted improvements for `openspec-apply-change`. Here's the full before/after: | Skill | Before | After | Change | |-------|--------|-------|--------| | openspec-apply-change | 74% | 90% | +16% | | openspec-explore | 72% | — | unchanged | | openspec-archive-change | 78% | — | unchanged | | openspec-propose | 78% | — | unchanged |
Changes made **Description improvements (biggest impact — 57% → 100%):** - Rewrote the description to list concrete actions: reading task definitions, generating code changes, marking tasks complete, tracking progress - Added explicit "Use when..." clause with natural trigger terms: "start or resume implementation", "spec tasks", "task list", "next pending change" - Added an inline example invocation to the input section for discoverability **Content improvements (77% → 77%, maintained while reducing bulk):** - Consolidated three verbose output format blocks (implementation, completion, pause) into a single concise output format paragraph — same information, ~60% fewer lines - Merged redundant pause/blocker conditions that were duplicated between step 6 and the Guardrails section into one consolidated list - Tightened the Fluid Workflow Integration section from a bulleted pair into a single focused paragraph - Kept both `.github/skills/` and `.codex/skills/` copies in sync **What stayed the same:** - All 7 workflow steps preserved with their CLI commands and state handling logic - Guardrail intent unchanged — just consolidated - OpenSpec-specific terminology and domain framing preserved throughout
I also stress-tested your `openspec-apply-change` skill against a few real-world task evals and it held up really well on multi-schema task iteration with blocked-state recovery. Kudos for that. Honest disclosure — I work at @tesslio where we build tooling around skills like these. Not a pitch — just saw room for improvement and wanted to contribute. Want to self-improve your skills? Just point your agent (Claude Code, Codex, etc.) at [this Tessl guide](https://docs.tessl.io/evaluate/optimize-a-skill-using-best-practices) and ask it to optimize your skill. Ping me — [@yogesh-tessl](https://github.com/yogesh-tessl) — if you hit any snags. Thanks in advance 🙏 --- .codex/skills/openspec-apply-change/SKILL.md | 88 +++---------------- .github/skills/openspec-apply-change/SKILL.md | 88 +++---------------- 2 files changed, 26 insertions(+), 150 deletions(-) diff --git a/.codex/skills/openspec-apply-change/SKILL.md b/.codex/skills/openspec-apply-change/SKILL.md index d474dc1..506321c 100644 --- a/.codex/skills/openspec-apply-change/SKILL.md +++ b/.codex/skills/openspec-apply-change/SKILL.md @@ -1,6 +1,6 @@ --- name: openspec-apply-change -description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks. +description: "Implement tasks from an OpenSpec change by reading task definitions, generating code changes, marking tasks complete, and tracking progress. Use when the user wants to start or resume implementation, work through spec tasks, check the task list, or apply the next pending change." license: MIT compatibility: Requires openspec CLI. metadata: @@ -9,9 +9,9 @@ metadata: generatedBy: "1.2.0" --- -Implement tasks from an OpenSpec change. +Implement tasks from an OpenSpec change — read task definitions, generate focused code changes, update task status, and report progress. -**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes. +**Input**: Optionally specify a change name (e.g., `apply add-auth`). If omitted, infer from conversation context. If vague or ambiguous, MUST prompt for available changes. **Steps** @@ -38,23 +38,16 @@ Implement tasks from an OpenSpec change. openspec instructions apply --change "" --json ``` - This returns: - - Context file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs) - - Progress (total, complete, remaining) - - Task list with status - - Dynamic instruction based on current state + This returns context file paths, progress (total/complete/remaining), task list with status, and a dynamic instruction. **Handle states:** - - If `state: "blocked"` (missing artifacts): show message, suggest using openspec-continue-change - - If `state: "all_done"`: congratulate, suggest archive + - `state: "blocked"` (missing artifacts): show message, suggest openspec-continue-change + - `state: "all_done"`: congratulate, suggest archive - Otherwise: proceed to implementation 4. **Read context files** - Read the files listed in `contextFiles` from the apply instructions output. - The files depend on the schema being used: - - **spec-driven**: proposal, specs, design, tasks - - Other schemas: follow the contextFiles from CLI output + Read all files listed in `contextFiles` from the apply instructions output. File sets vary by schema (e.g., spec-driven uses proposal/specs/design/tasks). 5. **Show current progress** @@ -87,70 +80,15 @@ Implement tasks from an OpenSpec change. - If all done: suggest archive - If paused: explain why and wait for guidance -**Output During Implementation** - -``` -## Implementing: (schema: ) - -Working on task 3/7: -[...implementation happening...] -✓ Task complete - -Working on task 4/7: -[...implementation happening...] -✓ Task complete -``` - -**Output On Completion** - -``` -## Implementation Complete - -**Change:** -**Schema:** -**Progress:** 7/7 tasks complete ✓ - -### Completed This Session -- [x] Task 1 -- [x] Task 2 -... - -All tasks complete! Ready to archive this change. -``` - -**Output On Pause (Issue Encountered)** - -``` -## Implementation Paused - -**Change:** -**Schema:** -**Progress:** 4/7 tasks complete - -### Issue Encountered - - -**Options:** -1.