refactor(skills): unify cursor rules and claude skills #180

ryoppippi · 2025-12-09T13:36:32Z

Summary

Replace separate Cursor rules with symlinks to Claude skills as single source of truth
Add globs/alwaysApply fields to SKILL.md for Cursor compatibility
Improve skill descriptions to clarify when each should be used
Add PR title guidelines to development-workflow skill
Consolidate redundant rules (clean-code, json-schema) into typescript-patterns

Structure

.claude/skills/          <- Source of truth
├── development-workflow/SKILL.md
├── file-operations/SKILL.md
├── orama-integration/SKILL.md
├── typescript-patterns/SKILL.md
└── typescript-testing/SKILL.md

.cursor/rules/           <- Symlinks
├── development-workflow.mdc -> ../../.claude/skills/development-workflow/SKILL.md
├── file-operations.mdc -> ...
└── ...

Test plan

Verify symlinks resolve correctly: head .cursor/rules/typescript-patterns.mdc
Check skill descriptions are under 1024 chars
Confirm Cursor-specific fields (globs, alwaysApply) are present

Fixes #156

Summary by cubic

Makes .claude/skills the single source of truth and replaces .cursor/rules with symlinks to eliminate duplication. Clarifies skill usage, adds Cursor-compatible fields, and consolidates redundant rules (Fixes #156).

Refactors
- Symlinked .cursor/rules/.mdc to corresponding .claude/skills//SKILL.md
- Added globs and alwaysApply to SKILL.md files for Cursor compatibility
- Folded clean-code, json-schema, and related rules into typescript-patterns
- Improved skill descriptions and scopes
- Added PR title/body guidelines and .yaml naming to development-workflow
- Simplified CLAUDE.md to document the unified skills/rules structure

^{Written for commit 7cd95b2. Summary will update automatically on new commits.}

Replace separate Cursor rules with symlinks to Claude skills, making skills the single source of truth for both AI tools. Changes: - Add globs/alwaysApply fields to SKILL.md for Cursor compatibility - Improve skill descriptions to clarify when each should be used - Replace .cursor/rules/*.mdc files with symlinks to .claude/skills/ - Add PR title guidelines to development-workflow skill - Consolidate clean-code patterns into typescript-patterns skill - Simplify CLAUDE.md to reference unified skill structure This eliminates content duplication and ensures consistent guidance across Cursor and Claude Code. Fixes #156

pkg-pr-new · 2025-12-09T13:37:22Z

Open in StackBlitz

npm i https://pkg.pr.new/StackOneHQ/stackone-ai-node/@stackone/ai@180

commit: 7cd95b2

Copilot

Pull request overview

This PR refactors the project's documentation structure by consolidating Cursor rules and Claude skills into a unified system. Claude skills (.claude/skills/) become the single source of truth, with Cursor rules (.cursor/rules/) implemented as symlinks for compatibility.

Key Changes:

Replaced 9 standalone Cursor rule files with 5 symlinked skill files
Added Cursor-specific metadata (globs, alwaysApply) to Claude SKILL.md files
Consolidated redundant rules (clean-code, json-schema) into typescript-patterns skill
Simplified CLAUDE.md to reference consolidated skills with a quick-lookup table

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
CLAUDE.md	Simplified to reference unified skills with quick-lookup table instead of duplicated content
.cursor/rules/vitest-mocks.mdc	Removed - consolidated into typescript-testing skill
.cursor/rules/typescript-testing.mdc	Created symlink to typescript-testing skill
.cursor/rules/typescript-patterns.mdc	Created symlink to typescript-patterns skill
.cursor/rules/typescript-best-practices.mdc	Removed - consolidated into typescript-patterns skill
.cursor/rules/release-please-standards.mdc	Removed - covered in development-workflow skill
.cursor/rules/pnpm-standards.mdc	Removed - covered in development-workflow skill
.cursor/rules/orama-integration.mdc	Created symlink to orama-integration skill
.cursor/rules/native-fetch.mdc	Removed - consolidated into file-operations skill
.cursor/rules/json-schema-handling.mdc	Removed - consolidated into typescript-patterns skill
.cursor/rules/file-utils.mdc	Removed - consolidated into file-operations skill
.cursor/rules/file-operations.mdc	Created symlink to file-operations skill
.cursor/rules/examples-standards.mdc	Removed (not replaced - examples guidance consolidated elsewhere)
.cursor/rules/development-workflow.mdc	Created symlink to development-workflow skill
.cursor/rules/cursor-rules-location.mdc	Removed (no longer relevant with symlink approach)
.cursor/rules/clean-code.mdc	Removed - consolidated into typescript-patterns skill
.claude/skills/typescript-testing/SKILL.md	Added Cursor metadata and improved description
.claude/skills/typescript-patterns/SKILL.md	Added Cursor metadata, improved description, consolidated clean-code and json-schema content
.claude/skills/orama-integration/SKILL.md	Added Cursor metadata and improved description
.claude/skills/file-operations/SKILL.md	Added Cursor metadata and improved description
.claude/skills/development-workflow/SKILL.md	Added Cursor metadata, PR guidelines, file naming conventions

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-12-09T13:40:37Z

.claude/skills/development-workflow/SKILL.md

 name: development-workflow
-description: Build, development, and code quality commands for StackOne SDK
+description: Build commands, testing, linting, git workflow, commit conventions, and file naming standards. (project)
+globs: ""


The globs field is set to an empty string, but for Cursor compatibility, it should either specify file patterns or be omitted. Since this skill is about development workflow (commands, testing, linting, git), consider using globs: "**/*" to apply to all files, or just remove the field entirely if alwaysApply: true is sufficient.

Suggested change

globs: ""

Copilot · 2025-12-09T13:40:37Z

.claude/skills/orama-integration/SKILL.md

 name: orama-integration
-description: Orama API integration reference for StackOne
+description: Use when integrating with Orama. Links to official docs for search, indexing, answer engine. (project)
+globs: ""


The globs field is set to an empty string, which may not be handled correctly by Cursor. Since this skill applies to Orama integration code, consider specifying relevant file patterns (e.g., globs: "*.ts") or removing the field entirely since you have alwaysApply: false.

Suggested change

globs: ""

Copilot · 2025-12-09T13:40:38Z

CLAUDE.md

-
-Refer to `.claude/skills/orama-integration/SKILL.md` for complete details.
+| Skill | When to Use |
+|-------|-------------|


[nitpick] Inconsistent table formatting: The header row has spaces around the pipes (| Skill | When to Use |) but the separator row doesn't (|-------|-------------|). For proper Markdown rendering, add spaces: | ----- | ----------- |.

Suggested change

|-------|-------------|

| ----- | ----------- |

cubic-dev-ai

1 issue found across 21 files

Prompt for AI agents (all 1 issues)


Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name=".claude/skills/typescript-testing/SKILL.md">

<violation number="1" location=".claude/skills/typescript-testing/SKILL.md:4">
P2: Glob pattern `*.spec.ts` won&#39;t match test files in subdirectories. Use `**/*.spec.ts` for recursive matching since all test files are in paths like `src/tests/` and `src/`.</violation>
</file>

_{Reply to cubic to teach it or ask questions. Re-run a review with @cubic-dev-ai review this PR}

cubic-dev-ai · 2025-12-09T13:42:08Z

.claude/skills/typescript-testing/SKILL.md

 name: typescript-testing
-description: Vitest test runner and MSW-based testing patterns for StackOne SDK
+description: Use when writing or running tests. Covers Vitest commands, MSW HTTP mocking, fs-fixture for file system tests. (project)
+globs: "*.spec.ts"


P2: Glob pattern *.spec.ts won't match test files in subdirectories. Use **/*.spec.ts for recursive matching since all test files are in paths like src/tests/ and src/.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At .claude/skills/typescript-testing/SKILL.md, line 4: <comment>Glob pattern `*.spec.ts` won't match test files in subdirectories. Use `**/*.spec.ts` for recursive matching since all test files are in paths like `src/tests/` and `src/`.</comment> <file context> @@ -1,6 +1,8 @@ name: typescript-testing -description: Vitest test runner and MSW-based testing patterns for StackOne SDK +description: Use when writing or running tests. Covers Vitest commands, MSW HTTP mocking, fs-fixture for file system tests. (project) +globs: "*.spec.ts" +alwaysApply: false --- </file context>

Suggested change

globs: "*.spec.ts"

globs: "**/*.spec.ts"

- Update file-operations skill to HTTP-only (file utils removed upstream) - Keep unified skills/rules structure from this branch

ryoppippi · 2025-12-09T13:54:38Z

this should be merged after #175

…-claude-skills

Copilot AI review requested due to automatic review settings December 9, 2025 13:36

ryoppippi requested a review from a team as a code owner December 9, 2025 13:36

ryoppippi requested a review from NicolasBelissent December 9, 2025 13:36

Copilot started reviewing on behalf of ryoppippi December 9, 2025 13:36 View session

Copilot AI reviewed Dec 9, 2025

View reviewed changes

cubic-dev-ai bot reviewed Dec 9, 2025

View reviewed changes

merge: resolve conflicts with origin/main

b9bbc3e

- Update file-operations skill to HTTP-only (file utils removed upstream) - Keep unified skills/rules structure from this branch

NicolasBelissent approved these changes Dec 9, 2025

View reviewed changes

Merge remote-tracking branch 'origin/main' into refactor/unify-cursor…

7cd95b2

…-claude-skills

ryoppippi merged commit b565d1c into main Dec 9, 2025
7 of 8 checks passed

ryoppippi deleted the refactor/unify-cursor-claude-skills branch December 9, 2025 13:58

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

refactor(skills): unify cursor rules and claude skills #180

refactor(skills): unify cursor rules and claude skills #180

Uh oh!

ryoppippi commented Dec 9, 2025 •

edited by cubic-dev-ai bot

Loading

Uh oh!

pkg-pr-new bot commented Dec 9, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Dec 9, 2025

Uh oh!

Copilot AI Dec 9, 2025

Uh oh!

Copilot AI Dec 9, 2025

Uh oh!

cubic-dev-ai bot left a comment

Uh oh!

cubic-dev-ai bot Dec 9, 2025 •

edited

Loading

Uh oh!

ryoppippi commented Dec 9, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

refactor(skills): unify cursor rules and claude skills #180

refactor(skills): unify cursor rules and claude skills #180

Uh oh!

Conversation

ryoppippi commented Dec 9, 2025 • edited by cubic-dev-ai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Structure

Test plan

Summary by cubic

Uh oh!

pkg-pr-new bot commented Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Dec 9, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 9, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 9, 2025

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ryoppippi commented Dec 9, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ryoppippi commented Dec 9, 2025 •

edited by cubic-dev-ai bot

Loading

pkg-pr-new bot commented Dec 9, 2025 •

edited

Loading

cubic-dev-ai bot Dec 9, 2025 •

edited

Loading