-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathrulesync.txt
More file actions
2200 lines (1787 loc) · 118 KB
/
rulesync.txt
File metadata and controls
2200 lines (1787 loc) · 118 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
This file is a merged representation of a subset of the codebase, containing specifically included files, combined into a single document by Repomix.
<file_summary>
This section contains a summary of this file.
<purpose>
This file contains a packed representation of a subset of the repository's contents that is considered the most important context.
It is designed to be easily consumable by AI systems for analysis, code review,
or other automated processes.
</purpose>
<file_format>
The content is organized as follows:
1. This summary section
2. Repository information
3. Directory structure
4. Repository files (if enabled)
5. Multiple file entries, each consisting of:
- File path as an attribute
- Full contents of the file
</file_format>
<usage_guidelines>
- This file should be treated as read-only. Any changes should be made to the
original repository files, not this packed version.
- When processing this file, use the file path to distinguish
between different files in the repository.
- Be aware that this file may contain sensitive information. Handle it with
the same level of security as you would the original repository.
</usage_guidelines>
<notes>
- Some files may have been excluded based on .gitignore rules and Repomix's configuration
- Binary files are not included in this packed representation. Please refer to the Repository Structure section for a complete list of file paths, including binary files
- Only files matching these patterns are included: pages/AI___Coding___Tool___Report___25___Skills Comparison.md, pages/AI___LLM___Technique___Skill___Progressive Disclosure.md, .rulesync/skills/rulesync-create-skill/references/checklist.md, .rulesync/skills/rulesync-create-skill/references/layers.md, .rulesync/skills/rulesync-create-skill/SKILL.md, .rulesync/skills/rulesync/case-studies.md, .rulesync/skills/rulesync/cli-commands.md, .rulesync/skills/rulesync/configuration.md, .rulesync/skills/rulesync/declarative-sources.md, .rulesync/skills/rulesync/dry-run.md, .rulesync/skills/rulesync/faq.md, .rulesync/skills/rulesync/file-formats.md, .rulesync/skills/rulesync/global-mode.md, .rulesync/skills/rulesync/installation.md, .rulesync/skills/rulesync/mcp-server.md, .rulesync/skills/rulesync/official-skills.md, .rulesync/skills/rulesync/programmatic-api.md, .rulesync/skills/rulesync/quick-start.md, .rulesync/skills/rulesync/simulated-features.md, .rulesync/skills/rulesync/SKILL.md, .rulesync/skills/rulesync/supported-tools.md, .rulesync/skills/rulesync/why-rulesync.md, pages/rulesync___GitHub___Issue___25___09___Brainstorm needed - how to share some rules across repos, but not all i329.md, pages/rulesync___GitHub___Issue___25___10___Custom Claude Code Command Yaml Frontmatter i413.md, pages/rulesync___GitHub___Issue___25___10___Documentation clarification on globs i389.md, pages/rulesync___GitHub___Issue___25___10___Feature request rulesync githook.md, pages/rulesync___GitHub___Issue___25___10___README clarification on simulated subagents and commands i388.md, pages/rulesync___gitignore.md, pages/rulesync___How To___Write Skills With Progressive Disclosure.md, pages/rulesync___Ignore.md, pages/rulesync___log___25___09___29 Mon - First time with rulesync.md, pages/rulesync___log___25___10___04 Sat - Issues with gitignore.md, pages/rulesync___log___25___10___07 Tue - DRYing out AI Coding Configs.md, pages/rulesync___log___25___10___11 Sat - globs and simulated commands.md, pages/rulesync___log___25___11___10 Mon - on abstraction costs and plugin marketplaces.md, pages/rulesync___log.md, pages/rulesync___mise.md, pages/rulesync___Skill___Declarative Source.md, pages/rulesync.md
- Files matching patterns in .gitignore are excluded
- Files matching default ignore patterns are excluded
- Files are sorted by Git change count (files with more changes are at the bottom)
</notes>
</file_summary>
<directory_structure>
.rulesync/
skills/
rulesync/
case-studies.md
cli-commands.md
configuration.md
declarative-sources.md
dry-run.md
faq.md
file-formats.md
global-mode.md
installation.md
mcp-server.md
official-skills.md
programmatic-api.md
quick-start.md
simulated-features.md
SKILL.md
supported-tools.md
why-rulesync.md
rulesync-create-skill/
references/
checklist.md
layers.md
SKILL.md
pages/
AI___Coding___Tool___Report___25___Skills Comparison.md
AI___LLM___Technique___Skill___Progressive Disclosure.md
rulesync___GitHub___Issue___25___10___Custom Claude Code Command Yaml Frontmatter i413.md
rulesync___GitHub___Issue___25___10___Documentation clarification on globs i389.md
rulesync___GitHub___Issue___25___10___Feature request rulesync githook.md
rulesync___GitHub___Issue___25___10___README clarification on simulated subagents and commands i388.md
rulesync___gitignore.md
rulesync___How To___Write Skills With Progressive Disclosure.md
rulesync___Ignore.md
rulesync___log___25___09___29 Mon - First time with rulesync.md
rulesync___log___25___10___04 Sat - Issues with gitignore.md
rulesync___log___25___10___07 Tue - DRYing out AI Coding Configs.md
rulesync___log___25___10___11 Sat - globs and simulated commands.md
rulesync___log___25___11___10 Mon - on abstraction costs and plugin marketplaces.md
rulesync___log.md
rulesync___mise.md
rulesync___Skill___Declarative Source.md
rulesync.md
</directory_structure>
<files>
This section contains the contents of the repository's files.
<file path=".rulesync/skills/rulesync-create-skill/references/checklist.md">
# Checklist: Rulesync skill with progressive disclosure
## Before writing
- [ ] **Problem**: What single class of user requests should trigger this skill?
- [ ] **Level 1**: Draft `description` first; can a stranger agent say yes/no without reading the body?
- [ ] **Level 2**: What is the minimum sequence that completes 80% of tasks?
- [ ] **Level 3**: What belongs in `references/` or `scripts/` instead of the body?
## While writing `SKILL.md`
- [ ] YAML has no long prose, duplicated docs, or reference tables.
- [ ] Body opens with the shortest working path; edge cases point to `references/`.
- [ ] Every `references/*.md` file is linked from the body with a **when to read** cue.
- [ ] Scripts have a stated contract: command, cwd assumptions, expected output.
## Token discipline pass
- [ ] Remove text the base model already knows unless it is safety- or repo-specific.
- [ ] No essential step exists **only** in a bundled file unless the body says when to load it.
- [ ] Large command catalogs or API dumps live in `references/`, not in the body.
## Troubleshooting
| Symptom | Likely fix |
|--------|------------|
| Skill rarely triggers | Add concrete triggers and examples to `description`; narrow or broaden scope explicitly. |
| Agents load too much | Move sections to `references/`; split topics; shorten body to a workflow index. |
| Duplication across skills | Shared content belongs in a rule, command, or one shared reference linked from several skills. |
| Generate does not update tool skills | Add `"skills"` to `features` in `rulesync.jsonc` and run `rulesync generate` for your targets. |
## Optional: Logseq garden mirror
In the logseq-encode-garden graph, the same authoring ideas are summarized as a Diataxis how-to page titled **rulesync/How To/Write Skills With Progressive Disclosure** (filesystem: `rulesync___How To___Write Skills With Progressive Disclosure.md`). Use that page for human-oriented narrative; this skill stays repo-local for agents.
</file>
<file path=".rulesync/skills/rulesync-create-skill/references/layers.md">
# Three layers for a Rulesync skill
Progressive disclosure means **staging** what enters the model context: metadata first, core instructions when the skill matches, bundled files only when the task needs them.
## Level 1 — Discovery (YAML on `SKILL.md`)
- **Always-on cost**: frontmatter is what agents use to **select** among skills.
- **Rulesync**: keep `name` stable; set `targets` appropriately; add tool-specific blocks only when they change real behavior (for example `allowed-tools`, `short-description`).
- **Write `description` like a trigger spec**: concrete user intents, technologies, and boundaries (“use when…”, “do not use for…”).
## Level 2 — Core procedure (body of `SKILL.md`)
- Loaded **after** the skill is chosen; still shared with everything else in the window, so keep it **short and procedural**.
- Start with **quick start** or numbered default path.
- Tell the agent **when to open** each reference file or **when to run** each script so it does not preload “just in case.”
- Prefer **relative links** (`./references/foo.md`) so the skill stays portable across clones.
## Level 3 — Bundled resources (same directory)
Typical layout:
```text
.rulesync/skills/<skill-name>/
├── SKILL.md
├── references/ # long tables, API notes, rare branches
├── scripts/ # deterministic or token-heavy steps
└── assets/ # templates, static files for outputs
```
- **`references/`**: one topic per file when possible; filenames should signal when to load them.
- **`scripts/`**: document invocation, inputs, and what to trust in stdout or artifacts; execution can avoid loading entire source into context.
- **Precedence**: local skills under `.rulesync/skills/<name>/` override curated copies with the same name (see Rulesync declarative sources docs).
## Relation to the generic `skill-creator` skill
Upstream `skill-creator` (for example from `anthropics/skills`) is **general** skill authoring. This garden’s workflow is **Rulesync-shaped**: same directory model, plus `targets` and tool-specific YAML from Rulesync. Follow both: Rulesync file-format constraints here, token discipline from `skill-creator` where it does not conflict.
</file>
<file path=".rulesync/skills/rulesync-create-skill/SKILL.md">
---
name: rulesync-create-skill
description: >-
Create or refactor a Rulesync skill under .rulesync/skills/<skill-name>/ using
progressive disclosure: small YAML for discovery, a lean SKILL.md body, and
optional references/ and scripts/ loaded only when needed. Use when the user
asks for a new skill, wants an oversized SKILL.md split up, or should align a
skill with staged-loading practices for AI agents.
targets: ["*"]
---
# Rulesync: create a progressive-disclosure skill
## When this applies
Use this skill for **authoring or restructuring** `.rulesync/skills/<skill-name>/`, not for learning the Rulesync CLI. For CLI reference, use the `rulesync` documentation skill or [file-formats.md](../rulesync/file-formats.md#rulesyncskillsskillmd) in this repo.
## Quick start
1. Pick a **kebab-case** directory name under `.rulesync/skills/<skill-name>/` (match the skill’s `name` in frontmatter when practical).
2. Add `SKILL.md` with YAML containing at least `name`, `description`, and `targets` (see [file-formats.md](../rulesync/file-formats.md#rulesyncskillsskillmd) for tool-specific keys such as `claudecode.allowed-tools` or `codexcli.short-description`).
3. Write `description` so another agent can decide **from that field alone** whether to load the skill: what it does, **when** to use it (verbs, tools, file types, user intents). Do not put tutorials or long tables in YAML.
4. In the markdown **body**, put only the **shortest happy path** and guardrails. Link to `./references/...` for depth; use `./scripts/` for repeatable automation (invoke via shell; prefer trusting stdout over pasting full source).
5. Before finishing, run the checklist in [references/checklist.md](./references/checklist.md).
## Deeper material (load on demand)
- [references/layers.md](./references/layers.md) — map progressive disclosure levels to Rulesync layout and Rulesync-specific notes.
- [references/checklist.md](./references/checklist.md) — design review, token discipline, troubleshooting.
## After files exist
If this project uses `rulesync generate`, ensure `rulesync.jsonc` includes `"skills"` in `features`, then run generate for your targets so tool-specific skill outputs stay in sync.
</file>
<file path="pages/rulesync___GitHub___Issue___25___10___Custom Claude Code Command Yaml Frontmatter i413.md">
tags:: [[GitHub/Issue/My]], [[Claude Code/Command/Slash/Custom]]
- # [Feature request: for claude code slash commands, support passing through claude-code-specific yaml markdown frontmatter keys to the generated command markdown files · Issue #413 · dyoshikawa/rulesync](https://github.com/dyoshikawa/rulesync/issues/413)
- ## [[Original Poster]]
- # Feature Request: Support Claude Code-Specific YAML Frontmatter Keys for Commands
NOTE: *this feature request was drafted with the assistance of [this deepwiki thread](https://deepwiki.com/search/claude-code-slash-commands-all_82ed05e6-e4cf-4c98-af1f-295a538d8954).*
- ## Summary
Currently, rulesync commands defined in `.rulesync/commands/*.md` only support a minimal frontmatter schema with `description` as the only field that gets passed through to Claude Code slash commands. However, Claude Code's native slash command format [supports additional YAML frontmatter keys](https://docs.claude.com/en/docs/claude-code/slash-commands#frontmatter) like `allowed-tools`, `argument-hint`, `model`, and `disable-model-invocation` that enable powerful command customization. This feature request proposes adding support for passing through these Claude Code-specific keys from rulesync command definitions to generated Claude Code command files.
- ## Current Limitation
When converting from `RulesyncCommand` to `ClaudecodeCommand`, only the `description` field is extracted and passed through. The `ClaudecodeCommand` schema itself only defines `description` in its frontmatter, meaning there's no mechanism to specify tool-specific configuration like `allowed-tools` or `model`.
- ## Precedent: Subagents Already Support This Pattern
Interestingly, rulesync **subagents** already implement a solution to this exact problem. The `RulesyncSubagent` frontmatter schema includes a `claudecode:` section that allows tool-specific configuration. This configuration gets properly passed through during conversion to `ClaudecodeSubagent`.
- ## Proposed Feature Specification
- ### 1. Extend RulesyncCommand Frontmatter Schema
Add a `claudecode:` section to the `RulesyncCommandFrontmatter` schema (similar to how subagents work)<cite />:
```yaml
---
description: "Create a git commit"
claudecode:
allowed-tools: "Bash(git add:*), Bash(git status:*), Bash(git commit:*)"
argument-hint: "[message]"
model: "claude-3-5-haiku-20241022"
disable-model-invocation: false
---
Create a git commit with message: $ARGUMENTS
```
- ### 2. Supported Claude Code Keys
The `claudecode:` section should support all Claude Code-specific frontmatter keys:
- **`allowed-tools`**: Restrict which tools the command can use (e.g., `"Bash(git add:*), Bash(git status:*)"`)
- **`argument-hint`**: Display hint for command arguments (e.g., `"[message]"` or `"[pr-number] [priority] [assignee]"`)
- **`model`**: Specify which Claude model to use (e.g., `"claude-3-5-haiku-20241022"`)
- **`disable-model-invocation`**: Whether to prevent `SlashCommand` tool from calling this command
- ### 3. Conversion Behavior
When generating Claude Code commands via `rulesync generate --targets claudecode --features commands`<cite />:
1. Extract the `claudecode:` section from the rulesync command frontmatter
2. Merge these keys into the generated Claude Code command's YAML frontmatter
3. Preserve the `description` field at the top level (as it currently works)
4. For other tool targets (Cursor, Roo, etc.), ignore the `claudecode:` section
- ### 4. Backward Compatibility
- Existing commands without a `claudecode:` section should continue to work as they do today
- The `description` field should remain at the top level of frontmatter for all tools
- Other tool-specific sections (e.g., `roo:`, `cursor:`) could be added in the future following the same pattern
- ## Example Usage
**Input**: `.rulesync/commands/git-commit.md`
```yaml
---
description: "Create a git commit"
claudecode:
allowed-tools: "Bash(git add:*), Bash(git status:*), Bash(git commit:*)"
argument-hint: "[message]"
model: "claude-3-5-haiku-20241022"
---
Create a git commit with message: $ARGUMENTS
```
**Output**: `.claude/commands/git-commit.md` (after `rulesync generate`)
```yaml
---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
argument-hint: [message]
description: Create a git commit
model: claude-3-5-haiku-20241022
---
Create a git commit with message: $ARGUMENTS
```
- ## Benefits
1. **Feature Parity**: Commands would have the same tool-specific configuration capabilities that subagents already have<cite />
2. **Full Claude Code Support**: Users could leverage all Claude Code slash command features through rulesync
3. **Consistent Pattern**: Follows the established `claudecode:` section pattern used by subagents
4. **Extensibility**: The pattern could be extended to other tools (e.g., `roo:`, `cursor:`) in the future
- ## Notes
- The Roo command implementation already supports `argument-hint` as a top-level field, but this is tool-specific rather than following a general pattern
- This feature would make commands a first-class citizen alongside subagents in terms of tool-specific configuration support
- Global mode currently supports commands for Claude Code, so this feature would enhance that capability as well
-
</file>
<file path="pages/rulesync___GitHub___Issue___25___10___Documentation clarification on globs i389.md">
tags:: [[GitHub/Issue/My]]
- [Documentation clarification on globs · Issue #389 · dyoshikawa/rulesync](https://github.com/dyoshikawa/rulesync/issues/389)
-
</file>
<file path="pages/rulesync___GitHub___Issue___25___10___Feature request rulesync githook.md">
- [Feature request: `rulesync githook` and `rulesync githook --install` which registers git post-checkout hook to regenerate rules in the case that `rulesync gitignore` · Issue #351 · dyoshikawa/rulesync](https://github.com/dyoshikawa/rulesync/issues/351)
- ## Summary
- If a `rulesync` user runs `rulesync gitignore` to treat all the non-rulesync AI Configs as ignored and generated assets. If they then pull a commit which changes a rule, then a git hook should regenerate the downstream AI Configs.
- ## Details
- `rulesync githook` could be the executable entrypoint for the hook, and `rulesync githook --install` could be the command which installed the git hook into the repository.
- ## Side note about wording - AI Configs and AI Config Manager
- From a marketing perspective, it would be advantageous to settle on the terminology for the types of assets that rulesync manages. In the readme, it currently says:
- > A Node.js CLI tool that automatically generates configuration files for various AI development tools from unified AI rule files.
- This is about as correct as one can get. But in issues and documentation, it's a little verbose to call these assets "configuration files for various AI development tools."
- Calling them "rules" seems intuitive but wrong, as rulesync now manages agents, commands, and other configuration items.
- Given that [configuration management](https://en.wikipedia.org/wiki/Configuration_management) is an established term, perhaps calling the assets rulesync manages "AI Configs" and branding rulesync as an "AI Config Manager" might be good enough? What do you think and what other terms have you considered? I asked ChatGPT and it came up with ten names, but the only one I kind of liked was AI DevConfig.
</file>
<file path="pages/rulesync___GitHub___Issue___25___10___README clarification on simulated subagents and commands i388.md">
tags:: [[GitHub/Issue/My]]
- [README clarification on simulated commands and subagents · Issue #388 · dyoshikawa/rulesync](https://github.com/dyoshikawa/rulesync/issues/388)
</file>
<file path="pages/rulesync___gitignore.md">
- `rulesync gitignore` - add generated files to [[git/.gitignore]]
-
</file>
<file path="pages/rulesync___How To___Write Skills With Progressive Disclosure.md">
tags:: [[rulesync]], [[Diataxis/How To]]
see-also:: [[AI/LLM/Technique/Skill/Progressive Disclosure]], [[rulesync]]
- # How To write rulesync skills with progressive disclosure
- ## Overview
- This guide tells an AI agent how to author a skill under `.rulesync/skills/<skill-name>/` so discovery stays cheap, `SKILL.md` loads only when relevant, and heavy material stays on disk until the workflow needs it — matching the staged-loading idea in [[Progressive Disclosure]].
- Rulesync’s bundled examples (for example the upstream `skill-creator` and `playwright-cli` skills) follow the same shape: compact YAML metadata, a focused main file, optional `references/` and `scripts/`
- ## Prerequisites
- A rulesync project with the `skills` feature enabled and a target directory such as `.rulesync/skills/<skill-name>/`
- Familiarity with why staged loading matters (context cost).
- For more detailed information on best practices for progressive disclosure, see [Claude Code's skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview.md).
- If you have access to `logseq-encode-garden`, see [[Progressive Disclosure]].
- ## Steps
- ### 1. Design the three layers before writing prose
- **Level 1 (always visible)**: plan `name` and `description` in YAML — these are the only fields agents use to decide whether to open the skill; the description must say what the skill does **and when to use it** (triggers, tools, file types, user intents)
- **Level 2 (load on match)**: plan the body of `SKILL.md` as the minimum procedure to complete the usual task — workflows, guardrails, and pointers to deeper files — not a dump of every edge case
- **Level 3 (on demand)**: list optional `references/*.md`, `scripts/*`, templates, or assets; each file should have one clear reason to exist and be named so the agent knows when to open it
- ### 2. Write `SKILL.md` frontmatter for discovery, not documentation
- Keep `description` self-contained: a stranger agent should know from that text alone whether this skill applies to the current request
- Avoid putting long tutorials or reference tables in YAML; that defeats progressive disclosure and bloats the always-on layer
- ### 3. Keep the `SKILL.md` body action-first
- Open with the shortest path that works (a “quick start” or numbered happy path), then optional sections for variants
- Prefer short imperative steps and small examples over general explanations; if the reader needs theory, link or point to a `references/` file instead of inlining it
- State explicitly when to **read** a reference file versus **run** a script so the agent does not preload everything “just in case”
- ### 4. Split depth into `references/` and automation into `scripts/`
- Move rarely needed detail (API tables, long command catalogs, style guides) into `references/<topic>.md` and cite paths from `SKILL.md` only when that topic is in scope
- Put repeatable, fragile, or token-heavy operations in `scripts/` when execution can return **stdout or artifacts** without pasting the whole program into context; note in `SKILL.md` how to invoke and what output to trust
- ### 5. Review against token discipline
- For every paragraph in `SKILL.md`, ask whether the model already knows it; cut or demote to `references/` if not task-critical
- Ensure unrelated skills still pay almost nothing: no essential steps hidden only in bundled files unless `SKILL.md` tells the agent when to load them
- ## Troubleshooting
- **Skill never triggers**: rewrite `description` with concrete triggers (verbs, tools, file globs, error messages users mention)
- **Skill pulls too much context**: move long sections out of `SKILL.md` into `references/`; replace inlined scripts with `scripts/` plus a one-line invocation contract
</file>
<file path="pages/rulesync___log___25___09___29 Mon - First time with rulesync.md">
### [[2025-09-29 Mon]]
- I tried running it in [[Person/codekiln/GitHub/logseq-cursor-rules]] in the root directory with ` rulesync import --targets cursor` and it didn't load any, because they were in the root of the directory. There's a [[GitHub/Issue]] for this here: [rulesync import ignores subdirectories in .cursor/rules · Issue #56 · dyoshikawa/rulesync](https://github.com/dyoshikawa/rulesync/issues/56).
- I also tried running it in [[GitHub/codekiln/logseq-encode-garden]], which did have non-nested [[CursorAI/Project Rules]], but it did not import any rules, as far as I can tell, nor did it output any debug information.
- As a result, I think this project is of limited utility at this time.
- I filed [[GitHub/Issue]] [rulesync import --targets cursor does not import .cursor/rules/*.mdc · Issue #328 · dyoshikawa/rulesync](https://github.com/dyoshikawa/rulesync/issues/328)
- result of running `rulesync generate --targets "*" --features "*" after importing` - ALL the [[AI/Coding/Tool]]s had rules imported!
- 
- Again, this made me think that we need [[Package Management]] for [[Knowledge Gardens]], because what if we wanted to share some rules in multiple repositories. It does make me wonder if I need to just make my own MCP server which would be a gateway MCP server.
- #Filed [[GitHub/Issue/My]]
- [Brainstorm needed - how to share some rules across repos, but not all · Issue #329 · dyoshikawa/rulesync](https://github.com/dyoshikawa/rulesync/issues/329)
- Each project usually requires a combination of shared and project-specific rules.
- For example, some of my projects use rules and commands that are specific to the context of FastAPI. Others, use rules and commands specific to the context of typescript CLIs. I don't need all of my rules and commands in each project.
- Ideally, it would be possible to define my rules for technology A, e.g. FastAPI, in one repo, my rules for technology B, e.g. TypeScript in another repo, and my rules for technology C, e.g. EnterprisePrivateTechnology in another private repo, and just marshal those rules into the current repo and then use `rulesync` to spread those out to the various providers.
- One possible solution could be to use git submodules, but those may have problems:
- in CI, if you have private repos, authentication permissions can get tricky with git submodules.
- it's not clear that rulesync would support subdirectories needed for git submodules
- So, let's talk about what possible solutions are out there for this use case.
- [Feature request: pre-made rules for how AI can use rulesync · Issue #330 · dyoshikawa/rulesync](https://github.com/dyoshikawa/rulesync/issues/330)
- In order for AI to aid in updating rules, AI needs the context of how `rulesync` works. It would be great if there was an [llms.txt with docs for AI](https://llmstxt.org/) or some other facility for instruction AI on how to update rulesync rules, and what the syntax is for the frontmatter.
- Is it expected that a rulesync user will edit rules in the AI tool of their choice, then re-import them? Or is the target use case for those who wish to import and thereafter maintain `.rulesync/rules/*.md`?
</file>
<file path="pages/rulesync___log___25___10___04 Sat - Issues with gitignore.md">
### [[2025-10-04 Sat]] - [[git/.gitignore]] issues
id:: 68e0f877-fcfc-438c-a9d8-a9d625d68232
- Yesterday I discovered that the [[rulesync/gitignore]] command implies a usage of rulesync in which the configuration files for any given tool are treated as compiled build artifacts. I was curious about trying out this workflow, so I ran it, which added a bunch of rules to `.gitignore` for each [[AI/Coding/Tool]] - [[CursorAI]], [[Claude Code]], etc.
- Today, on another computer I discovered the classic problem with introducing [[git/.gitignore]] rules after some subset of files have been tracked to the repo. I asked Claude Code about it.
- #### [[AI/Response]]
- The `.gitignore` patterns (lines 24-25 and 29-31) will only prevent untracked files from being added, but they don't affect files that are already in the git repository.
- Here's what happened:
- 1. These files were previously committed to your repository
- 2. When you ran rulesync generate, it modified these already-tracked files
- 3. Git shows them as modified because they're already being tracked
- 4. The `.gitignore` patterns don't apply to files already in git's tracking
- To fix this, you have two options:
- **Option 1**: Remove these files from git tracking (recommended if you want rulesync to manage them independently):
- `git rm --cached .cursor/rules/*.mdc .github/instructions/*.instructions.md CLAUDE.md .claude/memories/*.md`
- **Option 2**: Keep them tracked and commit the changes (if you want these in version control):
- `git add .cursor/rules/ .github/instructions/ CLAUDE.md .claude/memories/
git commit -m "chore: update generated AI tool rules"`
- So, what do I want to do?
- #### Option 1 - Remove AI configuration files in repo
- ###### Pros
- Some [[Search]] tools (like [[PyCharm]]) can respect [[git/.gitignore]], and it would be convenient to not pollute the search space with a bunch of duplicate information.
- It will be clearer to AI coding tools that respect gitignore which are the "canonical" versions of the files, which will be particularly useful in the common use case of asking AI tools to updating AI rules files.
- ##### Cons
- Sometimes when I talk to people about how I accomplish certain things with AI, it's helpful to be able to hyperlink them to the exact prompt I use, and for many, it would be less confusing if that rule were in the format that they know.
- I have to regenerate them regularly, which implies running them in a post-checkout hook.
- #### Option 2 - Keep AI configuration files in repo
- ##### Pros
- No need to regenerate them each time; one would regenerate every time a rule is updated, and then commit the changes
- I can refer coders (be they human or AI) to a file in github that has the version of my rule in their framework of choice.
- ##### Cons
- Often times I update AI configuration files in the middle of a task. Explaining to AI how to carefully stage only the items related to an AI configuration change when the git stage is dirty might be tricky and unreliable.
- I ended up filing [[rulesync/GitHub/Issue/25/10/Feature request rulesync githook]]
</file>
<file path="pages/rulesync___log___25___10___07 Tue - DRYing out AI Coding Configs.md">
# [[2025-10-07 Tue]]
- ## How to [[DRY]] out [[AI/Coding/Config]]s
- ### Thinking About [[rulesync/GitHub/Issue/25/09/Brainstorm needed - how to share some rules across repos, but not all i329]]
- Rules, commands, subagents and other AI coding configurations need to be defined at different scopes. In general, there's a need for `public`, `team` and `private` scopes. In addition, within each of these, sub-scopes would be necessary for individual projects and specific technologies.
- Here are some examples that illustrate why three high-level scopes—`public`, `team`, `private`—and their sub-scopes (per-technology and per-project) are all useful. They are grouped by scope, then shown a few sub-scope situations for each.
- ### 1. PUBLIC SCOPE (usable by anyone, even outside the company)
- "General Secure-Coding Rules"
- Lint-style guardrails: *"Always sanitize user input before DB insertion."*
- Works for every repo, language, and organisation; no sensitive data.
- "Inclusive Language Checker" command
- Shell-style command a developer can call: `check-inclusive-language`.
- Prompts the AI to flag non-inclusive terms in docs or code comments.
- "Open-Source License Explainer" subagent
- User can ask: *"Is GPL-3 compatible with MIT for this file?"*
- Perfectly safe to share with the broader open-source community.
- Public • Technology sub-scope
- A public FastAPI rule pack: *"When creating FastAPI endpoints, always return Pydantic models, never raw dicts."*
- Public • Project sub-scope
- Open-source SDK project: *"SDK must not depend on non-standard library modules."*
- ### 2. TEAM SCOPE (shared only by the internal engineering org)
- "Company Commit-Message Convention" rule
- *"Always start commit messages with `[JIRA-ticket]`."*
- "Standard Staging-Env Spin-Up" command
- Command: `spin-up-staging`.
- AI agent runs Terraform in a specific AWS account that only the team uses.
- "Logging Style Enforcer" subagent
- Looks at any log lines and rewrites them to match the org's `jsonlog` schema.
- Team • Technology sub-scope
- TypeScript CLI rule set: *"Disallow `console.log`; use our `logger.ts` wrapper."*
- Team • Project sub-scope
- "Mobile-App" subagent that knows the internal feature flag system used only by the mobile team.
- ### 3. PRIVATE SCOPE (individual or very restricted use)
- "Experimental Algorithm" rule
- Describes proprietary heuristics for an upcoming product feature.
- Only the inventor keeps this in her personal repo.
- "Internal Metrics Dashboard" command
- Command: `query-sales-funnel`. Hits an internal Grafana API with a secret token.
- "Contract-Drafting" subagent
- Personal-use GPT-based helper that loads the user's saved prompts and legal templates.
- Private • Technology sub-scope
- GPU-cluster optimisation rules the research team is experimenting with, hidden from everyone else.
- Private • Project sub-scope
- One-off migration script commands for a stealth project codenamed "Project Quartz".
- ### Why the distinctions matter
- Public vs. Team vs. Private keeps confidential knowledge isolated.
- Technology sub-scopes avoid polluting every repo with rules that only apply to, say, FastAPI or React.
- Project sub-scopes stop cross-talk (the "mobile" rules don't appear in the "data-pipeline" repo).
- Let's elaborate a bit on specific recommendations for how teams and developers could use `rulesync` in a way that better honors the [[Software/Engineering/Principle/DRY]] (Don't Repeat Yourself).
- ### [[Markdown/Frontmatter/Yaml]] `remote` Config Key
- In the `.rulesync/{commands,rules,subagents,...}/*.md`'s yaml frontmatter, you could support a yaml key like `remote` which could have a pointer to where the command/rule/subagent definition was located:
- Places with a risk of prompt injection
- a webpage on the internet
- a file in another github (or gitlab, or any SCM) repo
- Places with mitigated risks of prompt injection
- a local file outside of the repository
- a pointer to a file within a
- Then upon `rulesync generate`, it would pull in the rule file into the `targets`.
- As indicated above, there are issues. Introducing a `remote` key may encourage less experienced engineers to open up their system to prompt injection.
- ### Rulesync `include` Config Keys
- `rulesync.jsonc` could support a config like the following
- #### Proposed extension: rulesync.jsonc → "include" array
- Top-level schema change:
- ~~~
{
...
"include": [<IncludeObject>, <IncludeObject>, ...]
}
~~~
- If `include` is absent or empty, current behaviour is unchanged.
- Entries are evaluated **in array order**; each may add, merge or override files that ultimately flow into the local `.rulesync` workspace.
- #### IncludeObject specification
- ##### Required
- `repo` (`string`): URI, URL, or relative path that resolves to a Git repository containing a `.rulesync` folder.
- ##### Optional
- `ref` (`string`): Git reference (commit SHA, tag, or branch). Default = repository default branch.
- `subDir` (`string`): Path inside the repo where the root `.rulesync` directory lives if it is **not** at repo root.
- `features` (`array<string>` | `"*"`): Subset of tool-agnostic "features" to import: `"rules"`, `"commands"`, `"ignore"`, `"mcp"`, `"subagents"`. Default = `"*"` (all recognised features).
- `patterns` (`array<string>` | `Record<Feature,array<string>>`): Glob patterns (minimatch style) applied **after** `features` filtering. Shorthand array applies to every selected feature; map form lets you specify per-feature patterns.
- Example:
- ~~~
"patterns": {
"rules": ["**/fastapi/**", "!**/experimental/**"],
"commands": ["deploy-prod.md"]
}
~~~
- `select` (`Record<Feature,array<string>>`): Explicit file list (relative to the feature directory) that must be present. If `select` is provided for a feature, it overrides `patterns` for that feature.
- `exclude` (`array<string>`): Additional glob exclusions applied last, across all chosen features.
- `mode` (`"merge"` | `"override"`): merge – included files are added only when **no** equally-named file exists locally. override – included files replace conflicting local files. Default = "merge".
- `rename` (`Record<string,string>`): Mapping `sourcePath → targetPath` (paths relative to their feature roots) for files that need to land under a different name locally.
- `transform` (`string`): Command (executed with the file streamed to STDIN, transformed content from STDOUT) that post-processes each included file. Optional ‑ for advanced use only.
- #### Resolution rules & precedence
- 1. Iterate through `include` array in order.
- 2. For each IncludeObject:
- a. Clone or fetch `repo` at `ref`.
- b. Identify the `.rulesync` directory (`/` by default or `subDir`).
- c. Filter by `features`, then `patterns`, then `select`, then `exclude`.
- d. For each remaining file, determine destination path (after optional `rename`).
- e. Apply `transform` if present.
- f. Place file into the local staging area, respecting `mode`.
- 3. After all includes are processed, run the normal local generation / export logic.
- #### Illustrative examples
- ##### Example 1 – Pull in a public rule pack verbatim
- ~~~
"include": [
{
"repo": "https://github.com/public-ai/rules-general.git",
"ref": "v1.0.3",
"mode": "merge"
}
]
~~~
- ##### Example 2 – Cherry-pick FastAPI rules and two deployment commands from an internal repo
- ~~~
"include": [
{
"repo": "git@github.com:mycorp/fastapi-rules.git",
"features": ["rules", "commands"],
"patterns": {
"rules": ["fastapi/**"],
"commands": ["deploy-staging.md", "deploy-prod.md"]
},
"exclude": ["**/legacy/**"],
"mode": "override"
}
]
~~~
- ##### Example 3 – Rename and transform a private subagent definition
- ~~~
"include": [
{
"repo": "../personal-ai-snippets",
"features": ["subagents"],
"select": { "subagents": ["draft-legalese.md"] },
"rename": { "draft-legalese.md": "private/draft-legalese.md" },
"transform": "sed 's/ACME_CORP/FOOBAR_INC/g'"
}
]
~~~
- #### Error handling
- Missing repo, unreachable ref, or absent `.rulesync` directory → hard error; generation stops.
- `select` item not found → hard error.
- Overwrite conflicts when `mode == "merge"` → warning; local file is kept.
- `transform` exit code ≠ 0 → hard error for that file.
- #### Compatibility note
- The new `include` key is entirely additive. Existing projects without it run exactly as before.
</file>
<file path="pages/rulesync___log___25___10___11 Sat - globs and simulated commands.md">
- [[2025-10-11 Sat]]
- ## Filed [[rulesync/GitHub/Issue/25/10/README clarification on simulated subagents and commands i388]] [README clarification on simulated commands and subagents · Issue #388 · dyoshikawa/rulesync](https://github.com/dyoshikawa/rulesync/issues/388)
- I think the README [section on simulated commands and subagents](https://github.com/dyoshikawa/rulesync?tab=readme-ov-file#-simulated-commands-and-subagents) could be clearer.
- I think of "simulated" commands like when I at-mention a specific cursor project rule ([Project Rules | Cursor Docs](https://cursor.com/docs/context/rules#project-rules): rule type `Manual` are "Only included when explicitly mentioned using @ruleName"). I think I have an idea of what these are because I think I used them in Cursor in the [bmad-code-org/BMAD-METHOD: Breakthrough Method for Agile Ai Driven Development](https://github.com/bmad-code-org/BMAD-METHOD/tree/main).
- Specifically, I think having an explanation for the motivation for why they exist and when one might want to use them or why they are necessary (e.g. in Claude Code you could do `/pr-review` but in Cursor you need to do `@pr-review`) as well what the caveats are for them would be helpful.
- My understanding is that one would only ever use "simulated" commands or subagents in an agentic coding tool that didn't actually support commands or subagents.
- Right now the readme says,
- > This is useful for shortening your prompts.
- This part makes me think I don't understand them the same way. Can you help me understand how they shorten prompts?
- Commands in general do save on context relative to rules ... is that what you meant?
- ## Filed [[rulesync/GitHub/Issue/25/10/Documentation clarification on globs i389]]
- The documentation could benefit from some clarifications on how the `globs` parameter impacts different coding agents.
My thoughts about what belongs in documentation for a library may be subtly changing due to deepwiki, though. I used [[rulesync/DeepWiki]] #DeepWiki [rulesync's deepwiki](https://deepwiki.com/search/what-formats-of-globs-can-i-us_146d4d84-894f-4a54-8f13-4fd11d3a87d0) to answer the following questions. Who knows, maybe in the future we will just use these types of auto-generated documentation with attached chatbots instead of fixing every use case into prose.
- ## What formats of globs can I use in rulesync?
- Suspected answer (deepwiki):
- > The glob implementation is handled by the standard [glob library's globSync](https://github.com/isaacs/node-glob?tab=readme-ov-file#usage)
- ## Are the globs relative to the root directory?
- Suspected answer (deepwiki):
- > Yes, glob patterns are relative to the project root directory. The implementation ... resolves patterns relative to the current working directory (the project root).
- ## What if I reference a file path in a project rule or a command? Some tools have specific syntaxes for this; for example, [claude code has both file-relative "import" syntax `@docs/git-instructions.md`](https://docs.claude.com/en/docs/claude-code/memory#claude-md-imports) and project-relative "import" syntax `@~/.claude/my-project-instructions.md`, and cursor [has a similar @path/to/file/from/project/root](https://cursor.com/docs/context/rules#rule-anatomy) syntax
- [Suspected answer (deepwiki):](https://deepwiki.com/search/what-formats-of-globs-can-i-us_146d4d84-894f-4a54-8f13-4fd11d3a87d0)
- > Rulesync does not currently perform automatic conversion of file path references between different tools' syntaxes. When you write content in .rulesync/rules/*.md or .rulesync/commands/*.md files, the body content is passed through to tool-specific files without modification. ... The @ symbol you mentioned appears in rulesync's reference section generation, but this is a different feature.
-
</file>
<file path="pages/rulesync___log___25___11___10 Mon - on abstraction costs and plugin marketplaces.md">
## High Level Reflections
- Corey Doctorow's books (particularly [[Person/Corey Doctorow/Book/25/Picks & Shovels]] and [[Person/Corey Doctorow/Book/25/Enshittification]]) have taught me that [[Interop]] tools like `rulesync` are important because in the age of AI, vendor lock-in is likely to become a serious issue. [[pandoc]] could serve as an example for how to do an interop tool like `rulesync`
- But the pace of AI progress is fast. The feature surface area of the underlying tools is exploding. The cost of using and maintaining an abstraction layer like `rulesync` is becoming high. If I keep my canonical [[AI/Coding/Config]]s in `rulesync`'s formats, then I can't easily use the latest features of Claude Code, such as
- [Support for Claude Skills · Issue #422 · dyoshikawa/rulesync](https://github.com/dyoshikawa/rulesync/issues/422)
- [Feature request: for claude code slash commands, support passing through claude-code-specific yaml markdown frontmatter keys to the generated command markdown files · Issue #413 · dyoshikawa/rulesync](https://github.com/dyoshikawa/rulesync/issues/413)
- [Support for Claude Code plugins and Gemini CLI extensions · Issue #382 · dyoshikawa/rulesync](https://github.com/dyoshikawa/rulesync/issues/382)
- In the past couple weeks, as Claude Code Skills emerged, I stopped primarily using `rulesync` because the latest features can't be represented in rulesync's format yet.
I have been thinking about [Programmatic API · Issue #377 · dyoshikawa/rulesync](https://github.com/dyoshikawa/rulesync/issues/377), and from the perspective of someone using the tool, maybe it could make sense to optimize for lossless modeling of AI code configs and best effort conversion.
- ### Proposed rulesync architectural assumptions
- 1 - **assume users will store AI code configs some AI coding tool's native format**, whether that's cursor, claude code, or any of the many tools that are out there
- 2 - **optimize rulesync for "lossless conversion" within each tool**. This means that if I store my configs in Claude Code, then if I import into rulesync, then wipe away my `.claude` directory and regenerate from rulesync, every file and folder should work the way it did before.
- 3 - **make rulesync "best effort" or "lossy" between tools**. The tools are not always going to have feature parity with each other, and the concepts are not going to match. Rulesync would
- ### Benefits of this approach
- Even if tool X adds feature Y which hasn't been added as a feature to rulesync, a user can still use feature Y until it's supported for conversion.
- ### What could this look like?
- 1 - `rulesync` could assume that one tool is the "parent" from which other code configs are adapted from that source
-
</file>
<file path="pages/rulesync___log.md">
## [[rulesync]] - [[My Notes]]
- see sub-pages
</file>
<file path="pages/rulesync___mise.md">
- [[mise]] config
- ```toml
[tasks.rulesync]
# https://github.com/dyoshikawa/rulesync/tree/main
description = "Node.js CLI tool to sync AI coding rules across multiple tools."
run = "npx rulesync $@"
```
</file>
<file path=".rulesync/skills/rulesync/case-studies.md">
# Case Studies
Rulesync is trusted by leading companies and recognized by the industry:
- **Anthropic Official Customer Story**: [Classmethod Inc. - Improving AI coding tool consistency with Rulesync](https://claude.com/customers/classmethod)
- **Asoview Inc.**: [Adopting Rulesync for unified AI development rules](https://tech.asoview.co.jp/entry/2025/12/06/100000)
- **KAKEHASHI Tech Blog**: [Building multilingual systems for the LLM era with a monorepo and a "living specification"](https://kakehashi-dev.hatenablog.com/entry/2025/12/08/110000)
- **Cloudflare**: [Adopting Rulesync for AI coding assistant configuration](https://github.com/cloudflare/cloudflare-docs/pull/28232)
</file>
<file path=".rulesync/skills/rulesync/cli-commands.md">
# CLI Commands
## Quick Commands
```bash
# Initialize new project (recommended: organized rules structure)
rulesync init
# Import existing configurations (to .rulesync/rules/ by default)
rulesync import --targets claudecode --features rules,ignore,mcp,commands,subagents,skills
# Fetch configurations from a Git repository
rulesync fetch owner/repo
rulesync fetch owner/repo@v1.0.0 --features rules,commands
rulesync fetch https://github.com/owner/repo --conflict skip
# Generate all features for all tools (new preferred syntax)
rulesync generate --targets "*" --features "*"
# Generate specific features for specific tools
rulesync generate --targets copilot,cursor,cline --features rules,mcp
rulesync generate --targets claudecode --features rules,subagents
# Generate only rules (no MCP, ignore files, commands, or subagents)
rulesync generate --targets "*" --features rules
# Generate simulated commands and subagents
rulesync generate --targets copilot,cursor,codexcli --features commands,subagents --simulate-commands --simulate-subagents
# Dry run: show changes without writing files
rulesync generate --dry-run --targets claudecode --features rules
# Check if files are up to date (for CI/CD pipelines)
rulesync generate --check --targets "*" --features "*"
# Install skills from declarative sources in rulesync.jsonc
rulesync install
# Force re-resolve all source refs (ignore lockfile)
rulesync install --update
# Fail if lockfile is missing or out of sync (for CI); fetch missing skills using locked refs
rulesync install --frozen
# Install then generate (typical workflow)
rulesync install && rulesync generate
# Add generated files to .gitignore
rulesync gitignore
# Update rulesync to the latest version (single-binary installs)
rulesync update
# Check for updates without installing
rulesync update --check
# Force update even if already at latest version
rulesync update --force
```
## Fetch Command
The `fetch` command allows you to fetch configuration files directly from a Git repository (GitHub/GitLab).
> [!NOTE]
> This feature is in development and may change in future releases.
**Note:** The fetch command searches for feature directories (`rules/`, `commands/`, `skills/`, `subagents/`, etc.) directly at the specified path, without requiring a `.rulesync/` directory structure. This allows fetching from external repositories like `vercel-labs/agent-skills` or `anthropics/skills`.
### Source Formats
```bash
# Full URL format
rulesync fetch https://github.com/owner/repo
rulesync fetch https://github.com/owner/repo/tree/branch
rulesync fetch https://github.com/owner/repo/tree/branch/path/to/subdir
rulesync fetch https://gitlab.com/owner/repo # GitLab (planned)
# Prefix format
rulesync fetch github:owner/repo
rulesync fetch gitlab:owner/repo # GitLab (planned)
# Shorthand format (defaults to GitHub)
rulesync fetch owner/repo
rulesync fetch owner/repo@ref # Specify branch/tag/commit
rulesync fetch owner/repo:path # Specify subdirectory
rulesync fetch owner/repo@ref:path # Both ref and path
```
### Options
| Option | Description | Default |
| ----------------------- | ------------------------------------------------------------------------------------------ | -------------------------------- |
| `--target, -t <target>` | Target format to interpret files as (e.g., 'rulesync', 'claudecode') | `rulesync` |
| `--features <features>` | Comma-separated features to fetch (rules, commands, subagents, skills, ignore, mcp, hooks) | `*` (all) |
| `--output <dir>` | Output directory relative to project root | `.rulesync` |
| `--conflict <strategy>` | Conflict resolution: `overwrite` or `skip` | `overwrite` |
| `--ref <ref>` | Git ref (branch/tag/commit) to fetch from | Default branch |
| `--path <path>` | Subdirectory in the repository | `.` (root) |
| `--token <token>` | Git provider token for private repositories | `GITHUB_TOKEN` or `GH_TOKEN` env |
### Examples
```bash
# Fetch skills from external repositories
rulesync fetch vercel-labs/agent-skills --features skills
rulesync fetch anthropics/skills --features skills
# Fetch all features from a public repository
rulesync fetch dyoshikawa/rulesync --path .rulesync
# Fetch only rules and commands from a specific tag
rulesync fetch owner/repo@v1.0.0 --features rules,commands
# Fetch from a private repository (uses GITHUB_TOKEN env var)
export GITHUB_TOKEN=ghp_xxxx
rulesync fetch owner/private-repo
# Or use GitHub CLI to get the token
GITHUB_TOKEN=$(gh auth token) rulesync fetch owner/private-repo
# Preserve existing files (skip conflicts)
rulesync fetch owner/repo --conflict skip
# Fetch from a monorepo subdirectory
rulesync fetch owner/repo:packages/my-package
```
</file>
<file path=".rulesync/skills/rulesync/configuration.md">
# Configuration
You can configure Rulesync by creating a `rulesync.jsonc` file in the root of your project.
## JSON Schema Support
Rulesync provides a JSON Schema for editor validation and autocompletion. Add the `$schema` property to your `rulesync.jsonc`:
```jsonc
// rulesync.jsonc
{
"$schema": "https://raw.githubusercontent.com/dyoshikawa/rulesync/refs/heads/main/config-schema.json",
"targets": ["claudecode"],
"features": ["rules"],
}
```
## Configuration Options
Example:
```jsonc
// rulesync.jsonc
{
"$schema": "https://raw.githubusercontent.com/dyoshikawa/rulesync/refs/heads/main/config-schema.json",
// List of tools to generate configurations for. You can specify "*" to generate all tools.
"targets": ["cursor", "claudecode", "geminicli", "opencode", "codexcli"],
// Features to generate. You can specify "*" to generate all features.
"features": ["rules", "ignore", "mcp", "commands", "subagents", "hooks"],
// Alternatively, you can use object format to specify features per target:
// "features": {
// "claudecode": ["rules", "commands"],
// "cursor": ["rules", "mcp"],
// },
// Base directories for generation.
// Basically, you can specify a `["."]` only.
// However, for example, if your project is a monorepo and you have to launch the AI agent at each package directory, you can specify multiple base directories.
"baseDirs": ["."],
// Delete existing files before generating
"delete": true,
// Verbose output
"verbose": false,
// Silent mode - suppress all output (except errors)
"silent": false,
// Advanced options
"global": false, // Generate for global(user scope) configuration files
"simulateCommands": false, // Generate simulated commands
"simulateSubagents": false, // Generate simulated subagents
"simulateSkills": false, // Generate simulated skills
// Declarative skill sources — installed via 'rulesync install'
// See the "Declarative Skill Sources" section for details.
// "sources": [
// { "source": "owner/repo" },
// { "source": "org/repo", "skills": ["specific-skill"] },
// ],
}
```
## Per-Target Features
The `features` option accepts both an array and an object format. Use the object format when you want to generate different features for different targets:
```jsonc
// rulesync.jsonc
{
"targets": ["claudecode", "cursor", "copilot"],
"features": {
"claudecode": ["rules", "commands"],
"cursor": ["rules", "mcp"],
"copilot": ["rules", "subagents"],
},
}
```
In this example:
- `claudecode` generates rules and commands
- `cursor` generates rules and MCP configuration
- `copilot` generates rules and subagents
You can also use `*` (wildcard) for specific targets:
```jsonc
{
"targets": ["claudecode", "cursor"],
"features": {
"claudecode": ["*"], // Generate all features for Claude Code
"cursor": ["rules"], // Only rules for Cursor
},
}
```
## Local Configuration
Rulesync supports a local configuration file (`rulesync.local.jsonc`) for machine-specific or developer-specific settings. This file is automatically added to `.gitignore` by `rulesync gitignore` and should not be committed to the repository.
**Configuration Priority** (highest to lowest):
1. CLI options
2. `rulesync.local.jsonc`
3. `rulesync.jsonc`
4. Default values
Example usage:
```jsonc
// rulesync.local.jsonc (not committed to git)
{
"$schema": "https://raw.githubusercontent.com/dyoshikawa/rulesync/refs/heads/main/config-schema.json",
// Override targets for local development
"targets": ["claudecode"],
// Enable verbose output for debugging
"verbose": true,
}
```
## Target Order and File Conflicts
When multiple targets write to the same output file, **the last target in the array wins**. This is the "last-wins" behavior.
For example, both `agentsmd` and `opencode` generate `AGENTS.md`:
```jsonc
{
// opencode wins because it comes last
"targets": ["agentsmd", "opencode"],
"features": ["rules"],
}
```
In this case:
1. `agentsmd` generates `AGENTS.md` first
2. `opencode` generates `AGENTS.md` second, overwriting the previous file
If you want `agentsmd`'s output instead, reverse the order:
```jsonc
{
// agentsmd wins because it comes last
"targets": ["opencode", "agentsmd"],
"features": ["rules"],
}
```
</file>
<file path=".rulesync/skills/rulesync/declarative-sources.md">
# Declarative Skill Sources
Rulesync can fetch skills from external GitHub repositories using the `install` command. Instead of manually running `fetch` for each skill source, declare them in your `rulesync.jsonc` and run `rulesync install` to resolve and fetch them. Then `rulesync generate` picks them up as local curated skills. Typical workflow: `rulesync install && rulesync generate`.
## Configuration
Add a `sources` array to your `rulesync.jsonc`:
```jsonc
{
"$schema": "https://raw.githubusercontent.com/dyoshikawa/rulesync/refs/heads/main/config-schema.json",
"targets": ["copilot", "claudecode"],
"features": ["rules", "skills"],
"sources": [
// Fetch all skills from a repository
{ "source": "owner/repo" },
// Fetch only specific skills by name
{ "source": "anthropics/skills", "skills": ["skill-creator"] },
// With ref pinning and subdirectory path (same syntax as fetch command)
{ "source": "owner/repo@v1.0.0:path/to/skills" },
],
}
```
Each entry in `sources` accepts:
| Property | Type | Description |
| -------- | ---------- | ----------------------------------------------------------------------------------------------------------- |
| `source` | `string` | Repository source using the same format as the `fetch` command (`owner/repo`, `owner/repo@ref:path`, etc.). |
| `skills` | `string[]` | Optional list of skill names to fetch. If omitted, all skills are fetched. |
## How It Works
When `rulesync install` runs and `sources` is configured:
1. **Lockfile resolution** — Each source's ref is resolved to a commit SHA and stored in `rulesync.lock` (at the project root). On subsequent runs the locked SHA is reused for deterministic builds.
2. **Remote skill listing** — The `skills/` directory (or the path specified in the source URL) is listed from the remote repository.
3. **Filtering** — If `skills` is specified, only matching skill directories are fetched.
4. **Precedence rules**:
- **Local skills always win** — Skills in `.rulesync/skills/` (not in `.curated/`) take precedence; a remote skill with the same name is skipped.
- **First-declared source wins** — If two sources provide a skill with the same name, the one declared first in the `sources` array is used.
5. **Output** — Fetched skills are written to `.rulesync/skills/.curated/<skill-name>/`. This directory is automatically added to `.gitignore` by `rulesync gitignore`.
## CLI Options
The `install` command accepts these flags:
| Flag | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--update` | Force re-resolve all source refs, ignoring the lockfile (useful to pull new updates). |
| `--frozen` | Fail if lockfile is missing or out of sync. Fetches missing skills using locked refs without updating the lockfile. Useful for CI to ensure reproducibility. |
| `--token <token>` | GitHub token for private repositories. |
```bash
# Install skills using locked refs
rulesync install
# Force update to latest refs
rulesync install --update
# Strict CI mode — fail if lockfile doesn't cover all sources (missing locked skills are fetched)
rulesync install --frozen
# Install then generate
rulesync install && rulesync generate
# Skip source installation — just don't run install
rulesync generate