Back to Details

context-bundling

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Context Bundling Skill 📦

上下文打包Skill 📦

Overview

概述

This skill centralizes the knowledge and workflows for creating "Context Bundles." These bundles are essential for compiling large amounts of code and design context into a single, portable Markdown file for sharing with other AI agents or for human review.
该Skill整合了创建「上下文包」的相关知识和工作流。这些包可将大量代码和设计上下文编译为单个可移植的Markdown文件，非常适合分享给其他AI Agent或供人工评审使用。

🎯 Primary Directive

🎯 核心准则

Curate, Consolidate, and Convey. You do not just "list files"; you architect context. You ensure that any bundle you create is:
  1. Complete: Contains all required dependencies, documentation, and source code.
  2. Ordered: Flows logically (Identity/Prompt → Manifest → Design Docs → Source Code).
  3. Annotated: Every file must include a brief note explaining its purpose in the bundle.
筛选、整合、传递。 你不只是简单「罗列文件」，而是在架构上下文。你需要确保创建的所有包都满足以下要求：
  1. 完整： 包含所有必需的依赖项、文档和源代码。
  2. 有序： 逻辑流畅（身份/Prompt → 清单 → 设计文档 → 源代码）。
  3. 带注释： 每个文件都必须附带简短说明，解释其在包中的作用。

Core Workflow: Generating a Bundle

核心工作流：生成上下文包

The context bundler operates through a simple JSON manifest pattern.
上下文打包工具采用简单的JSON清单模式运行。

1. Analyze the Intent

1. 分析需求意图

Before bundling, determine what the user is trying to accomplish:
  • Code Review: Include implementation files and overarching logic.
  • Red Team / Security: Include architecture diagrams and security protocols.
  • Bootstrapping: Include 
    README
    , 
    .env.example
    , and structural scaffolding.
打包前，先明确用户的使用目标：
  • 代码评审： 包含实现文件和整体逻辑说明。
  • 红队/安全测试： 包含架构图和安全协议文档。
  • 项目初始化： 包含
    README
    、
    .env.example
    和结构脚手架文件。

2. Define the Manifest Schema

2. 定义清单结构

You must formulate a JSON manifest containing the exact files to be bundled.
json
{
  "title": "Bundle Title",
  "description": "Short explanation of the bundle's goal.",
  "files": [
    {
      "path": "docs/architecture.md",
      "note": "Primary design document"
    },
    {
      "path": "src/main.py",
      "note": "Core implementation logic"
    }
  ]
}
你必须制定一个JSON清单，列出要打包的所有具体文件：
json
{
  "title": "Bundle Title",
  "description": "Short explanation of the bundle's goal.",
  "files": [
    {
      "path": "docs/architecture.md",
      "note": "Primary design document"
    },
    {
      "path": "src/main.py",
      "note": "Core implementation logic"
    }
  ]
}

3. Generate the Markdown Bundle

3. 生成Markdown上下文包

Use your native tools (e.g., 
cat
, 
view_file
, or custom scripts depending on the host agent environment) to read the contents of each file listed in the manifest and compile them into a target 
output.md
file.
The final bundle format must follow this structure:
markdown
undefined
使用你自带的工具（例如
cat
、
view_file
，或根据宿主Agent环境使用自定义脚本）读取清单中列出的每个文件的内容，将它们编译为目标
output.md
文件。
最终的包格式必须遵循以下结构：
markdown
undefined

[Bundle Title]

[Bundle Title]

Description: [Description]
Description: [Description]

Index

Index

  1. docs/architecture.md
    - Primary design document
  2. src/main.py
    - Core implementation logic
  1. docs/architecture.md
    - Primary design document
  2. src/main.py
    - Core implementation logic

File: 
docs/architecture.md

File: 
docs/architecture.md

Note: Primary design document
```markdown ... file contents ... ```
Note: Primary design document
```markdown ... file contents ... ```

File: 
src/main.py

File: 
src/main.py

Note: Core implementation logic
```python ... file contents ... ```
undefined
Note: Core implementation logic
```python ... file contents ... ```
undefined

Conditional Step Inclusion & Error Handling

可选步骤说明与错误处理

If a file requested in the manifest does not exist or raises a permissions error:
  1. Do not abort the entire bundle.
  2. In the final 
    output.md
    , insert a placeholder explicitly declaring the failure:
    markdown
    ## File: `missing/file.py`
> 🔴 **NOT INCLUDED**: The file was not found or could not be read.
  3. Proceed bundling the remaining valid files.
如果清单中请求的文件不存在或触发权限错误：
  1. 不要 中止整个打包流程。
  2. 在最终的
    output.md
    中插入占位符，明确声明失败情况：
    markdown
    ## File: `missing/file.py`
> 🔴 **NOT INCLUDED**: The file was not found or could not be read.
  3. 继续打包其余有效文件。

Best Practices & Anti-Patterns

最佳实践与反模式

  1. Self-Contained Functionality: The output file must contain 100% of the context required for a secondary agent to operate without needing to run terminal commands.
  2. Specialized Prompts: If bundling for an external review (e.g., a "Red Team" security check), suggest including a specialized prompt file as the very first file in the bundle to guide the receiving LLM.
  1. 功能自包含： 输出文件必须包含100%的所需上下文，确保第三方Agent无需运行终端命令即可正常工作。
  2. 专用Prompt： 如果打包是为了外部评审（例如「红队」安全检查），建议将专用Prompt文件放在包的最开头，用于引导接收内容的LLM。

Common Bundling Mistakes

常见打包错误

  • Bloat: Including 
    node_modules/
    or massive 
    .json
    dumps instead of targeted files.
  • Silent Exclusion: Filtering out an unreadable file without explicitly declaring it missing (violates transparency).
  • 内容冗余： 包含
    node_modules/
    或大型.json导出文件，而非目标文件。
  • 隐式排除： 过滤掉无法读取的文件却不明确声明其缺失（违反透明性要求）。