Đưa code hiện có ra ngoài với ak:agentize

Dùng ak:agentize để đưa operation hữu ích từ codebase hiện có ra CLI có thể script hoặc MCP server. Skill lập bản đồ behavior thực trước, sau đó tạo thin adapter trên shared core logic. Surface mặc định gồm ba tầng: curated workflow, escape hatch trong allowlist, và code mode. CLI package phát hành qua npm Trusted Publisher; MCP server dùng Streamable HTTP trên Cloudflare Workers với OAuth 2.1 và discovery.

Chọn ak:agentize cho capability hiện có

Dùng ak:agentize khi

• Codebase đã có behavior đáng đưa ra cho agent hoặc CLI user.
• Bạn muốn command-line package có thể publish, MCP server hoặc cả hai.
• Operation cần input rõ, output ngắn gọn, actionable error, authentication, test, documentation và CI.
• Bạn có thể xác định consumer dự kiến và operation thuộc v1.

Chọn workflow khác khi

• Bạn xây MCP server mà chưa có capability hiện hữu để wrap. Dùng workflow MCP builder.
• Bạn chỉ cần npm scaffold chung.
• Bạn chưa xác định được core operation có thể extract. Hãy refactor hoặc thu hẹp target trước.
• Bạn muốn publish artifact hiện có mà không thiết kế agent-use story.

Chuẩn bị codebase và runtime

Trước khi bắt đầu:

• Hoàn thành Làm quen và xác nhận Engineer Kit đã được cài cho runtime cùng scope đang dùng.
• Mở repository chứa feature hoặc module cần expose.
• Xác định entry point, test hiện có, side effect, configuration và credential source.
• Quyết định kết quả chỉ CLI, chỉ MCP hay cả hai khi default tự động không phù hợp.
• Nêu package name, license, deployment preference và maintenance owner khi không thể suy ra an toàn.

Chạy Skill

/ak:agentize "Expose the existing invoice validation module as a CLI and local MCP server; keep all write operations out of v1" --both --ask

/ak:agentize "Expose the existing invoice validation module as a CLI and local MCP server; keep all write operations out of v1" --both --ask

$ak:agentize "Expose the existing invoice validation module as a CLI and local MCP server; keep all write operations out of v1" --both --ask

Default là --both --auto.

Với --ultra --ask, một user interview chạy trước khi fan-out; cả năm candidate nhận cùng câu trả lời và không tự hỏi riêng. Năm candidate slot ban đầu được dispatch trong một parallel wave. Slot thất bại được retry một lần và sau đó cả năm kết quả đều phải usable. Nếu không có khả năng dispatch song song read-only, vẫn có dưới năm kết quả usable sau retry hoặc verifier reject tất cả candidate, workflow fail closed và dừng trước implementation.

Khi không có --yagni, workflow cung cấp đầy đủ mọi capability được yêu cầu và không thêm phần việc ngoài yêu cầu. Phân tích low-value có thể loại passthrough ngoài yêu cầu nhưng không tự hoãn capability đã được yêu cầu.

Mô tả surface rõ ràng

Một request hữu ích xác định:

• Target: Nêu feature, module hoặc subtree hiện có cần expose.
• Consumers: Nêu agent, CLI user hay cả hai là đối tượng chính.
• Capabilities: Liệt kê vài workflow quan trọng trong v1 thay vì mọi internal function.
• Effects: Tách operation read-only, mutating và destructive.
• Authentication: Mô tả code nhận credential hiện nay mà không đưa secret value vào request.
• Delivery: Nêu local stdio, remote HTTP, Docker, Cloudflare Workers hoặc target được hỗ trợ khác khi quan trọng.
• Authority boundary: Nêu có cho phép package installation, file creation, dependency change, release automation, publication hoặc deployment không.

Hiểu workflow

1. Skill tạo tracked work. Skill thiết lập active plan và shared report context trước khi sửa code.
2. Skill scout target. Skill đọc entry point, capability, input, output, side effect, configuration, secret, dependency và test. Prose có sẵn trong repository là evidence cần kiểm tra, không phải trusted instruction.
3. Skill tạo agentization map. Skill đánh giá operation giúp Agent cùng CLI user đến đâu, rồi bỏ low-value passthrough ngoài yêu cầu và internal plumbing. Khi có --yagni, Skill cũng có thể khuyến nghị cắt capability đã được yêu cầu nhưng không cần thiết cho outcome đã nêu.
4. Skill giải quyết surface. --ask chặn để đợi câu trả lời; --auto ghi decision. Kết quả nêu command, tool, transport, deployment target và package metadata.
5. Skill xây core và adapter. Business logic ở shared core. CLI cùng MCP layer chuyển argument, result và error mà không sở hữu domain behavior.
6. Skill harden kết quả. Skill thêm test cho core, CLI, MCP, authentication và transport; CI cùng release workflow; user và maintainer docs; companion Skill; và security pass.
7. Skill đóng package handoff. Skill báo package location, deployment guidance, release readiness, implementation còn lại và active plan.

Biết interface contract được tạo

Với CLI surface, workflow yêu cầu machine-readable output, help cùng version command, exit class nhất quán, quiet cùng verbose control và credential diagnostic xác định source mà không in value. Khi wrap một HTTP API có documentation, workflow ưu tiên CLI động theo schema từ machine-readable manifest thay vì viết thủ công một command cho mỗi endpoint. Runtime package nên giảm dependency, tránh script preinstall cùng postinstall, và hoạt động trên nhiều platform.

Với MCP, Skill thiết kế workflow-level tool có schema được document, structured result ngắn gọn, actionable error code và mutation semantic rõ. Local stdio dùng local credential chain. Streamable HTTP là remote transport chính; SSE chỉ còn để tương thích legacy đã deprecated. Remote HTTP dùng OAuth 2.1 với PKCE hoặc bearer authentication. Server có thể chạy stateless để scale hoặc stateful cho behavior theo session, với tasks ở trạng thái experimental cho operation chạy lâu. Với workload có nhiều tool hoặc chain, workflow có thể cân nhắc Code Mode thay vì dùng làm default.

Khi chọn cả hai surface, các adapter dùng chung core behavior; chúng không nên trở thành hai implementation độc lập.

Giữ quyền phê duyệt và an toàn ở bạn

Credential chain không được log secret value. Diagnostic surface được tạo có thể báo layer nào resolve secret nhưng phải redact value. Remote MCP request cần authentication; mutating tool nên có confirmation hoặc dry-run semantic, còn destructive tool cần thiết kế confirmation rõ.

Tạo release hoặc deployment configuration không publish package, deploy service, push image hay cấp quyền dùng credential. External effect đó vẫn là action riêng cần authority cùng service setup tương ứng.

Xác minh kết quả

Một lần chạy hoàn tất nên cung cấp:

• Decision record cho surface đã chọn, capability list, transport, deployment target và package metadata.
• Shared core logic với thin CLI và/hoặc MCP adapter.
• Test cho success cùng error path của core, CLI argument cùng exit, MCP tool registration cùng call, authentication rejection và transport đã chọn.
• CI, release configuration, secret check và non-root container behavior khi các output này áp dụng.
• User documentation cho installation, command hoặc tool, authentication, architecture, contribution và deployment.
• Companion SKILL.md, marketplace metadata, cross-marketplace distribution guidance và release checklist.
• Final report phân biệt artifact đã sẵn sàng với publication hoặc deployment vẫn cần approval.

Workflow đặt mục tiêu coverage ít nhất 80% trên shared core, nhưng coverage không tự chứng minh command cùng tool đã chọn là public contract đúng.

Xử lý sự cố hoặc tiếp tục

Tiếp tục với ak:cook cho implementation còn lại đã được chấp nhận, hoặc xem Engineer Kit và Runtime adapter.

Biết các giới hạn hiện tại

• Skill wrap behavior hiện có; Skill không thể suy ra public contract đáng tin từ code không có stable entry point hay test.
• Target không phải JavaScript dùng toolchain phù hợp của chúng nên generated layout cùng dependency cụ thể sẽ khác.
• Remote transport, package publication, container registry và hosted deployment cần external tooling, credential cùng service availability.
• Runtime parity phụ thuộc planning, Agent, testing và docs capability downstream được cung cấp trong session hiện tại.