---
name: contributor-pr-workflow
description: "This skill should be used when a contributor wants to submit a new skill, edit an existing skill, or make any change to the Taiwan Architect KB repository. It guides the full lifecycle: clone/fetch, branch, create/edit, self-validate, and submit PR."
license: CC-BY-SA-4.0
compatibility: claude-code,opencode,agent-skills
metadata:
  audience: contributors
  region: taiwan
  class: A
  status: verified
  data-currency: "2026-07-14"
---

# Contributor PR Workflow

Guide a contributor through the end-to-end process of submitting a change to this KB.

## Overview

This skill covers the full lifecycle from first clone to PR submission, with automated validation gates at each step. It prevents common mistakes: wrong directory structure, mismatched frontmatter, dirty files, broken links, and Simplified Chinese content.

## How It Works

### Phase 0: Environment Setup

1. **Clone the repo** (if first time):
   ```bash
   git clone https://github.com/h30190/HJPLUS_Taiwan_Architect_KB.git
   cd HJPLUS_Taiwan_Architect_KB
   ```

2. **Sync with latest main**:
   ```bash
   git checkout main
   git pull origin main
   ```

3. **Create a feature branch**:
   ```bash
   git checkout -b feat/your-feature-description
   ```

4. **Ask the contributor**: "What are you contributing?"
   - New skill → Phase 1
   - Edit existing skill → Phase 2
   - Rename / restructure → Phase 3
   - Other (fix typo, add reference, translate) → Phase 4

### Phase 1: Creating a New Skill

1. **Choose the category**: Look at `raw/` subdirectories to find the right home (建築設計與規劃, 建築法規, 公共工程, etc.).

2. **Copy the template**:
   ```bash
   cp -r 知識樣板/ raw/<category>/<chinese-entry-name>/
   ```

3. **Name the entry directory** (Traditional Chinese, intuitive name like `排煙窗法規檢討/`).

4. **Rename the skill directory** (inside the Chinese entry, from `skill-name-hyphenated/` to lowercase English hyphenated).

5. **Clean up optional subdirectories**: Delete `assets/`, `references/`, `scripts/` if not needed.

6. **Write `SKILL.md`**:
   - Frontmatter: `name` MUST match the skill directory name
   - `metadata.class` is REQUIRED (A/B/C)
   - `metadata.status` is RECOMMENDED (verified/unverified/draft)
   - `license` and `compatibility` are RECOMMENDED
   - Body in English, keep under 500 lines
   - C-class skills MUST include MCP tool examples

7. **Write `domain.md`**:
   - Traditional Chinese body
   - OKF frontmatter with `type: Knowledge Entry` and `title` matching the `# H1` — nothing else
   - 使用情境、學習目標、實務應用

8. **Update parent `index.md`**:
   - Open the parent directory's `index.md`
   - Add a new `* [Skill Name](path/SKILL.md) - description` entry under `## Skills`
   - If no `index.md` exists and the directory has 2+ children, create one per OKF v0.2

### Phase 2: Editing an Existing Skill

1. **Never delete `SKILL.md` or `domain.md` without a replacement**.

2. **Sync SKILL.md and domain.md**: If you change one, update the other.

3. **Preserve frontmatter**: `name` must stay in sync with directory name.

4. **If file is lowercase `skill.md`**, rename to `SKILL.md`:
   ```bash
   git mv <path>/skill.md <path>/SKILL.md
   ```

5. **B-class skills**: Keep `<!-- TODO: Taiwan adaptation needed -->` markers until adaptation is complete.

6. **When adding or removing a skill**, update the parent directory's `index.md` accordingly.

### Phase 3: Renaming / Restructuring

1. **Use `git mv`**, not OS-level rename:
   ```bash
   git mv <old-path> <new-path>
   ```

2. **Scan the entire repo** for stale references:
   ```bash
   # Search for old directory name in all markdown files
   grep -r "<old-name>" raw/ --include="*.md"
   ```
   Every reference must be updated.

3. **Update all `index.md` entries** that point to the old path.

4. **Update frontmatter `name`** if the skill directory name changed.

### Phase 4: Other Changes (Typo, Reference, Translation)

1. Make the change directly on your branch.
2. If touching a skill AND its domain, keep both in sync.
3. No special structure requirements.

### Phase 5: Self-Validation (RUN BEFORE SUBMITTING)

Run ALL checks below. If any fails, fix it before proceeding.

#### Structure Checks

- [ ] `SKILL.md` is uppercase (❌ `skill.md` is wrong)
- [ ] Three-layer structure correct:
      `category/chinese-entry/english-skill-name/SKILL.md`
      `category/chinese-entry/domain.md`
- [ ] `domain.md` frontmatter has `type: Knowledge Entry` + `title` ONLY (no skill fields)
- [ ] No `.history/`, `.vscode/`, `node_modules/`, `__pycache__/` files in the diff
- [ ] Skill directory name is lowercase English hyphenated (❌ pinyin like `pai-yan-chuang`)
- [ ] Skill directory name matches `name` in SKILL.md frontmatter

#### Frontmatter Checks

- [ ] `type: Skill` is present (OKF §11.2 — required on every SKILL.md)
- [ ] `name` is 1-64 chars, lowercase + hyphens only
- [ ] `description` is 1-1024 chars, includes trigger scenario
- [ ] `metadata.class` is present: A / B / C
- [ ] `sources` declared with `id` / `resource` (required for new skills)
- [ ] Top-level `status`, if used, is `draft`/`stable`/`deprecated` — never `verified`/`unverified`
- [ ] No undefined frontmatter fields (❌ `user-invocable`, `language`, `category` without AGENTS.md approval)
- [ ] `python scripts/validate_okf.py` reports 0 errors

#### Content Checks

- [ ] **No Simplified Chinese characters** anywhere in new/modified files

  Common simplified characters to catch:
  `质`(→質) `体`(→體) `设`(→設) `门`(→門) `气`(→氣) `车`(→車)
  `机`(→機) `发`(→發/發展) `层`(→層) `组`(→組) `备`(→備)
  `标`(→標) `规`(→規) `场`(→場) `试`(→試) `复`(→複/復)
  `认`(→認) `适`(→適) `整`(→整) `审`(→審) `图`(→圖)
  `电`(→電) `专`(→專) `阀`(→閥) `预`(→預) `签`(→簽)
  `标`(→標) `记`(→記) `证`(→證) `准`(→準) `验`(→驗)

- [ ] In `REFERENCES.md` or body text: no broken relative paths
- [ ] C-class skills have MCP tool call examples

#### Index & Cross-Reference Checks

- [ ] Parent directory's `index.md` lists this skill (or is created if needed)
- [ ] If the skill belongs to an existing question cluster, it's added to `consultation-workflow/SKILL.md` Section 1 Step 3
- [ ] `## Related Skills` section exists (if overlapping skills exist in `raw/`)

### Phase 6: Submit

1. **Stage and commit**:
   ```bash
   git add -A
   git commit -m "type(scope): brief description"
   ```
   Use Conventional Commits:
   - `feat` = new skill
   - `fix` = bug/correction
   - `docs` = documentation
   - `refactor` = restructure

2. **Push**:
   ```bash
   git push origin feat/your-feature-description
   ```

3. **Create PR via GitHub CLI**:
   ```bash
   gh pr create --title "<title>" --body "<description>"
   ```

4. **Tell the contributor**: "Your PR is submitted! A maintainer will review it. If changes are requested, the review comments will tell you exactly what to fix."

## Troubleshooting

**"I don't have gh (GitHub CLI)"**
→ Push your branch, then open the PR manually at https://github.com/h30190/HJPLUS_Taiwan_Architect_KB/pulls

**"I can't push (permission denied)"**
→ You need to fork the repo first, then push to your fork and create a PR from there.

**"I don't know what class my skill is"**
→ A = International standard (no Taiwan adaptation). B = International → Taiwan (add TODO). C = Taiwan-specific code/regulation.

## Related Skills

* [consultation-workflow](../raw/建築顧問方法論/顧問諮詢工作流程/consultation-workflow/SKILL.md) - For consultants using the KB to answer questions