Spec Skill

Create lightweight specifications for changes that benefit from upfront design.

Usage

/spec "description"
/spec composition "Add Valkey caching"
/spec infrastructure "Add GPU node pool"

Types (optional): composition | infrastructure | security | platform

If type is omitted, infer from description or ask.

When to Use

• New Crossplane compositions
• Major infrastructure changes (VPC, EKS, IAM)
• Security changes (network policies, RBAC, PKI)
• Multi-component platform features

When NOT to Use

• Version bumps, documentation-only, single-file bug fixes, minor config tweaks

Workflow

1. Generate Identifiers

bash
1# Next spec number (3 digits)
2MAX_NUM=$(find docs/specs -name "spec.md" -path "*/[0-9]*" 2>/dev/null | \
3  sed 's|.*/\([0-9]*\)-.*|\1|' | sort -rn | head -1)
4SPEC_NUM=$(printf "%03d" $((10#${MAX_NUM:-0} + 1)))
5
6# Slug from description (3-4 meaningful words, kebab-case)
7# Filter stop words, take meaningful words, join with hyphens

2. Create GitHub Issue

bash
1ISSUE_URL=$(gh issue create \
2  --title "[SPEC] ${TITLE}" \
3  --label "spec,spec:draft" \
4  --body "## Summary
5${DESCRIPTION}
6
7## Spec Directory
8\`docs/specs/${SPEC_NUM}-${SLUG}/\`
9
10---
11_Lightweight spec. See spec file for details._")
12
13ISSUE_NUM=$(echo "$ISSUE_URL" | grep -oP 'issues/\K\d+$')

Labels used:

• spec - All specification issues
• spec:draft - Initial state (add manually: spec:implementing when work starts, spec:done when archived)

3. Create Spec Directory and File

bash
1SPEC_DIR="docs/specs/${SPEC_NUM}-${SLUG}"
2mkdir -p "$SPEC_DIR"

Copy template from docs/specs/templates/spec.md and fill:

• SPEC-XXX → SPEC-${SPEC_NUM}
• #XXX → #${ISSUE_NUM}
• YYYY-MM-DD → current date
• [Title] → from description

4. Link in Issue

bash
1gh issue comment ${ISSUE_NUM} --body "Spec created: [\`${SPEC_DIR}/spec.md\`](${SPEC_DIR}/spec.md)"

5. Output

Spec created:

  Issue: https://github.com/Smana/cloud-native-ref/issues/XXX (label: spec:draft)
  Spec:  docs/specs/XXX-slug/spec.md

Next:
  1. Fill in the spec (use /clarify for [NEEDS CLARIFICATION] sections)
  2. Run /spec-status to see pipeline overview
  3. When starting work: gh issue edit XXX --remove-label "spec:draft" --add-label "spec:implementing"
  4. Implement the changes
  5. Reference in PR: "Implements #XXX"
  6. After merge: spec is auto-archived by GitHub Action

Template Location

docs/specs/templates/spec.md (~80 lines)

Clarifications

Use /clarify to resolve [NEEDS CLARIFICATION: ...] markers with structured options, or discuss conversationally with Claude.

Integration

• /spec creates spec + issue with spec:draft label (this skill)
• /spec-status shows pipeline overview (Draft/Implementing/Done counts)
• /clarify resolves [NEEDS CLARIFICATION] markers with structured options
• /create-pr auto-detects specs and references issue
• /commit for commits
• GitHub Action auto-archives specs on PR merge