Skip to content

Commit 9c867f8

Browse files
author
Joongheon Park
committed
docs(CONTRIBUTING): enhance guidelines for Claude Agent Skills contribution
Added a comprehensive section on contributing to Claude Agent Skills, detailing the directory structure, guidelines for improving existing skills, and steps for adding new skills. Included a contribution checklist and an updated list of existing skills to facilitate better understanding and participation in the development process.
1 parent 0f423f6 commit 9c867f8

2 files changed

Lines changed: 184 additions & 0 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,98 @@ uv run pytest -q
9393
- 사용자에 영향이 있는 변경은 `README.md` 또는 관련 가이드를 함께 업데이트합니다.
9494
- 스캐폴드 템플릿(`act_operator/act_operator/scaffold/`)의 `README.md`/`TEMPLATE_README.md`도 변경 반영이 필요한지 확인합니다.
9595

96+
## Claude Agent Skill 기여
97+
98+
Act Operator 스캐폴드에는 Claude Agent가 Cast 개발을 지원하기 위한 Skill들이 포함되어 있습니다. 이 Skill들을 개선하거나 새로운 Skill을 추가하는 방법을 안내합니다.
99+
100+
### Skill 구조
101+
102+
각 Skill은 다음 디렉터리 구조를 따릅니다:
103+
104+
```
105+
.claude/skills/<skill-name>/
106+
├── SKILL.md # Skill 메인 문서 (필수)
107+
├── references/ # 참조 문서들 (선택)
108+
│ └── *.md
109+
├── scripts/ # 유틸리티 스크립트들 (선택)
110+
│ └── *.py
111+
└── assets/ # 예제 파일들 (선택)
112+
└── *.txt, *.py, etc.
113+
```
114+
115+
### 기존 Skill 개선
116+
117+
**SKILL.md 작성 가이드:**
118+
- **Frontmatter 필수**: YAML frontmatter에 `name`과 `description` 포함
119+
```yaml
120+
---
121+
name: skill-name
122+
description: 명확하고 간결한 설명 - 언제 이 skill을 사용해야 하는지 포함
123+
---
124+
```
125+
- **명확한 사용 시점**: "Use this skill when:" 섹션으로 사용 시나리오 명시
126+
- **구조화된 내용**: Workflow/Task/Reference 패턴 중 적합한 구조 선택
127+
- **실용적인 예제**: 코드 샘플, 체크리스트, 단계별 가이드 포함
128+
- **참조 연결**: 관련 `references/`, `scripts/`, `assets/` 파일 언급
129+
130+
**references/ 문서:**
131+
- API 레퍼런스, 베스트 프랙티스, 패턴 가이드 등
132+
- Markdown 형식으로 작성
133+
- Skill의 메인 문서에서 적절히 링크
134+
135+
**scripts/ 유틸리티:**
136+
- 검증, 자동화, 헬퍼 스크립트 등
137+
- Python 스크립트 권장
138+
- 독립 실행 가능하거나 Skill 컨텍스트에서 사용 가능해야 함
139+
140+
**assets/ 예제:**
141+
- 템플릿, 설정 파일, 예제 코드 등
142+
- Skill 문서에서 참조되는 실제 사용 가능한 예제
143+
144+
### 새 Skill 추가
145+
146+
1. **Skill 디렉터리 생성**
147+
```bash
148+
mkdir -p act_operator/act_operator/scaffold/{{ cookiecutter.act_slug }}/.claude/skills/<skill-name>/{references,scripts,assets}
149+
```
150+
151+
2. **SKILL.md 작성**
152+
- 기존 Skill들(`cast-development`, `act-setup` 등)을 참고하여 구조 작성
153+
- Frontmatter에 명확한 name과 description 포함
154+
- 사용 시점, 워크플로우, 예제 포함
155+
156+
3. **필요한 리소스 추가**
157+
- `references/`: 관련 문서
158+
- `scripts/`: 유틸리티 스크립트
159+
- `assets/`: 예제 파일
160+
161+
4. **테스트 및 검증**
162+
- Skill이 실제 Claude Agent에서 올바르게 작동하는지 확인
163+
- 문서의 예제들이 정확한지 검증
164+
165+
### Skill 기여 체크리스트
166+
167+
- [ ] SKILL.md에 frontmatter(`name`, `description`) 포함
168+
- [ ] "Use this skill when:" 섹션으로 사용 시점 명확히 기술
169+
- [ ] 구조화된 내용(Workflow/Task/Reference 등)
170+
- [ ] 실용적인 예제 및 코드 샘플 포함
171+
- [ ] 관련 references/scripts/assets 파일과 연결
172+
- [ ] 기존 Skill들과 일관된 스타일 유지
173+
- [ ] 문서 내 링크 및 참조가 정확한지 확인
174+
175+
### 기존 Skill 목록
176+
177+
현재 포함된 Skill들:
178+
- **cast-development**: Cast 모듈 개발 (노드, 상태, 그래프 구현)
179+
- **act-setup**: Act 프로젝트 설정 및 uv 워크스페이스 관리
180+
- **graph-composition**: 그래프 구성 및 엣지 연결
181+
- **modules-integration**: 모듈 통합 (agents, tools, prompts 등)
182+
- **node-implementation**: 노드 구현 패턴 및 베스트 프랙티스
183+
- **state-management**: 상태 관리 및 스키마 정의
184+
- **testing-debugging**: 테스트 작성 및 디버깅
185+
186+
새로운 Skill 추가 시 이 목록도 업데이트해주세요.
187+
96188
## 이슈 템플릿 사용
97189
- `.github/ISSUE_TEMPLATE`에 제공된 템플릿을 사용하세요.
98190
- **Backlog**: 기능 제안/백로그 산정/작업 단계 정의

‎CONTRIBUTING_EN.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,98 @@ uv run pytest -q
9595
- If a change affects users, update `README.md` or related guides accordingly.
9696
- Check whether scaffold templates (`act_operator/act_operator/scaffold/`) need updates in `README.md` or `TEMPLATE_README.md`.
9797

98+
## Contributing to Claude Agent Skills
99+
100+
The Act Operator scaffold includes Skills that help Claude Agent support Cast development. This section guides you on how to improve existing Skills or add new ones.
101+
102+
### Skill Structure
103+
104+
Each Skill follows this directory structure:
105+
106+
```
107+
.claude/skills/<skill-name>/
108+
├── SKILL.md # Skill main document (required)
109+
├── references/ # Reference documents (optional)
110+
│ └── *.md
111+
├── scripts/ # Utility scripts (optional)
112+
│ └── *.py
113+
└── assets/ # Example files (optional)
114+
└── *.txt, *.py, etc.
115+
```
116+
117+
### Improving Existing Skills
118+
119+
**SKILL.md Writing Guide:**
120+
- **Required Frontmatter**: Include `name` and `description` in YAML frontmatter
121+
```yaml
122+
---
123+
name: skill-name
124+
description: Clear and concise description - include when to use this skill
125+
---
126+
```
127+
- **Clear Usage Scenarios**: Specify usage scenarios with "Use this skill when:" section
128+
- **Structured Content**: Choose appropriate structure from Workflow/Task/Reference patterns
129+
- **Practical Examples**: Include code samples, checklists, step-by-step guides
130+
- **Reference Links**: Mention related `references/`, `scripts/`, `assets/` files
131+
132+
**references/ Documents:**
133+
- API references, best practices, pattern guides, etc.
134+
- Write in Markdown format
135+
- Link appropriately from the Skill's main document
136+
137+
**scripts/ Utilities:**
138+
- Validation, automation, helper scripts, etc.
139+
- Python scripts recommended
140+
- Should be executable independently or usable within Skill context
141+
142+
**assets/ Examples:**
143+
- Templates, configuration files, example code, etc.
144+
- Real, usable examples referenced in Skill documentation
145+
146+
### Adding a New Skill
147+
148+
1. **Create Skill Directory**
149+
```bash
150+
mkdir -p act_operator/act_operator/scaffold/{{ cookiecutter.act_slug }}/.claude/skills/<skill-name>/{references,scripts,assets}
151+
```
152+
153+
2. **Write SKILL.md**
154+
- Reference existing Skills (`cast-development`, `act-setup`, etc.) for structure
155+
- Include clear name and description in frontmatter
156+
- Include usage scenarios, workflows, examples
157+
158+
3. **Add Required Resources**
159+
- `references/`: Related documents
160+
- `scripts/`: Utility scripts
161+
- `assets/`: Example files
162+
163+
4. **Test and Validate**
164+
- Verify the Skill works correctly in actual Claude Agent
165+
- Validate that examples in documentation are accurate
166+
167+
### Skill Contribution Checklist
168+
169+
- [ ] SKILL.md includes frontmatter (`name`, `description`)
170+
- [ ] "Use this skill when:" section clearly describes usage scenarios
171+
- [ ] Structured content (Workflow/Task/Reference, etc.)
172+
- [ ] Practical examples and code samples included
173+
- [ ] Links to related references/scripts/assets files
174+
- [ ] Consistent style with existing Skills
175+
- [ ] Verify all links and references in documentation are accurate
176+
177+
### Existing Skills List
178+
179+
Currently included Skills:
180+
- **cast-development**: Cast module development (nodes, state, graph implementation)
181+
- **act-setup**: Act project setup and uv workspace management
182+
- **graph-composition**: Graph composition and edge connections
183+
- **modules-integration**: Module integration (agents, tools, prompts, etc.)
184+
- **node-implementation**: Node implementation patterns and best practices
185+
- **state-management**: State management and schema definition
186+
- **testing-debugging**: Test writing and debugging
187+
188+
Please update this list when adding new Skills.
189+
98190
## Issue Templates
99191
- Use templates under `.github/ISSUE_TEMPLATE`.
100192
- **Backlog / Feature Request**: propose new features, define tasks/steps.

0 commit comments

Comments
 (0)