heymark 1.2.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/README.ko.md +63 -110
  2. package/README.md +65 -110
  3. package/package.json +3 -3
  4. package/scripts/cli.js +375 -0
  5. package/scripts/lib/config.js +30 -14
  6. package/scripts/lib/repo.js +14 -14
  7. package/scripts/tools/antigravity.js +5 -9
  8. package/scripts/tools/claude.js +5 -9
  9. package/scripts/tools/codex.js +5 -9
  10. package/scripts/tools/copilot.js +5 -9
  11. package/scripts/tools/cursor.js +5 -9
  12. package/scripts/sync.js +0 -330
package/README.ko.md CHANGED
@@ -1,54 +1,61 @@
1
1
  # Heymark
2
2
 
3
- AI 코딩 도구별 Skill 문서를 단일 위치에서 관리하고, 각 도구 형식으로 자동 변환하는 도구입니다.
4
- 한 번 작성한 Markdown 소스를 여러 에이전트 도구에 맞춰 재사용할 수 있습니다.
3
+ Heymark는 하나의 Skill 저장소를 여러 AI Tool 형식으로 변환하고 동기화하는 허브 시스템입니다.
5
4
 
6
5
  1. [Overview](#overview)
7
6
  2. [Features](#features)
8
- 3. [Supported Agent Tools](#supported-agent-tools)
9
- 4. [Tech Stack](#tech-stack)
10
- 5. [Heymark Usage](#heymark-usage)
11
- 6. [Heymark Development](#heymark-development)
7
+ 3. [Supported Tools](#supported-tools)
8
+ 4. [How to Use](#how-to-use)
9
+ 5. [How to Dev](#how-to-dev)
12
10
 
13
11
  ## Overview
14
12
 
15
- 프로젝트마다 AI 도구별 Skill 파일을 따로 관리하면 문서가 분산되고 유지보수 비용이 커집니다.
16
- Heymark는 단일 진실 공급원(Single Source of Truth) 원칙으로, 하나의 Markdown 소스를 여러 도구 형식으로 변환합니다.
17
- 한 번 작성한 Skill을 Cursor, Claude Code, GitHub Copilot, OpenAI Codex, Antigravity에서 바로 사용할 수 있습니다.
13
+ AI Tool은 프롬프트 문맥에 맞는 Skill을 로드해 반복적인 지시문 입력을 줄이는 기능을 지원합니다.
14
+ 이 기능을 사용하면 공통 작업을 표준화하고, 팀 내에서 일관된 작업 기준을 유지할 수 있다는 장점이 있습니다.
15
+ 하지만 프로젝트마다 Skill을 개별적으로 연결하고 관리해야 하며, AI Tool마다 요구하는 Skill 파일 형식도 달라
16
+ 같은 내용을 여러 형식으로 반복 관리해야 하는 불편이 있습니다.
17
+ Heymark는 단일 Skill 저장소(Single Source of Truth)를 중심으로 도구별 형식 변환과 동기화를 자동화해,
18
+ 반복 운영 비용을 줄이고 AI 활용 효율을 극대화합니다.
19
+
20
+ <img width="600" alt="image" src="https://github.com/user-attachments/assets/3819f0d7-9bb2-474f-a58a-da3d1344207d" />
21
+
22
+ _프롬프트 문맥에 맞는 Skill을 자동 로드하는 모습입니다._
18
23
 
19
24
  ## Features
20
25
 
21
- - 단일 소스 관리: Markdown 파일 하나로 여러 AI 도구의 Skill을 통합 관리
22
- - 자동 형식 변환: 각 도구의 네이티브 형식으로 자동 변환 (YAML frontmatter, AGENTS.md 등)
23
- - 선택적 변환: 필요한 도구만 선택해서 변환 가능
24
- - NPM 패키지 배포: npx 기반으로 설치 없이 실행 가능
25
- - 플러그인 구조: 변환 모듈을 추가해 지원 도구 확장 가능
26
+ - 단일 소스 관리: Markdown 기반 Skill을 한 곳에서 관리
27
+ - 자동 형식 변환: 도구별 형식으로 Skill 자동 생성
28
+ - 선택 동기화: 전체 또는 특정 도구만 동기화
29
+ - 샘플 Skill 즉시 사용: Skill 저장소 준비 없이 `npx heymark link --samples`로 바로 시작
26
30
 
27
- ## Supported Agent Tools
31
+ ## Supported Tools
28
32
 
29
- | Tool | Output Format | Key Features |
30
- | :------------- | :--------------------------------------- | :------------------------------------------------------- |
31
- | Cursor | `.cursor/rules/*.mdc` | YAML frontmatter (`description`, `globs`, `alwaysApply`) |
32
- | Claude Code | `.claude/skills/*/SKILL.md` | Skill 디렉터리 구조 + YAML frontmatter |
33
- | GitHub Copilot | `.github/instructions/*.instructions.md` | `applyTo` 다중 패턴 매핑 |
34
- | OpenAI Codex | `.agents/skills/*/SKILL.md` | Skill 디렉터리 구조 + YAML frontmatter |
35
- | Antigravity | `.agent/skills/*/SKILL.md` | Skill 디렉터리 구조 + YAML frontmatter |
33
+ | Tool | Output Format |
34
+ | :------------- | :--------------------------------------- |
35
+ | Cursor | `.cursor/rules/*.mdc` |
36
+ | Claude Code | `.claude/skills/*/SKILL.md` |
37
+ | GitHub Copilot | `.github/instructions/*.instructions.md` |
38
+ | OpenAI Codex | `.agents/skills/*/SKILL.md` |
39
+ | Antigravity | `.agent/skills/*/SKILL.md` |
36
40
 
37
- ## Tech Stack
41
+ ## How to Use
38
42
 
39
- - Runtime: Node.js
40
- - Language: JavaScript
41
- - Core: File system API, YAML frontmatter parsing
43
+ ### Prepare Skill Repository
42
44
 
43
- ## Heymark Usage
45
+ Skill 저장소는 아래처럼 구성하면 됩니다.
44
46
 
45
- ### 1. Prepare the Skill Markdown Archive Repository
47
+ ```text
48
+ my-skills-repository/
49
+ ai-behavior.md
50
+ code-conventions.md
51
+ api-skills.md
52
+ ```
46
53
 
47
- Skill 소스 디렉터리(외부 또는 개인 GitHub 저장소)에 Markdown 파일을 작성하고, YAML frontmatter로 메타데이터를 정의합니다.
54
+ 각 Skill Markdown에는 frontmatter를 포함합니다.
48
55
 
49
56
  ```markdown
50
57
  ---
51
- description: "AI assistant behavior guidelines"
58
+ description: "AI coding behavior guidelines"
52
59
  globs: "**/*.ts,**/*.tsx"
53
60
  alwaysApply: true
54
61
  ---
@@ -58,113 +65,59 @@ alwaysApply: true
58
65
  Skill content...
59
66
  ```
60
67
 
61
- 저장소 구조는 다음처럼 단순하게 구성하면 됩니다.
62
-
63
- ```text
64
- my-skills-repository/
65
- ai-behavior.md
66
- code-conventions.md
67
- api-skills.md
68
- ```
69
-
70
- Skill 소스는 원격 GitHub 저장소(Public/Private)에서 읽습니다.
71
-
72
- ### 2. Initial Setup
73
-
74
- 최초 1회, 사용할 Skill 소스 저장소를 설정합니다.
68
+ ### Quick Start
75
69
 
76
70
  ```bash
77
- # Skill 소스 설정 (.heymark/config.json 생성)
78
- npx heymark init <GitHub-저장소-URL>
71
+ npx heymark link --samples # 샘플 Skill 바로 연결
72
+ npx heymark sync .
79
73
  ```
80
74
 
81
- ```bash
82
- # HTTPS (Private이면 Git credential/토큰 설정 필요)
83
- npx heymark init https://github.com/org/my-rules.git
84
-
85
- # SSH (Private 저장소 권장)
86
- npx heymark init git@github.com:org/my-rules.git
87
-
88
- # 저장소 안에서 .md가 하위 폴더에 있을 때
89
- npx heymark init https://github.com/org/my-rules.git --dir rules --branch main
90
- ```
75
+ _`link`와 `sync` 실행 후, 각 도구가 요구하는 디렉터리에 Skill 파일이 생성됩니다._
91
76
 
92
- ### 3. Run
77
+ <img width="250" alt="image" src="https://github.com/user-attachments/assets/0e5bc974-12d6-4aab-b0aa-16ca5659f973" />
93
78
 
94
- 설치 없이 npx로 바로 실행할 수 있습니다.
95
- Skill은 외부 GitHub 저장소에서 가져오며, 저장소 내 Markdown 파일을 각 AI 도구 형식으로 변환해 현재 프로젝트에 생성합니다.
79
+ ### Commands
96
80
 
97
81
  ```bash
98
- # .heymark/config.json에 설정된 외부 Skill 저장소에서 가져와 모든 도구 형식으로 변환
99
- # (기존 생성 파일 삭제 후 새로 생성)
100
- npx heymark
101
-
102
- # 단일 실행에서만 다른 외부 저장소 사용 (.heymark/config.json 무시)
103
- npx heymark --source https://github.com/org/other-rules.git
82
+ npx heymark link --samples # 샘플 Skill 바로 연결
104
83
 
105
- # 특정 도구만 변환
106
- npx heymark -t cursor,claude
84
+ npx heymark link <GitHub-저장소-URL> # Skill 저장소 연결
85
+ npx heymark link <GitHub-저장소-URL> --folder <folder-name> # 하위 폴더 사용 시
86
+ npx heymark link <GitHub-저장소-URL> --branch <branch-name> # 다른 브랜치 사용 시
107
87
 
108
- # 미리보기 (파일 생성 없이 변환 결과만 확인)
109
- npx heymark --preview
88
+ npx heymark sync . # 전체 동기화
89
+ npx heymark sync cursor claude # 일부 도구만 동기화
110
90
 
111
- # 이전에 생성된 도구별 파일 삭제
112
- npx heymark --clean
91
+ npx heymark clean . # 전체 정리
92
+ npx heymark clean cursor claude # 일부 도구만 정리
113
93
 
114
- # CLI help
115
- npx heymark --help
94
+ npx heymark status # 상태 확인 (status 생략 가능)
95
+ npx heymark help # 명령어 확인
116
96
  ```
117
97
 
118
- ## Heymark Development
119
-
120
- ### 1. Local Execution
121
-
122
- ```bash
123
- # Skill 소스 설정 (최초 1회, GitHub 저장소 URL)
124
- node scripts/sync.js init https://github.com/org/my-rules.git
98
+ ## How to Dev
125
99
 
126
- # 모든 도구 형식으로 변환
127
- node scripts/sync.js
100
+ ### Tech Stack
128
101
 
129
- # 단일 실행에서만 다른 저장소 사용
130
- node scripts/sync.js --source https://github.com/org/other-rules.git
131
-
132
- # 특정 도구만 변환
133
- node scripts/sync.js -t cursor,claude
102
+ - Runtime: Node.js
103
+ - Language: JavaScript
104
+ - Core: File system API, YAML frontmatter parsing
134
105
 
135
- # 미리보기 (파일 생성 없이 확인)
136
- node scripts/sync.js --preview
106
+ ### Local Development
137
107
 
138
- # 생성된 파일 삭제
139
- node scripts/sync.js --clean
140
- ```
108
+ `How to Use` 섹션의 `npx heymark`를 `node scripts/cli.js`로 바꿔 실행하면 됩니다.
141
109
 
142
- ### 2. Release
110
+ ### Release
143
111
 
144
112
  ```bash
145
- # NPM 로그인
146
113
  npm login
147
- # Username: your-npm-username
148
- # Email: your-email@example.com
149
-
150
- # 1. Skill 수정 후 테스트
151
- node scripts/sync.js --preview
152
-
153
- # 2. 버전 업데이트 (자동으로 Git 태그 생성)
154
114
  npm version patch # 또는 minor, major
155
-
156
- # 3. GitHub에 푸시
157
- git push --follow-tags # 커밋과 태그를 함께 푸시
158
-
159
- # 4. NPM에 배포
115
+ git push --follow-tags
160
116
  npm publish
161
117
  ```
162
118
 
163
- ### 3. Versioning
119
+ ### Versioning
164
120
 
165
121
  - `patch` (1.0.0 -> 1.0.1): 버그 수정, 오타 수정
166
122
  - `minor` (1.0.0 -> 1.1.0): 새 Skill 추가, 기능 개선
167
123
  - `major` (1.0.0 -> 2.0.0): 호환성 깨지는 변경
168
- - `npm version` 명령어는 자동으로 Git 태그를 생성합니다.
169
- - `git push --follow-tags`는 일반 커밋과 태그를 함께 푸시합니다. (권장)
170
- - 또는 `git push && git push --tags`로 커밋 푸시 후 모든 태그를 별도로 푸시할 수 있습니다.
package/README.md CHANGED
@@ -1,54 +1,63 @@
1
1
  # Heymark
2
2
 
3
- Heymark is a tool that manages Skill documentation for AI coding tools in a single location and automatically converts it into each tool format.
4
- A Markdown source written once can be reused across multiple agent tools.
3
+ For the Korean version, see [README.ko.md](README.ko.md).
4
+
5
+ Heymark is a hub system that converts and syncs one Skill repository into multiple AI Tool formats.
5
6
 
6
7
  1. [Overview](#overview)
7
8
  2. [Features](#features)
8
- 3. [Supported Agent Tools](#supported-agent-tools)
9
- 4. [Tech Stack](#tech-stack)
10
- 5. [Heymark Usage](#heymark-usage)
11
- 6. [Heymark Development](#heymark-development)
9
+ 3. [Supported Tools](#supported-tools)
10
+ 4. [How to Use](#how-to-use)
11
+ 5. [How to Dev](#how-to-dev)
12
12
 
13
13
  ## Overview
14
14
 
15
- Managing Skill files separately for each AI tool leads to fragmented documentation and higher maintenance costs.
16
- Heymark follows the Single Source of Truth principle and converts one Markdown source into multiple tool formats.
17
- A Skill written once can be used immediately in Cursor, Claude Code, GitHub Copilot, OpenAI Codex, and Antigravity.
15
+ AI Tools support loading context-aware Skills to reduce repetitive instruction typing.
16
+ This helps standardize common tasks and keeps team workflows consistent.
17
+ However, each project still needs separate Skill linking and management, and each AI Tool requires a
18
+ different Skill file format, so the same content is often maintained multiple times.
19
+ Heymark automates format conversion and sync around a single Skill repository (Single Source of Truth),
20
+ reducing repetitive operational work and maximizing AI workflow efficiency.
21
+
22
+ <img width="600" alt="image" src="https://github.com/user-attachments/assets/3819f0d7-9bb2-474f-a58a-da3d1344207d" />
23
+
24
+ _This shows Skills being automatically loaded based on prompt context._
18
25
 
19
26
  ## Features
20
27
 
21
- - Single source management: Manage Skills for multiple AI tools with one Markdown file
22
- - Automatic format conversion: Convert into each tool's native format (YAML frontmatter, AGENTS.md, etc.)
23
- - Selective conversion: Convert only the tools you need
24
- - NPM package distribution: Run with `npx` without installation
25
- - Plugin structure: Extend supported tools by adding conversion modules
28
+ - Single source management: Manage Markdown-based Skills in one place
29
+ - Automatic format conversion: Generate Skill outputs in each tool's required format
30
+ - Selective sync: Sync all tools or only selected tools
31
+ - Instant sample usage: Start immediately with `npx heymark link --samples` without preparing a Skill repo
26
32
 
27
- ## Supported Agent Tools
33
+ ## Supported Tools
28
34
 
29
- | Tool | Output Format | Key Features |
30
- | :---------- | :--------------------------------------- | :------------------------------------------------------- |
31
- | Cursor | `.cursor/rules/*.mdc` | YAML frontmatter (`description`, `globs`, `alwaysApply`) |
32
- | Claude Code | `.claude/skills/*/SKILL.md` | Skill directory structure + YAML frontmatter |
33
- | Copilot | `.github/instructions/*.instructions.md` | Multi-pattern mapping via `applyTo` |
34
- | Codex | `.agents/skills/*/SKILL.md` | Skill directory structure + YAML frontmatter |
35
- | Antigravity | `.agent/skills/*/SKILL.md` | Skill directory structure + YAML frontmatter |
35
+ | Tool | Output Format |
36
+ | :------------- | :--------------------------------------- |
37
+ | Cursor | `.cursor/rules/*.mdc` |
38
+ | Claude Code | `.claude/skills/*/SKILL.md` |
39
+ | GitHub Copilot | `.github/instructions/*.instructions.md` |
40
+ | OpenAI Codex | `.agents/skills/*/SKILL.md` |
41
+ | Antigravity | `.agent/skills/*/SKILL.md` |
36
42
 
37
- ## Tech Stack
43
+ ## How to Use
38
44
 
39
- - Runtime: Node.js
40
- - Language: JavaScript
41
- - Core: File system API, YAML frontmatter parsing
45
+ ### Prepare Skill Repository
42
46
 
43
- ## Heymark Usage
47
+ You can organize your Skill repository like this:
44
48
 
45
- ### 1. Prepare the Skill Markdown Archive Repository
49
+ ```text
50
+ my-skills-repository/
51
+ ai-behavior.md
52
+ code-conventions.md
53
+ api-skills.md
54
+ ```
46
55
 
47
- Create Markdown files in a Skill source directory (external or personal GitHub repository) and define metadata with YAML frontmatter.
56
+ Each Skill Markdown file should include frontmatter:
48
57
 
49
58
  ```markdown
50
59
  ---
51
- description: "AI assistant behavior guidelines"
60
+ description: "AI coding behavior guidelines"
52
61
  globs: "**/*.ts,**/*.tsx"
53
62
  alwaysApply: true
54
63
  ---
@@ -58,113 +67,59 @@ alwaysApply: true
58
67
  Skill content...
59
68
  ```
60
69
 
61
- You can keep the repository structure simple, as shown below.
62
-
63
- ```text
64
- my-skills-repository/
65
- ai-behavior.md
66
- code-conventions.md
67
- api-skills.md
68
- ```
69
-
70
- Skill sources are read from a remote GitHub repository (Public/Private).
71
-
72
- ### 2. Initial Setup
73
-
74
- For first-time use, configure the Skill source repository once.
70
+ ### Quick Start
75
71
 
76
72
  ```bash
77
- # Configure Skill source (.heymark/config.json will be created)
78
- npx heymark init <GitHub-Repository-URL>
73
+ npx heymark link --samples # quickly link sample Skills
74
+ npx heymark sync .
79
75
  ```
80
76
 
81
- ```bash
82
- # HTTPS (for private repositories, Git credentials/token setup is required)
83
- npx heymark init https://github.com/org/my-rules.git
84
-
85
- # SSH (recommended for private repositories)
86
- npx heymark init git@github.com:org/my-rules.git
87
-
88
- # When .md files are in a subdirectory of the repository
89
- npx heymark init https://github.com/org/my-rules.git --dir rules --branch main
90
- ```
77
+ _After `link` and `sync`, Skill files are generated in each tool's expected directory._
91
78
 
92
- ### 3. Run
79
+ <img width="250" alt="image" src="https://github.com/user-attachments/assets/0e5bc974-12d6-4aab-b0aa-16ca5659f973" />
93
80
 
94
- You can run it directly with `npx` without installation.
95
- Skills are fetched from an external GitHub repository, and Markdown files in that repository are converted into each AI tool format and generated in the current project.
81
+ ### Commands
96
82
 
97
83
  ```bash
98
- # Fetch from the external Skill repository configured in .heymark/config.json and convert to all tool formats
99
- # (delete previously generated files and recreate them)
100
- npx heymark
101
-
102
- # Use a different external repository for this run only (ignore .heymark/config.json)
103
- npx heymark --source https://github.com/org/other-rules.git
84
+ npx heymark link --samples # quickly link sample Skills
104
85
 
105
- # Convert only specific tools
106
- npx heymark -t cursor,claude
86
+ npx heymark link <GitHub-Repository-URL> # link a Skill repository
87
+ npx heymark link <GitHub-Repository-URL> --folder <folder-name> # when using a subfolder
88
+ npx heymark link <GitHub-Repository-URL> --branch <branch-name> # when using another branch
107
89
 
108
- # Preview (check conversion result without creating files)
109
- npx heymark --preview
90
+ npx heymark sync . # sync all tools
91
+ npx heymark sync cursor claude # sync selected tools
110
92
 
111
- # Delete tool-specific files generated previously
112
- npx heymark --clean
93
+ npx heymark clean . # clean all generated outputs
94
+ npx heymark clean cursor claude # clean selected tool outputs
113
95
 
114
- # CLI help
115
- npx heymark --help
96
+ npx heymark status # check status (same as running npx heymark)
97
+ npx heymark help # show command help
116
98
  ```
117
99
 
118
- ## Heymark Development
119
-
120
- ### 1. Local Execution
121
-
122
- ```bash
123
- # Configure Skill source (first-time only, GitHub repository URL)
124
- node scripts/sync.js init https://github.com/org/my-rules.git
100
+ ## How to Dev
125
101
 
126
- # Convert to all tool formats
127
- node scripts/sync.js
102
+ ### Tech Stack
128
103
 
129
- # Use a different repository for this run only
130
- node scripts/sync.js --source https://github.com/org/other-rules.git
131
-
132
- # Convert only specific tools
133
- node scripts/sync.js -t cursor,claude
104
+ - Runtime: Node.js
105
+ - Language: JavaScript
106
+ - Core: File system API, YAML frontmatter parsing
134
107
 
135
- # Preview (check without creating files)
136
- node scripts/sync.js --preview
108
+ ### Local Development
137
109
 
138
- # Delete generated files
139
- node scripts/sync.js --clean
140
- ```
110
+ Replace `npx heymark` in the `How to Use` section with `node scripts/cli.js` for local runs.
141
111
 
142
- ### 2. Release
112
+ ### Release
143
113
 
144
114
  ```bash
145
- # NPM login
146
115
  npm login
147
- # Username: your-npm-username
148
- # Email: your-email@example.com
149
-
150
- # 1. Test after updating Skills
151
- node scripts/sync.js --preview
152
-
153
- # 2. Update version (Git tag is created automatically)
154
116
  npm version patch # or minor, major
155
-
156
- # 3. Push to GitHub
157
- git push --follow-tags # push commits and tags together
158
-
159
- # 4. Publish to NPM
117
+ git push --follow-tags
160
118
  npm publish
161
119
  ```
162
120
 
163
- ### 3. Versioning
121
+ ### Versioning
164
122
 
165
123
  - `patch` (1.0.0 -> 1.0.1): Bug fixes, typo fixes
166
124
  - `minor` (1.0.0 -> 1.1.0): New Skills, feature improvements
167
125
  - `major` (1.0.0 -> 2.0.0): Breaking changes
168
- - The `npm version` command automatically creates a Git tag.
169
- - `git push --follow-tags` pushes normal commits and tags together. (Recommended)
170
- - Alternatively, you can run `git push && git push --tags` to push commits first and then push all tags separately.
package/package.json CHANGED
@@ -1,10 +1,10 @@
1
1
  {
2
2
  "name": "heymark",
3
- "version": "1.2.0",
3
+ "version": "2.0.0",
4
4
  "description": "Rules & Skills Hub for AI Coding Assistants",
5
5
  "type": "commonjs",
6
- "main": "scripts/sync.js",
7
- "bin": "scripts/sync.js",
6
+ "main": "scripts/cli.js",
7
+ "bin": "scripts/cli.js",
8
8
  "keywords": [
9
9
  "ai-coding-assistant",
10
10
  "ai-agent",