Feature/blog writing skill

.claude/skills/tech-blog-coauthoring/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: tech-blog-coauthoring
+description: Guides users through collaborative writing of HyperAccel technical blog posts. Use when writing new blog posts, drafting tech content, or creating posts. Follows a 3-stage workflow (Context → Refinement → Reader Testing), then English translation. Author writes in Korean first.
+---
+
+# Tech Blog Co-Authoring
+
+This skill guides collaborative writing of HyperAccel technical blog posts: **Korean first**, then English translation after completion. Use the `well-writing` skill for review to sustain the feedback loop (write → review → revise).
+
+## When to Offer This Workflow
+
+**Triggers**: "write a blog post", "draft a post", "create a tech blog post"
+
+**When offering**: Explain the 3-stage workflow and ask if the user wants to try it.
+1. **Context Gathering**: Audience, purpose, series info, reference materials
+2. **Refinement & Structure**: Section-wise brainstorming → curation → drafting
+3. **Reader Testing**: Validate the doc with reader-perspective questions
+
+If declined, proceed freeform. If accepted, start with Stage 1.
+
+---
+
+## Stage 1: Context Gathering
+
+**Goal**: Clarify audience, purpose, and structure.
+
+### Initial Questions
+
+1. Post topic / core message?
+2. Target audience? (e.g., ML engineers, compiler practitioners)
+3. What should readers gain after reading?
+4. Is this part of a series? Series name?
+5. Reference materials (papers, Confluence, docs)?
+
+Short answers are fine. Ask for templates or existing posts to reference if applicable.
+
+**Format reference**: Before drafting, identify posts by the **same author** (`authors` in frontmatter) and use them as the primary reference for document format—frontmatter structure, section flow, tone, and styling. If none exist, refer to other posts in `content/posts/`.
+
+### Info Dumping
+
+Encourage dumping background, architecture, related discussions, why alternatives weren't used, and constraints. No need to organize.
+
+### Clarifying Questions
+
+After the dump, ask 5–10 clarifying questions on unclear areas. Accept shorthand replies (e.g., "1: yes, 2: see #channel, 3: no because…").
+
+**Exit**: Proceed to Stage 2 when basics are clear and you can ask about trade-offs and edge cases.
+
+---
+
+## Stage 2: Refinement & Structure
+
+**Goal**: For each section: brainstorm → curate → draft → refine. Apply `.gemini/styleguide.md` while drafting.
+
+### Section Order
+
+If structure is clear, ask which section to start with. Otherwise propose 3–5 sections and confirm with the user.
+
+### Document Scaffold
+
+Create `content/posts/{post-slug}/index.ko.md` with headers and placeholders (`[To be written]`). Match frontmatter and structure to **same-author** existing posts when available.
+
+**Plan review**: Before drafting section content, present the scaffold (section structure and headers) to the author for review. Proceed to per-section drafting only after confirmation.
+
+### Per-Section Process
+
+#### 1. Clarifying Questions
+
+Ask 5–10 questions about what belongs in this section.
+
+#### 2. Brainstorming
+
+Generate 5–20 numbered options for section content.
+
+#### 3. Curation
+
+Ask which to keep / remove / combine. Example: "Keep 1,4,7,9", "Remove 3 (duplicates 1)".
+
+#### 4. Gap Check
+
+Ask if anything important is missing given the selections.
+
+#### 5. Drafting
+
+Replace placeholders with drafted content. **Always** apply `.gemini/styleguide.md`:
+- Space after bold when followed by Korean: `**GPU** 는`
+- First use of acronym: `**FullTerm(Acronym)**`
+- Sentence/paragraph length, heading hierarchy (H2→H3→H4, no skipping), code block language tags
+
+#### 6. Iterative Refinement
+
+Edit with `str_replace` based on feedback. Reflect direct edits in future sections.
+
+**Section done**: After 3 iterations with no substantial changes, ask if anything can be removed, then confirm completion.
+
+### Near Completion
+
+At ~80% done, read the full document and check:
+- Flow and consistency
+- Redundancy or contradictions
+- Unnecessary content
+- Whether each sentence carries weight
+
+---
+
+## Stage 3: Reader Testing
+
+**Goal**: Verify the doc works for readers.
+
+### With Sub-agent
+
+1. Predict 5–10 realistic reader questions
+2. Test with a fresh Claude instance using only the doc and questions
+3. Check for ambiguity, false assumptions, contradictions
+4. Loop back to refine sections if issues exist
+
+### Without Sub-agent
+
+Guide the user:
+1. Open a fresh Claude conversation (https://claude.ai)
+2. Paste the document
+3. Ask the predicted questions
+4. Also ask: "What's ambiguous in this doc?", "What knowledge does it assume?"
+5. Apply fixes based on the results
+
+**Exit**: When questions are answered correctly and no new gaps or ambiguities remain.
+
+---
+
+## Stage 4: English Translation
+
+**When**: After the Korean post (`index.ko.md`) passes Reader Testing.
+
+### Translation Workflow
+
+1. Create `content/posts/{post-slug}/index.en.md`
+2. Translate frontmatter and body from `index.ko.md`
+3. Apply style guide rules for English (bold spacing, acronym format, sentence/paragraph length, code blocks, images, links)
+4. Recommend Reader Testing on the English version too
+
+### Multilingual Structure
+
+- Korean: `content/posts/{post-slug}/index.ko.md`
+- English: `content/posts/{post-slug}/index.en.md`
+- Same slug/folder for both
+
+---
+
+## Feedback Loop: Review and Revise
+
+After writing/translation, use the **well-writing** skill for review.
+
+1. Suggest: "Run the `well-writing` skill to review?"
+2. For issues (Critical / High / Medium), apply fixes using this workflow
+3. Re-run well-writing as needed
+
+Sustain the loop: write (tech-blog-coauthoring) ↔ review (well-writing).
+
+---
+
+## Style Guide Reference
+
+Refer to `.gemini/styleguide.md` when drafting. Summary:
+
+| Priority | Item | Summary |
+|----------|------|---------|
+| Critical | Bold + Korean | `**GPU** 는` (space required) |
+| Critical | Acronyms | First use: `**FullTerm(Acronym)**` |
+| Critical | Capitalization | Acronyms uppercase, common nouns lowercase |
+| High | Readability | ~50 chars/sentence, 5–7 sentences/paragraph |
+| High | Technical terms | Explain on first use |
+| Medium | Headings | H2→H3→H4, no skipping |
+| Medium | Code | Language tag required |
+
+Image rules: see well-writing skill "Stage 4: Images".
+
+---
+
+## Tips
+
+**Tone**: Direct and procedural. Explain rationale only when it affects behavior.
+
+**Deviations**: If the user wants to skip a stage, ask and allow freeform flow.
+
+**Editing**: Use `str_replace`. Avoid reprinting the whole doc.
+
+**Quality**: Prefer meaningful edits over speed.

.claude/skills/well-writing/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: well-writing
+description: This skill should be used when reviewing and editing markdown blog posts for the HyperAccel technical blog. It provides style guide compliance checking and readability improvements.
+---
+
+# Well-Writing
+
+This skill helps review and edit markdown blog posts for the HyperAccel technical blog by ensuring style guide compliance and improving readability.
+
+**Feedback Loop**: Use with `tech-blog-coauthoring`: write → review (well-writing) → revise (tech-blog-coauthoring) → re-review (well-writing).
+
+## When to Offer This Review
+
+**Triggers**: "review this post", "check style", "edit blog post", "validate frontmatter", "improve readability"
+
+**When offering**: Explain that you'll check Critical Issues → Content Quality → Markdown Formatting → Images. Ask which file(s) to review.
+
+---
+
+## Stage 1: Critical Issues
+
+**Goal**: Fix must-fix items before merging.
+
+### Load Style Guide
+
+- Load `.gemini/styleguide.md` (or `references/styleguide.md`) for detailed rules
+- Load `references/checklist.md` for quick reference during review
+
+### Bold Rendering
+
+- Search for pattern: `\*\*[^*]+\*\*[가-힣]` (bold text immediately followed by Korean)
+- Ensure space between closing `**` and Korean text
+- Example: `**GPU** 는` (correct) vs `**GPU**는` (incorrect)
+
+### Acronym Usage
+
+- Verify all acronyms are introduced with full terms first: `**FullTerm(Acronym)**`
+- Check that acronyms in title/summary are introduced in first paragraph
+- Common acronyms: GPU, TPU, SM, CUDA, HBM, SMEM, VMEM, MXU, VPU, TCS, XLA, JAX, Pallas, Triton
+
+### Capitalization
+
+- Ensure consistent capitalization throughout
+- Acronyms uppercase: GPU, TPU, SM
+- Common nouns lowercase: loop, thread, warp, core
+- Brand names correct: NVIDIA, Google, TensorFlow, PyTorch
+
+---
+
+## Stage 2: Content Quality
+
+**Goal**: Check readability and technical writing.
+
+### Readability
+
+- Sentences should be within 50 characters (flexible for technical terms)
+- Paragraphs should be within 10 sentences or about 300 characters
+- Break complex explanations into multiple sentences
+- Use blank lines to separate distinct ideas
+
+### Technical Writing
+
+- Technical terms explained when first introduced
+- Code examples have comments or explanations
+- Images have meaningful alt text
+- Content has logical structure with clear sections
+
+---
+
+## Stage 3: Markdown Formatting
+
+**Goal**: Ensure formatting consistency.
+
+- Headings: Proper hierarchy (H2 → H3 → H4, no skipping)
+- Code blocks: All have language tags (` ```python`, ` ```bash`, etc.)
+- Images: Descriptive alt text, meaningful file names
+- Links: Descriptive link text
+- Lists: Consistent formatting (`-` for unordered)
+- Frontmatter: All required fields present and correct
+
+---
+
+## Stage 4: Images
+
+**Goal**: Ensure images are referenced correctly. **Recommend manual verification** by the author.
+
+- Confluence images: Download manually; save to `images/` with format `{number}-{descriptive-name}.{ext}` (e.g., `01-tpuv1-arch.png`)
+- The agent may briefly remind: check references match files, alt text is descriptive, placement is logical
+- Full verification (orphaned files, missing refs, naming, placement) → **ask the author to verify manually**
+
+---
+
+## Providing Feedback
+
+When reviewing a post:
+
+1. **Prioritize by severity**:
+   - Critical: Must fix (rendering issues, major readability problems)
+   - High: Significantly impacts readability or understanding
+   - Medium: Formatting or consistency issues
+
+2. **Be specific**:
+   - Point to exact locations (line numbers if possible)
+   - Provide before/after examples
+   - Reference specific rules from style guide
+
+3. **Suggest fixes**:
+   - Show correct format
+   - Explain why the fix is needed
+
+---
+
+## Style Guide Reference
+
+Refer to `.gemini/styleguide.md` when reviewing. Summary:
+
+| Priority | Item | Summary |
+|----------|------|---------|
+| Critical | Bold + Korean | `**GPU** 는` (space required) |
+| Critical | Acronyms | First use: `**FullTerm(Acronym)**` |
+| Critical | Capitalization | Acronyms uppercase, common nouns lowercase |
+| High | Readability | ~50 chars/sentence, 5–7 sentences/paragraph |
+| High | Technical terms | Explain on first use |
+| Medium | Headings | H2→H3→H4, no skipping |
+| Medium | Code | Language tag required |
+| Medium | Images | `{number}-{descriptive-name}.{ext}`, descriptive alt text |
+
+---
+
+## Tips
+
+**Context matters**: Some rules may be flexible for technical content (e.g., longer sentences for complex explanations).
+
+**Consistency first**: If a pattern is used consistently throughout a post, it may be acceptable even if not ideal.
+
+**Be constructive**: When pointing out issues, suggest specific fixes and explain the reasoning.
+
+**After review**: If changes are needed, return to `tech-blog-coauthoring` to revise those sections, then run this skill again.