Skip to content

feat: contribute to Holdex repos using a structured Claude Code skill #100

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
zolotokrylin merged 5 commits into from
May 8, 2026
Merged

feat: contribute to Holdex repos using a structured Claude Code skill #100

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
07e1f36
feat: add holdex-contributing Claude Code skill
zolotokrylin Apr 15, 2026
b17fc39
docs: add Claude Code skills section to README
zolotokrylin Apr 15, 2026
5804351
docs: add symlink setup instructions for Claude Code skills
zolotokrylin Apr 15, 2026
ba2782f
Merge branch 'main' into feat/holdex-contributing-skill
zolotokrylin May 8, 2026
655a8d0
chore: apply rumdl fmt fixes
zolotokrylin May 8, 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
37 changes: 37 additions & 0 deletions .claude/commands/holdex-contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
---
name: holdex-contributing
description: Holdex contributing rules for GitHub issues and PRs. Invoke before creating or updating issues or PRs in any Holdex repository.
---

All PRs and issues must follow the

Check warning on line 6 in .claude/commands/holdex-contributing.md

View workflow job for this annotation

GitHub Actions / checks

MD041 

First line in file should be a level 1 heading
[Holdex Contributing Guidelines](https://github.com/holdex/developers/blob/main/docs/CONTRIBUTING.md).

Comment on lines +6 to +8
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Apr 15, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Add a level-1 heading after front matter.

Markdownlint MD041 is valid here. Add a top-level heading (for example # holdex-contributing) right after the front matter block.

🧰 Tools
🪛 GitHub Check: checks

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

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In @.claude/commands/holdex-contributing.md around lines 6 - 8, Add a level-1
heading immediately after the existing front matter block in the
holdex-contributing markdown (e.g., insert "# holdex-contributing" right after
the front matter delimiter) to satisfy markdownlint MD041; ensure the heading is
the first content following the front matter and does not alter the existing
contributing text that follows.

## Issues

- Name: `Problem: [statement]` — must be a **job story** describing what a
specific user **cannot do** (the whole title under 65 characters).
- Good: `employees can't safely handle fund disbursements`
- Bad: `fund handling issue`
Comment on lines +11 to +14
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Apr 15, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Make the “Good” issue example match the required format.

You require Problem: [statement], but the “Good” example omits the Problem: prefix. Update it to avoid contradictory guidance.

Suggested doc update 
-  - Good: `employees can't safely handle fund disbursements`
+  - Good: `Problem: employees can't safely handle fund disbursements`
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In @.claude/commands/holdex-contributing.md around lines 11 - 14, Update the
“Good” example to include the required prefix so it matches the rule "Name:
`Problem: [statement]`" — change the good example from `employees can't safely
handle fund disbursements` to `Problem: employees can't safely handle fund
disbursements` so the guidance is consistent; ensure the text in the doc that
currently shows the Good example is replaced with the prefixed version.

- Link each Problem as a **sub-issue** of its parent Goal issue.
- When referencing other issues or PRs, always use a **list item**, never
inline:

```md
- <https://github.com/holdex/hr-internal/issues/123>
```

## Pull Requests

- **Title**: `type(scope): action` — user-focused, present tense, Conventional
Commits format.
- Good: `docs: protect client funds from unauthorized contractor custody`
- Bad: `Add FUND_HANDLING.md`
- **Scope**: fits within 3–4 hours of work. Decompose if larger.
- **Lifecycle** (in order):
1. Open as a **draft PR** immediately when starting work.
1. Link to the Problem issue using a closing keyword (`Closes #123`).
1. Assign yourself.
1. Resolve all CI checks.
1. Assign at least one reviewer.
1. Mark ready for review only when all steps above are done.
- **Do not merge** without an approved review.
15 changes: 15 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,3 +22,18 @@ Align with:

Subscribe to repository notifications to stay updated with frequent fixes and
improvements.

## Claude Code Skills

Clone this repository locally and symlink the commands directory to make all
skills available globally across every repo you work in:

```bash
ln -s /path/to/holdex/developers/.claude/commands ~/.claude/commands
```
Comment on lines +31 to +33
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot May 8, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Harden the symlink setup command to avoid common setup failures.

On Line 32, ln -s ... ~/.claude/commands can fail (missing ~/.claude) or create an unexpected nested link if ~/.claude/commands already exists as a directory. A safer sequence will reduce onboarding issues.

Suggested doc update 
 ```bash
-ln -s /path/to/holdex/developers/.claude/commands ~/.claude/commands
+mkdir -p ~/.claude
+ln -sfn /path/to/holdex/developers/.claude/commands ~/.claude/commands
</details>

<!-- suggestion_start -->

<details>
<summary>📝 Committable suggestion</summary>

> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

```suggestion
🤖 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 `@README.md` around lines 31 - 33, Update the README.md symlink instructions to
first ensure the target directory exists and then create a deterministic
symlink: add a step to create the ~/.claude directory if missing (use a mkdir -p
style command) and replace the plain ln -s with an ln invocation that forcefully
replaces existing links/targets (use options equivalent to -sfn) so
~/.claude/commands (the symbol shown in the diff) is never left as a nested
directory or broken symlink; update the example line that references
/path/to/holdex/developers/.claude/commands to reflect these two steps.


Skills stay up to date automatically as you pull the repo. Available skills:

| Command | When to use |
| --- | --- |
| `/holdex-contributing` | Before creating or updating a GitHub issue or PR in any Holdex repository |
18 changes: 9 additions & 9 deletions docs/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,8 +54,8 @@ As soon as you get involved, you must:

### Problem

Once a Goal is clear, identify what prevents its achievement. Anything that
acts as a barrier is a Problem.
Once a Goal is clear, identify what prevents its achievement. Anything that acts
as a barrier is a Problem.

> [!NOTE]
> Report each Problem as a [GitHub Issue](https://docs.github.com/en/issues)
Expand Down Expand Up @@ -103,8 +103,8 @@ For reimbursable work-related costs, see [Expenses](./EXPENSES.md).
A Spec describes the intended behavior for a Goal — not what currently exists,
but what the Goal aims to deliver. It is a markdown file in `docs/specs/`.

A Google Document may be used for ideation before the Spec is written.
If one exists, link it in the Goal issue description, not in the Spec.
A Google Document may be used for ideation before the Spec is written. If one
exists, link it in the Goal issue description, not in the Spec.

A Goal must not be opened without a linked Spec.

Expand Down Expand Up @@ -229,8 +229,8 @@ Before marking your PR as ready for review, confirm:

### Commit Signature Verification

All commits must be signed. See [GitHub's documentation on commit signature
verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification).
All commits must be signed. See
[GitHub's documentation on commit signature verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification).

> [!NOTE]
> We recommend signing commits using an
Expand Down Expand Up @@ -283,9 +283,9 @@ PR names must be:
| `fix(sdk): mute sound` | `Fix: add file to mute sound` | Technical details |
| `test(api): open door` | `Feat: modified door function` | Vague, past tense |

A feature isn't a button, toggle, or handler — it's what the user gains from
it. Ask _"What will users be able to do?"_ not _"What am I building?"_ Use
action verbs: _View, Play, Customize, Save_.
A feature isn't a button, toggle, or handler — it's what the user gains from it.
Ask _"What will users be able to do?"_ not _"What am I building?"_ Use action
verbs: _View, Play, Customize, Save_.

> [!WARNING]
> This rule applies to **all PR types**, including `docs`. Do not use verbs that
Expand Down
6 changes: 3 additions & 3 deletions docs/LEAVE_POLICY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,16 +23,16 @@ These days cover **everything**: vacation, personal days, sick days, and public
holidays. Default values above apply unless your individual agreement specifies
otherwise.

> These are your **annual entitlements** — days are not granted all at once.
> See [How Do You Earn Days?](#how-do-you-earn-days-accrual) below for how they
> These are your **annual entitlements** — days are not granted all at once. See
> [How Do You Earn Days?](#how-do-you-earn-days-accrual) below for how they
> accrue over the year.

## How Do You Earn Days? (Accrual)

Days are **accrued gradually** throughout your leave year — you do not receive
the full entitlement up front. The formula is:

```
```text
paidLeaveAmount = (totalEligibleLeaves / 365) × daysElapsed
```

Expand Down
Loading