Commands and Skills are nearly duplicated after init — maintenance drift risk in team workflows

[panboDing]

Commands and Skills are nearly duplicated after init — maintenance drift risk in team workflows

Problem

After running openspec init (v1.3.1), both commands/opsx/*.md and skills/openspec-*/SKILL.md are generated with nearly identical content. The only differences are:

1. Frontmatter: Skills have extra metadata (author, version, generatedBy, compatibility, description-zh)
2. Minor content variations: A few rules differ slightly between the two copies

This creates a real maintenance problem in team collaboration scenarios.

Reproduction

# After init, compare the two files:
diff commands/opsx/apply.md skills/openspec-apply-change/SKILL.md

Result: 167 lines vs 167 lines, with differences only in frontmatter and 2-3 rule lines.

Same for propose: 124 lines vs 123 lines.

Why this matters for teams

In our monorepo, the team needs to customize rules for our specific tech stack. The customization workflow becomes ambiguous:

• If we customize commands/opsx/: The skills won't reflect our rules, and the next openspec update may overwrite our changes.
• If we customize skills/openspec-*/: Running openspec init again or onboarding a new machine will regenerate commands without our customizations.
• If we customize both: We now have two copies to keep in sync manually — which will inevitably drift.

In our case, the commands already drifted from skills after one round of team customization:

File pair	Commands (lines)	Skills (lines)	Content drift
apply	167	167	3 rules differ
propose	124	123	2 rules differ

The drift includes substantive rule differences — for example, commands contain team-specific enforcement rules (agent-memory checks, comment discipline, real verification commands) that are absent from skills, while skills contain additional UI spec routing logic (domestic spec loading) that commands lack.

Suggested solutions

Any of the following would work:

Option A: Skills reference commands (preferred)

Skills become thin wrappers that point to commands:

# skills/openspec-apply-change/SKILL.md
---
name: openspec-apply-change
description: Implement tasks from an OpenSpec change
---

Execute according to `.claude/commands/opsx/apply.md`.

Additional skill-specific constraints:
- [only list deltas]

This is the lightest change upstream and lets teams maintain a single source of truth in commands while skills serve as a discovery/trigger layer.

Option B: Single source of truth with a generation step

openspec init generates only commands. A separate openspec sync-skills command derives skills from commands + a skills-delta.yaml config that teams maintain for skill-specific metadata and overrides.

Option C: Merge-aware update

openspec update detects local modifications and prompts the user to resolve conflicts (similar to git merge), instead of silently overwriting. This would protect both commands and skills from losing team customizations.

Environment

• OpenSpec CLI: 1.3.1
• Claude Code: latest
• Repo: pnpm monorepo with 3 apps + shared packages
• Team size: 5+ developers collaborating on the same .claude/ config