Superpowers Framework: Phương Pháp Xây Dựng AI Coding Agents Với Composable Skills

TL;DR

Superpowers là open-source framework của Jesse Vincent (GitHub: obra) — một methodology xây dựng AI coding agents bằng composable skills tự động trigger. Thay vì viết prompt chains thủ công, bạn định nghĩa skills — và agent tự biết khi nào cần dùng skill nào. Hỗ trợ Claude Code (Marketplace), Cursor, Codex, OpenCode, và Gemini CLI.

Khi bạn xây một AI coding agent theo kiểu ad-hoc — vài prompt chains, một số system messages — nó thường works với projects nhỏ. Nhưng khi complexity tăng, vấn đề bắt đầu xuất hiện: agent không biết khi nào cần plan vs code, khi nào cần test vs ship. Không có ranh giới rõ ràng.

Superpowers giải quyết điều này bằng cách đặt câu hỏi từ đầu: Nếu agent phải đi theo một workflow phần mềm chuyên nghiệp, workflow đó trông như thế nào?

Superpowers Là Gì?

Từ GitHub repo (tác giả Jesse Vincent):

"Superpowers is a complete software development workflow for your coding agents, built on top of a set of composable 'skills' and some initial instructions that make sure your agent uses them."

Framework gồm hai phần:

1. Skills library — tập hợp các skills dưới dạng SKILL.md files, mỗi skill có tên, mô tả và instructions cụ thể
2. Initial instructions — hướng dẫn agent check skills trước khi bắt đầu bất kỳ task nào

Agent không cần được nhắc "dùng skill X". Nó tự kiểm tra skills library trước mỗi task và tự chọn skill phù hợp.

Superpowers: modular skill blocks kết nối thành một complete agent workflow

Basic Workflow — 7 Bước

Superpowers định nghĩa một workflow 7 bước mà agent bắt buộc phải follow — không phải suggestions mà là mandatory workflows:

1. brainstorming

Kích hoạt trước khi viết bất kỳ dòng code nào. Refine rough ideas qua Socratic questions, explore alternatives, present design theo từng chunks để validate. Lưu design document.

2. using-git-worktrees

Kích hoạt sau khi design được approve. Tạo isolated workspace trên branch mới, run project setup, verify clean test baseline — trước khi bất kỳ code nào được viết.

3. writing-plans

Kích hoạt với approved design. Break work thành bite-sized tasks (2-5 phút mỗi task). Mỗi task có:

• Exact file paths
• Complete code to write
• Verification steps

4. subagent-driven-development

Kích hoạt với plan. Dispatch fresh subagent cho mỗi task với two-stage review:

1. Spec compliance check
2. Code quality check

5. test-driven-development

Kích hoạt trong suốt implementation. Bắt buộc RED-GREEN-REFACTOR: viết failing test → watch it fail → write minimal code → watch it pass → commit. Xóa code được viết trước test (không đùa).

6. requesting-code-review

Kích hoạt giữa các tasks. Review theo plan, report issues theo severity. Critical issues block progress — agent không move forward cho đến khi resolve.

7. finishing-a-development-branch

Kích hoạt khi tất cả tasks complete. Verify tests, present options (merge/PR/keep/discard), cleanup worktree.

Composable Skills Library

Đây là danh sách đầy đủ skills trong Superpowers (từ GitHub README):

Testing:

• test-driven-development — RED-GREEN-REFACTOR cycle (có testing anti-patterns reference)

Debugging:

• systematic-debugging — 4-phase root cause process (root-cause-tracing, defense-in-depth, condition-based-waiting)
• verification-before-completion — Đảm bảo đã thực sự fix xong trước khi đánh dấu done

Collaboration:

• brainstorming — Socratic design refinement
• writing-plans — Detailed implementation plans
• executing-plans — Batch execution với human checkpoints
• dispatching-parallel-agents — Concurrent subagent workflows
• requesting-code-review — Pre-review checklist
• receiving-code-review — Responding to feedback
• using-git-worktrees — Parallel development branches
• finishing-a-development-branch — Merge/PR decision workflow
• subagent-driven-development — Fast iteration với two-stage review

Meta:

• writing-skills — Create new skills theo best practices
• using-superpowers — Introduction to the skills system

Sức Mạnh Của Composability

Tại sao composable skills tốt hơn prompt chains?

Prompt chains:

• Hard-coded thứ tự
• Khó reuse giữa các projects
• Không có skill discovery tự động
• Mỗi "chain" là một blob context lớn

Composable skills:

• Modular — thêm/bỏ skill không ảnh hưởng skill khác
• Reusable — cùng skill library cho mọi project
• Auto-discovery — agent check skills trước khi act
• Testable — mỗi skill có I/O contract rõ ràng

Điểm quan trọng nhất: agent không cần được nhắc nhở. Skills trigger automatically theo context.

Cài Đặt

Superpowers hỗ trợ nhiều platforms:

Claude Code (dễ nhất):

• Cài qua Claude Code Official Marketplace hoặc Plugin Marketplace trực tiếp

Cursor:

• Cài qua Plugin Marketplace

Codex và OpenCode:

• Yêu cầu manual setup (theo hướng dẫn trong README)

Gemini CLI:

• Hỗ trợ theo hướng dẫn riêng trong README

Sau khi cài, verify bằng lệnh:

# Ask agent about available skills
"What superpowers do you have available?"

Superpowers vs gstack

Cả hai đều ra mắt gần cùng thời điểm (tháng 3/2026) và giải quyết vấn đề tương tự — nhưng theo hướng khác:

Khi Nào Dùng Superpowers?

Phù hợp:

• Teams muốn methodology nhất quán cho agent development, không chỉ tooling
• Projects cần TDD nghiêm chỉnh từ đầu
• Developer muốn cùng framework trên nhiều coding agents (Claude, Cursor, Gemini CLI)
• Teams muốn extend framework bằng custom skills

Ít phù hợp:

• Cần browser automation hoặc QA testing tích hợp → xem xét gstack
• Project scope nhỏ không cần structured workflow

Viết Custom Skills

Superpowers có skill writing-skills để bạn tự tạo skills mới:

# Tên skill
---
name: my-custom-skill
description: Mô tả ngắn để agent biết khi nào dùng
---

## When to use this skill
[Trigger conditions]

## Instructions
[Step-by-step instructions]

Skill files tuân theo cùng SKILL.md format — có thể được share với community hoặc giữ private trong repo.

Framework Trend: Từ Generic Agents Đến Structured Methodology

Superpowers và gstack phản ánh một thay đổi lớn hơn: cộng đồng developer đang nhận ra rằng agentic workflow tốt cần có cấu trúc, không phải chỉ cần model tốt.

Khi bạn giao cho agent một task phức tạp mà không có workflow, nó không biết khi nào nên plan, khi nào nên code, khi nào nên test. Kết quả thường lộn xộn.

Superpowers đặt nền móng methodology — tương tự cách Agile hay TDD đặt quy trình cho human developers — nhưng áp dụng trực tiếp vào agent behavior.

FAQ

Superpowers có free không? Có — open source, không có pricing plans. Chỉ cần subscription của platform bạn dùng (Claude Code, Cursor...).

Skills có tự trigger không hay phải gọi thủ công? Skills trigger automatically — agent check skills library trước khi act và chọn skill phù hợp context. Đây là điểm khác biệt chính so với manual slash commands.

Superpowers có hoạt động với Gemini CLI không? Có — README liệt kê Gemini CLI là supported platform với hướng dẫn riêng.

Tôi có thể viết custom skills không? Có — writing-skills là skill dạy bạn cách tạo skills mới theo đúng format và best practices của framework.