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

Reply via email to