Skill Development Workflow
Orchestrate the full lifecycle of creating a skill for the CaldiaWorks marketplace. This skill is specific to the CaldiaWorks Skills repository.
Mandatory Execution Rule
Each invoked skill defines its own internal steps. Every internal step of every invoked skill must be executed in order without exception. Do not skip, merge, or silently omit any step -- even if the step seems trivial or the answer seems obvious.
If a step requires user input or confirmation, ask. If a step produces output, present it. Violating this rule degrades quality and erodes user trust.
Partial Workflow Entry
If the user already has artifacts from earlier steps, skip completed steps:
| Existing Artifact | Start From |
|---|
| Idea document | Step 2: Issue Creation |
| Issue number | Step 3: Planning |
| Plan document | Step 4: Branch Creation |
| USDM requirements document | Step 6: Skill Implementation |
Ask the user what artifacts they already have before starting.
Workflow Steps
Execute these 9 steps in order. After each step completes, ask the user whether to proceed to the next step.
Step 1: Ideation
- Input: User's rough idea or problem description
- Output: Idea document at
.docs/ideas/YYYY-MM-DD-<topic>.md
- Pass the idea document path to Step 5 (USDM)
Step 2: Issue Creation (Parent Issue)
Invoke the
skill in standalone mode.
- Input: Summary from the idea document
- Output: GitHub Issue number and URL
- Pass the issue number to Step 3 (Planning)
Step 3: Planning
- Input: The parent issue number from Step 2
- Output: Plan document at
.docs/plans/YYYY-MM-DD-<topic>.md
- Pass the plan document and first work unit's issue numbers to Step 4
Update the plan document: set the first work unit's Status to
.
Step 4: Branch Creation
- Input: Issue number and description from the plan's first work unit
- Output: Feature branch name
Update the plan document: set the work unit's Branch to the created branch name.
Step 5: Requirements Definition (USDM)
- Input: The idea document from Step 1
- Output: USDM requirements document at
After USDM completes, invoke the
skill in USDM mode to create requirement sub-issues:
- Input: USDM document path + parent issue number from Step 2
- This creates all REQ issues as sub-issues with SPECs in the body
Step 6: Skill Implementation
- Input: The USDM requirements document from Step 5
- Output: Complete skill directory under
- The skill must include with frontmatter and
.claude-plugin/plugin.json
- Verify the new skill's
.claude-plugin/plugin.json
- Add the skill path to both
.claude-plugin/plugin.json
.claude-plugin/marketplace.json
- Bump the version in both manifest files to the same value.
Step 7: Commit
- Input: All changes from Steps 4-6
- Commits may be made multiple times during implementation for safety
Step 8: Pull Request
- Input: The feature branch with all commits
- Output: PR number and URL
After the PR is merged or the user confirms completion, update the plan document: set the work unit's Status to
.
Step 9: Issue Cleanup
After the PR is merged, close all remaining open sub-issues under the parent issue.
- List open sub-issues of the parent issue:
gh sub-issue list <parent-issue-number>
- For each open sub-issue, recursively list and close its own sub-issues first (bottom-up).
- Close each open sub-issue with a comment referencing the merged PR.
This is necessary because
in commit messages only auto-closes the directly referenced issues. Sub-issues created from USDM requirements (sub-REQs) are not auto-closed and must be closed explicitly.
Plan Progress Tracking
Throughout the workflow, keep the plan document up to date:
| Event | Update |
|---|
| Work unit begins | Status: -> |
| Branch created | Branch: -> branch name |
| PR merged or user confirms completion | Status: -> |
Before Finishing
After the workflow completes (or when the user stops at any step), verify nothing is left behind:
- Open issues? Are there sub-issues under the parent issue that should be closed? Step 9 handles this after merge, but if the workflow is interrupted earlier, flag any open issues to the user.
- Uncommitted changes? Run to check for changes that were not included in the final commit.
- Plan up to date? Does the plan document reflect the actual state of all work units (Status and Branch columns)?
Constraints
- This skill is specific to the CaldiaWorks Skills repository.
- Always follow the project's git workflow: feature branches, squash merge, no direct commits to main.
- Do not skip marketplace registration after skill creation.