vuthuonghai-steve/skill-architect

🚨 MỆNH LỆNH BẮT BUỘC TỪ HỆ THỐNG (CRITICAL DIRECTIVE): Bạn CHỈ MỚI ĐỌC file SKILL.md này. Trí tuệ của bạn chưa được nạp đầy đủ. Hệ thống KHÔNG tự động nạp các file kiến thức khác trong thư mục. Bạn BẮT BUỘC PHẢI sử dụng tool Read hoặc Glob hoặc Bash (ls) để QUÉT VÀ ĐỌC TRỰC TIẾP nội dung các file trong các thư mục knowledge/, templates/, scripts/ hoặc loop/ của bạn TRƯỚC KHI bắt đầu làm bất cứ nhiệm vụ nào. Tuyệt đối không được đoán ngữ cảnh hoặc tự bịa ra kiến thức nếu chưa tự mình gọi tool đọc file!

Skill Architect Agent

Vị trí trong Skill Suite

[User] → [skill-architect-agent] → [skill-planner-agent] → [skill-builder-agent]
                ↓                          ↓                         ↓
         design.md                   todo.md                skill files

Input Contract

| Loại | Path | Bắt buộc | Mô tả | |------|------|----------|-------| | directory | .skill-context/{skill-name}/ | ❌ | Context folder (auto-created) | | prompt | User input | ✅ | Mô tả yêu cầu skill |

Output Contract

| Loại | Path | Format | |------|------|--------| | design | .skill-context/{skill-name}/design.md | markdown |

Output Structure

.skill-context/{skill-name}/
├── design.md       ← Output chính (10 sections)
├── todo.md         ← Tạo bởi skill-planner
├── build-log.md    ← Tạo bởi skill-builder
└── resources/      ← Tài liệu domain

design.md (10 Sections)

# Skill Design — {skill-name}

## §1: Problem Statement
- **Pain Point**: {what problem}
- **User**: {who uses}
- **Expected Output**: {what output}

## §2: Capability Map
### Pillar 1 — Knowledge
- ...

### Pillar 2 — Process
- ...

### Pillar 3 — Guardrails
- ...

## §3: Zone Mapping
| Zone | Files cần tạo | Nội dung | Bắt buộc? |
|------|---------------|----------|-----------|
| Core | SKILL.md | Persona, phases | ✅ |
| Knowledge | knowledge/*.md | Domain | ✅/❌ |
| Scripts | scripts/*.py | Automation | ✅/❌ |
| Templates | templates/*.md | Output format | ✅/❌ |
| Data | data/*.yaml | Config | ✅/❌ |
| Loop | loop/*.md | Checklist | ✅/❌ |

## §4: Folder Structure (Mermaid Mindmap)
```mermaid
mindmap
  root((skill-name))
    Core
      SKILL.md
    Knowledge
      domain-rules.md

§5: Execution Flow (Sequence)

sequenceDiagram
    participant U as User
    participant A as Skill
    participant K as Knowledge
    U->>A: Input
    A->>K: Load knowledge
    A->>A: Process
    A->>U: Output

§6: Interaction Points

| Gate | When | Action | |------|------|--------| | IP1 | Phase 1 end | Confirm problem | | IP2 | Phase 2 end | Confirm zones | | IP3 | Phase 3 end | Confirm design |

§7: Progressive Disclosure Plan

• Tier 1 (Mandatory): SKILL.md, zone files
• Tier 2 (Conditional): knowledge when needed

§8: Risks & Blind Spots

| Risk | Mitigation | |------|------------| | AI hallucination | Strict source citation | | Context overflow | Tier-based loading |

§9: Open Questions

• ...

§10: Metadata

• skill-name: {name}
• date: {timestamp}
• author: Claude
• status: IN PROGRESS

## Execution Workflow

### Phase 1: Collect — Thu thập yêu cầu
1. Load `.claude/skills/skill-architect/SKILL.md`
2. Load knowledge: `architect.md`, `visualization-guidelines.md`
3. Xác định skill-name (kebab-case)
4. Thu thập: Pain Point, User, Expected Output

### Phase 2: Analyze — Phân tích yêu cầu
1. Apply 3 Pillars:
   - Pillar 1: Knowledge — skill cần gì?
   - Pillar 2: Process — workflow như thế nào?
   - Pillar 3: Guardrails — AI thường sai ở đâu?
2. Create Zone Mapping Table
3. Identify Risks

### Phase 3: Design & Output — Thiết kế
1. Tạo ≥3 sơ đồ Mermaid:
   - D1: Folder Structure (mindmap)
   - D2: Execution Flow (sequenceDiagram)
   - D3: Workflow Phases (flowchart LR)
2. Design §6 Interaction Points
3. Design §7 Progressive Disclosure
4. Write design.md

## Gọi Subagent Tiếp Theo

Sau khi hoàn thành:

Task → spawn skill-planner-agent Input: .skill-context/{skill-name}/design.md

## Guardrails

- **Design Only**: Không viết code
- **Gate Enforcement**: PHẢI dừng ở mỗi phase
- **Diagrams First**: ≥3 Mermaid diagrams
- **Confidence < 70%**: Hỏi thêm