Hello everyone, I would like to discuss a set of TsFile skills that we have been developing for AI coding agents. The goal is to provide agents with a compact, version-aware, and maintainable source of TsFile development guidance without duplicating the full official documentation.
The skills are located under tsfile/skills (the PR https://github.com/apache/tsfile/pull/907 would be open soon on github) and are divided into two focused parts: 1. tsfile This skill covers programmatic TsFile development, including: - Java, Python, C++, and C APIs - Tree and Table model selection - Schema and data-type design - Reading and writing workflows - Encoding, compression, and performance considerations - Cross-language and cross-version compatibility 2. tsfile-cli This skill covers command-line operations, including: - File metadata and schema inspection - Row preview, export, counting, and sampling - CSV/TSV conversion to table-model TsFiles - Command selection and output-format guidance The main SKILL.md has intentionally been kept concise. Large quick-start sections, general concepts, and performance explanations have been moved into focused offline references. An agent loads only the reference relevant to the current task instead of placing the entire TsFile guide into its context. The offline references are not intended to mirror the official website. Stable workflows and compatibility guardrails are retained locally, while detailed tutorials, release inventories, and API catalogs remain authoritative on the TsFile website and in the source repository. A source policy and documentation map define the authority order: - For checkout-specific API behavior, use source code, tests, and maintained examples from the same commit. - For a named release, use its tag, release notes, published artifacts, and matching documentation. - For current published information, consult official TsFile and Apache sources. - Treat the website’s latest path as a mutable documentation alias rather than a release number. - When offline, use the locally archived scope and report its validation date without claiming that mutable online content is current. We also added a version-resolution script. It reads Maven, Java, C++, Python, and Git metadata directly from a TsFile checkout, so the skill does not contain a hard-coded TsFile version. The script supports two modes: - checkout: resolve versions and source identity from the local TsFile repository. - standalone: when the skill is downloaded without TsFile source code, return a successful degraded result with version fields marked as unavailable. An explicitly invalid source path remains an error. This distinction prevents an agent from guessing a version while still allowing the skill to work independently. The bundled assets were reviewed separately from upstream examples. The existing assets are standalone user-output templates rather than direct copies of repository examples, so they were retained. Their behavior is now: - When TsFile source is available, agents should prefer maintained examples from the same commit. - When only the skill is available and the user requests a starter project, agents may copy the appropriate template. - The Java template no longer contains a default TsFile dependency version; the target version must be provided explicitly. - A validation script checks the templates in both source-checkout and standalone modes. In checkout mode, the current validation compiles the Java and C++ templates against the local source and runs the Python write/read template against the local binding. In standalone mode, dependency-free checks run by default, while explicit Java artifacts, C++ headers, or Python environments can be supplied for full API validation. We would appreciate feedback on the following points: - Whether the split between SDK-oriented and CLI-oriented skills is appropriate - Whether the source-authority and offline fallback policy matches TsFile’s maintenance practices - Whether user-output templates should remain bundled with the skills - Which parts, if any, would be useful to maintain closer to the upstream TsFile repository Thank you for your time. I would be happy to provide the current directory structure, scripts, or a patch for further review. Best regards, Zeyu Zhang
