Hi Zeyu,
Thank you for starting this discussion on the developer mailing list and for preparing and improving PR #907. After reviewing the proposal and its implementation, I generally agree with this direction. Regarding the questions raised in the email, I have the following thoughts: - Separating the SDK-oriented content from the command-line-oriented content into two independent skills makes sense. They address different use cases, and maintaining them separately should make their responsibilities and structure clearer. - The current source-precedence and offline fallback policies fit TsFile's maintenance practices. For behavior tied to a specific version, the source code, tests, and maintained examples from the same version should take precedence. When the version cannot be determined, explicitly reporting the information as unavailable is more reliable than guessing. - I think the templates can remain bundled with the skills, provided that they stay concise, do not hard-code versions, and continue to be validated. They should be treated as convenient starting points rather than authoritative API documentation. When a local TsFile checkout is available, maintained examples from the same version should be preferred. In addition, I suggest continuing to maintain these scripts and the examples they use, so that they can be updated in step with the evolution of the TsFile APIs. The initial implementation has now been merged through PR #907. Further feedback from the community is still very welcome, and subsequent improvements can be made incrementally through follow-up PRs. Best regards, Colin At 2026-08-17 18:58:20, "Alan Chuang" <[email protected]> wrote: >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
