Skip to content

docs(claude): migrate workflows out of CLAUDE.md to skills #355

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nanotaboada merged 2 commits into from
Jul 27, 2026
+46 −33
Merged

docs(claude): migrate workflows out of CLAUDE.md to skills #355

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2f27f50
docs(claude): migrate workflows out of CLAUDE.md to skills
nanotaboada Jul 27, 2026
f11982d
Merge branch 'master' into docs/migrate-claude-md-to-skills
nanotaboada Jul 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions .claude/skills/create-issue/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
---
name: create-issue
description: Draft a GitHub Issue as the spec artifact for Spec-Driven Development (SDD) before implementing a feature or bug fix in this project.
---

This project uses Spec-Driven Development (SDD): discuss in Plan mode first, create a GitHub Issue as the spec artifact, then implement. Always offer to draft an issue before writing code.
Comment on lines +1 to +6

@coderabbitai coderabbitai Bot Jul 27, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Resolve MD041 in both new skill files.

Both files begin their Markdown content with a paragraph after YAML front matter, triggering the same top-level-heading lint warning.

  • .claude/skills/create-issue/SKILL.md#L1-L6: add a heading such as # Create an issue.
  • .claude/skills/key-workflows/SKILL.md#L1-L6: add a heading such as # Key workflows.
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)

[warning] 6-6: First line in a file should be a top-level heading

(MD041, first-line-heading, first-line-h1)

📍 Affects 2 files
  • .claude/skills/create-issue/SKILL.md#L1-L6 (this comment)
  • .claude/skills/key-workflows/SKILL.md#L1-L6
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.claude/skills/create-issue/SKILL.md around lines 1 - 6, Add a top-level
Markdown heading immediately after the YAML front matter in both
.claude/skills/create-issue/SKILL.md (lines 1-6) and
.claude/skills/key-workflows/SKILL.md (lines 1-6), using headings such as
“Create an issue” and “Key workflows” respectively, while preserving the
existing content.

Source: Linters/SAST tools


**Feature request** (`enhancement` label):
- **Problem**: the pain point being solved
- **Proposed Solution**: expected behavior and functionality
- **Suggested Approach** *(optional)*: implementation plan if known
- **Acceptance Criteria**: at minimum — behaves as proposed, tests added/updated, no regressions
- **References**: related issues, docs, or examples

**Bug report** (`bug` label):
- **Description**: clear summary of the bug
- **Steps to Reproduce**: numbered, minimal steps
- **Expected / Actual Behavior**: one section each
- **Environment**: runtime versions + OS
- **Additional Context**: logs, screenshots, stack traces
- **Possible Solution** *(optional)*: suggested fix or workaround
16 changes: 16 additions & 0 deletions .claude/skills/key-workflows/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
---
name: key-workflows
description: Step-by-step guides for adding an endpoint or modifying the schema in this Spring Boot project, plus the branch/commit proposal to make after finishing work.
---

**Add an endpoint**: Define DTO in `models/` with Bean Validation → add service method in `services/` with `@Transactional` → create controller endpoint with `@Operation` annotation → add tests → run `./mvnw clean test jacoco:report`.

**Modify schema**: Create a new Flyway migration `src/main/resources/db/migration/V{N}__description.sql` (production path) → update `@Entity` in `models/Player.java` → update DTOs if API changes → also update `src/test/resources/ddl.sql` and `dml.sql` (tests use Spring SQL init, not Flyway) → update service, repository, and tests → run `./mvnw clean test`. Do not manually edit the SQLite file in `storage/`; Flyway owns it.

**After completing work**: Suggest a branch name (e.g. `feat/113-add-player-stats`) and a commit message following Conventional Commits including co-author line:

```text
feat(scope): description (#issue)

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
```
6 changes: 6 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,12 @@ Release names follow the **historic football clubs** naming convention (A–Z):
`/pre-commit`; move CodeRabbit review to run against the uncommitted CHANGELOG
diff; separate commit-message approval from the actual commit so checks run
in between
- Trim `CLAUDE.md`: replace the "Pre-commit Checks" list with a pointer to the
existing `/pre-commit` skill, and move "Creating Issues" and "Key workflows"
into two new on-demand skills (`create-issue`, `key-workflows`) so their
content only loads when needed instead of every session — found and applied
by the new `/doctor` command, per
[the new rules of context engineering for Claude 5 generation models](https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models)

### Fixed

Expand Down
36 changes: 3 additions & 33 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,12 +68,7 @@ docker compose down -v

### Pre-commit Checks

1. `./mvnw clean install` — must succeed
2. All tests pass
3. Check coverage at `target/site/jacoco/index.html`
4. No compilation warnings
5. Commit message follows Conventional Commits format (enforced by commitlint)
6. If this commit introduces or changes an architectural decision, update `CLAUDE.md` and create or amend the relevant ADR in `docs/adr/`.
Run `/pre-commit` to execute the full pre-commit checklist for this project before proposing a commit.

### Commits

Expand Down Expand Up @@ -114,36 +109,11 @@ Example: `feat(api): add player stats endpoint (#42)`

### Creating Issues

This project uses Spec-Driven Development (SDD): discuss in Plan mode first, create a GitHub Issue as the spec artifact, then implement. Always offer to draft an issue before writing code.

**Feature request** (`enhancement` label):
- **Problem**: the pain point being solved
- **Proposed Solution**: expected behavior and functionality
- **Suggested Approach** *(optional)*: implementation plan if known
- **Acceptance Criteria**: at minimum — behaves as proposed, tests added/updated, no regressions
- **References**: related issues, docs, or examples

**Bug report** (`bug` label):
- **Description**: clear summary of the bug
- **Steps to Reproduce**: numbered, minimal steps
- **Expected / Actual Behavior**: one section each
- **Environment**: runtime versions + OS
- **Additional Context**: logs, screenshots, stack traces
- **Possible Solution** *(optional)*: suggested fix or workaround
This project uses Spec-Driven Development (SDD): discuss in Plan mode first, create a GitHub Issue as the spec artifact, then implement. Always offer to draft an issue before writing code. See the `create-issue` skill for the feature/bug issue templates.

### Key workflows

**Add an endpoint**: Define DTO in `models/` with Bean Validation → add service method in `services/` with `@Transactional` → create controller endpoint with `@Operation` annotation → add tests → run `./mvnw clean test jacoco:report`.

**Modify schema**: Create a new Flyway migration `src/main/resources/db/migration/V{N}__description.sql` (production path) → update `@Entity` in `models/Player.java` → update DTOs if API changes → also update `src/test/resources/ddl.sql` and `dml.sql` (tests use Spring SQL init, not Flyway) → update service, repository, and tests → run `./mvnw clean test`. Do not manually edit the SQLite file in `storage/`; Flyway owns it.

**After completing work**: Suggest a branch name (e.g. `feat/add-player-stats`) and a commit message following Conventional Commits including co-author line:

```text
feat(scope): description (#issue)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
```
See the `key-workflows` skill for the step-by-step guides to adding an endpoint, modifying the schema, and what to propose after finishing work.

## Invariants (never change without explicit discussion)

Expand Down