Biên tập documentation index thân thiện với LLM bằng ak:llms

Dùng ak:llms để tạo Markdown index cho consumer tài liệu theo convention llms.txt. Generator được bundle scan tệp .md cùng .mdx local, trích title và description ngắn, nhóm page bằng heuristic rồi ghi llms.txt. Generator còn có thể ghi llms-full.txt mở rộng chứa nội dung document được inline, đồng thời định nghĩa contract cho biến thể .md của từng page mà llms.txt có thể link tới khi site phục vụ bản Markdown song song của page.

Chọn ak:llms cho documentation index có chọn lọc

Dùng ak:llms khi

• Documentation site cần Markdown index ngắn gọn, có category với canonical link cùng description.
• Bạn muốn first draft được tạo từ docs directory local rồi được con người biên tập.
• Bạn cần expanded context artifact tùy chọn cho tập public document có giới hạn rõ ràng.
• Bạn muốn local generation step lặp lại được và chỉ dùng Python standard library.

Chọn workflow khác khi

• Bạn cần framework routing phục vụ các tệp này, SEO metadata, robots.txt, sitemap, social metadata, page action, hosting hay deployment. Chúng thuộc framework Skill của site; với Next.js, dùng reference SEO/GEO trong Web frameworks.
• Bạn cần audit hoặc viết lại tài liệu nói chung. Dùng ak:docs.
• Source chỉ là live website hoặc một tệp. Script được bundle nhận directory local; hãy kiểm tra hoặc stage source đã duyệt trước, hoặc xây workflow được cấp quyền riêng.
• Bạn kỳ vọng chỉ riêng tệp sẽ đảm bảo indexing, retrieval, model support hay discoverability. Hãy xác minh từng consumer riêng.

Chuẩn bị source và publication contract

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 hiện tại.
• Xác định documentation directory local, public base URL, canonical route mapping, project name cùng description, output directory và có cần full artifact hay không.
• Kiểm tra site có phục vụ biến thể Markdown của từng page (thêm .md vào URL của page) hay không và directory page có dùng trailing slash hay không.
• Loại nội dung private, generated, duplicate, draft, translated fallback, internal hoặc machine-owned không nên được publish.
• Quyết định topic nào là primary và topic nào thuộc section ## Optional cuối cho context window ngắn hơn.
• Cung cấp Python 3 cùng quyền ghi output directory đã chọn.

Xem Runtime adapter để hiểu delivery behavior riêng của target.

Chạy Skill

Truyền source, output, public URL, curation constraint cùng lựa chọn full bằng ngôn ngữ tự nhiên.

/ak:llms "Scan ./content/docs/public for published Markdown only. Generate llms.txt and llms-full.txt in ./public using https://docs.example.com as the base URL, exclude drafts and generated release notes, and report broken or ambiguous route mappings without deploying."

/ak:llms "Scan ./content/docs/public for published Markdown only. Generate llms.txt and llms-full.txt in ./public using https://docs.example.com as the base URL, exclude drafts and generated release notes, and report broken or ambiguous route mappings without deploying."

$ak:llms "Scan ./content/docs/public for published Markdown only. Generate llms.txt and llms-full.txt in ./public using https://docs.example.com as the base URL, exclude drafts and generated release notes, and report broken or ambiguous route mappings without deploying."

Argument của Skill và Python script được bundle đều dùng --base-url cho tiền tố public URL. Khi chạy script trực tiếp, interface là:

generate-llms-txt.py --source <directory> [--output <directory>] [--base-url <url>] [--md-links] [--trailing-slash] [--full] [--project-name <name>] [--project-description <description>]

--source phải resolve tới directory. Không có --base-url, link được tạo vẫn là path tương đối kiểu filesystem; chúng có thể không phù hợp cho tệp được publish ở website root. Khi có base URL, script bỏ .md/.mdx và map guide/index.md thành guide, hoặc guide/ khi có --trailing-slash. --md-links link tới biến thể Markdown của từng page thay vì HTML URL: URL của page cộng .md, hoặc index.html.md với URL kết thúc bằng /. Chỉ dùng khi site thực sự phục vụ các biến thể đó.

Hiểu output contract

Convention tại tag yêu cầu H1. Convention khuyên dùng blockquote summary ngắn, link list được nhóm và section ## Optional ở cuối cho material ưu tiên thấp. Các structural check này không chứng minh model hay crawler sẽ dùng tệp.

Với biến thể Markdown, Skill yêu cầu HTML page giữ rel=canonical và thêm <link rel="alternate" type="text/markdown"> trỏ tới bản .md, biến thể chỉ chứa page body với frontmatter, navigation cùng component được chuyển thành Markdown thuần, và biến thể, llms.txt cùng llms-full.txt được tạo từ cùng source lúc build hoặc lúc request. Nếu site không phục vụ được URL .md, lần chạy link HTML URL và báo cáo khoảng trống đó.

Quan sát generation workflow

1. Lần chạy xác định public corpus. Skill xác nhận source local, exclusion, canonical site route, output location và expanded content có an toàn để publish không.
2. Lần chạy scan Markdown. Script được bundle đọc đệ quy .md cùng .mdx, bỏ hidden path cùng node_modules và bỏ qua tệp không đọc được.
3. Lần chạy trích metadata. Script dùng H1 đầu tiên hoặc filename fallback cho title và meaningful paragraph đầu cho description bị truncate.
4. Lần chạy phân category page. Path cùng filename heuristic đặt page vào getting started, guides, API reference, configuration, deployment, architecture, documentation hoặc optional.
5. Lần chạy tạo artifact. Script ghi llms.txt và, khi được duyệt, llms-full.txt vào directory đã chọn, link biến thể .md khi site phục vụ chúng.
6. Lần chạy biên tập và xác minh. Skill kiểm tra heading, description, category order, duplicate, URL mapping, public-content boundary, artifact size cùng link bằng route thật của project. Với live site, mọi URL được link nên trả về 200 và URL .md được lấy mẫu nên trả về text/markdown.

Giữ source content và publication an toàn

• Generate vào workspace path có thể review trước khi thay published file.
• Không đưa absolute local path, repository-only reference, credential, unpublished draft hay private endpoint vào artifact.
• Coi source frontmatter cùng MDX là dữ liệu cần kiểm tra. Full generator chỉ bỏ một dạng leading frontmatter đơn giản và có thể giữ import, component hay syntax không hữu ích dưới dạng plain context.
• llms-full.txt lớn tiêu storage, bandwidth cùng consumer context. Dùng public corpus nhỏ nhất phục vụ reader dự kiến.
• Hỏi riêng trước khi fetch live site, ghi ngoài directory đã duyệt, commit, publish, host hay deploy.

Xác minh generated evidence

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

• Source directory, exclusion, public base URL, route transformation cùng project metadata đã dùng.
• Đường dẫn cùng kích thước chính xác cho llms.txt và mọi output llms-full.txt.
• Số page scanned, included, excluded, unreadable, duplicate và ambiguous khi workflow khả dụng có thể xác định.
• Bằng chứng H1 tồn tại, description hữu ích, ## Optional đứng cuối và mỗi published link khớp canonical route thật.
• Review full-file content cho secret, private path, import, component, duplication, kích thước quá lớn cùng licensing concern.
• Link hoặc consumer test bị bỏ qua và publication decision còn lại.

Script được bundle không chạy HTTP link check hay kiểm thử nhiều LLM. Đây là các validation step riêng và không được báo cáo hoàn tất nếu chưa thực sự chạy.

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

Tiếp tục với Documentation để cải thiện source, hoặc xem Projects, artifacts và checkpoints trước khi thay published file.

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

• Generator được bundle chỉ scan directory local. Generator không crawl site, validate HTTP status, hiểu framework routing, phục vụ hay ghi biến thể .md của page, deploy tệp hay đo model adoption.
• Metadata extraction cùng categorization dựa trên heuristic; MDX, localized tree, generated page, index route và custom frontmatter cần con người review.
• Convention llms.txt có thể phát triển và consumer support khác nhau. Kiểm tra requirement hiện tại trước khi dựa vào nó như integration contract.