tdfs4ds.cli¶

tdfs4ds.cli ¶

Command-line interface and programmatic skill management for tdfs4ds.

Entry points registered in setup.py: tdfs4ds-install-skills -> cli.install_skills_cmd

Programmatic API (re-exported from tdfs4ds): - tdfs4ds.list_skills() List bundled skill names. - tdfs4ds.skill_path(name) Path to a bundled SKILL.md. - tdfs4ds.install_skills(dir) Copy SKILL.md files into a target directory. - tdfs4ds.export_skills(dir) Alias of install_skills (clearer intent when used outside Claude Code).

_SKILLS_SRC `module-attribute` ¶

_SKILLS_SRC = parent / 'skills'

_read_frontmatter ¶

_read_frontmatter(md_path: Path) -> Dict[str, str]

Parse the leading --- frontmatter block of a SKILL.md file.

YAML first. The fallback below splits on the first colon and strips surrounding quotes, which accepts frontmatter that no real YAML parser does — and that is precisely how every shipped SKILL.md came to carry name: Feature Store: Deploy to AgentOps: valid here, and a parse error in an editor preview or any agent framework using a YAML library. A file format has one definition, and it is not this function's.

The fallback stays for an environment without PyYAML — a transitive dependency, not a declared one — and for a file that is malformed anyway, where returning what can be read beats returning nothing.

_iter_skill_dirs ¶

_iter_skill_dirs()

Yield each <skill>/ directory under tdfs4ds/skills/ that contains a SKILL.md.

_iter_plugin_skill_dirs ¶

_iter_plugin_skill_dirs()

Yield skill dirs from the TDFS4DS_SKILLS_FOLDER environment variable (if set).

list_skills ¶

list_skills() -> List[str]

Return the sorted list of bundled skill names.

Returns¶

list[str] Skill identifiers (the directory names under tdfs4ds/skills/).

Examples¶

import tdfs4ds tdfs4ds.list_skills() ['fs-agent', 'fs-analyze', 'fs-dataset', ...]

skill_path ¶

skill_path(name: str) -> Path

Return the absolute path to the bundled SKILL.md (or prompt .md) for name.

Searches in two locations:

tdfs4ds/skills/<name>/SKILL.md — top-level skill directory (ca-*, qo-skill-*, etc.)
tdfs4ds/skills/<skill>/prompts/<name>.md — flat prompt file nested inside a skill's prompts/ subfolder (e.g. qo-skill-optimize/prompts/qo-strategies.md).

Parameters¶

name : str Skill or prompt identifier (e.g. 'fs-upload', 'qo-strategies').

Returns¶

pathlib.Path Path to the .md file.

Raises¶

FileNotFoundError If no bundled skill or prompt with that name exists.

_read_skill_body ¶

_read_skill_body(md_path: Path) -> str

Return everything after the YAML frontmatter block of a SKILL.md file.

_read_skill_classifier_examples ¶

_read_skill_classifier_examples(md_path: Path) -> list

Return lines from the '## Classifier Examples' section of a SKILL.md file.

Each returned string is a raw example line (the leading '- ' prefix is stripped) ready to be formatted as f"- {ex}" in the classifier prompt.

_read_skill_enrichment_section ¶

_read_skill_enrichment_section(md_path: Path) -> str

Return the content of the '## Enrichment Knowledge' section of a SKILL.md file, or ''.

get_plugin_enrichment_knowledge ¶

get_plugin_enrichment_knowledge(intent: str, base_text: str = '') -> list

Return Enrichment Knowledge blocks from plugin skills matching intent and base_text.

Scans $TDFS4DS_SKILLS_FOLDER for SKILL.md files whose enrichment-for field matches intent. When enrichment-match is also set, at least one of its comma-separated tokens must appear (case-insensitive) in base_text for the block to be included. Returns a list of ## Enrichment Knowledge body strings (one per matching skill).

Called by node_skill_definition after the base grounded explanation is produced, to optionally extend the answer with approved domain knowledge.

Parameters¶

intent : str Skill intent to match against (e.g. 'DEFINITION'). base_text : str The grounded base explanation already produced by the skill. Used for keyword matching when enrichment-match is set.

Returns¶

list[str] Approved knowledge blocks to append (may be empty).

skill_prompt ¶

skill_prompt(name: str) -> str

Return the prompt template body (after frontmatter) for skill name.

The returned string may contain {variable} placeholders intended for use with meth:str.format (pure-Python prompts) or passed directly to ChatPromptTemplate.from_template (LangChain prompts).

Parameters¶

name : str Skill identifier, e.g. 'qo-candidates'.

Returns¶

str Prompt body with frontmatter stripped.

install_skills ¶

install_skills(target_dir: Optional[Union[str, Path]] = None, *, overwrite: bool = True, skills: Optional[List[str]] = None, verbose: bool = True) -> List[Path]

Copy bundled SKILL.md files to target_dir.

Parameters¶

target_dir : str or Path, optional Destination root. Defaults to ~/.claude/skills/ (Claude Code user-level skills directory). overwrite : bool, default True Replace existing SKILL.md files. Set to False to skip skills that already exist at the destination. skills : list[str], optional Subset of skill names to install. Defaults to all bundled skills. verbose : bool, default True Print one line per installed skill plus a final summary.

Returns¶

list[pathlib.Path] Destination paths of every SKILL.md that was written (skipped files are not included).

Notes¶

The destination directory layout mirrors the package source — one directory per skill, each containing a SKILL.md::

target_dir/
  fs-setup/SKILL.md
  fs-upload/SKILL.md
  ...

export_skills ¶

export_skills(target_dir: Union[str, Path], *, overwrite: bool = False, skills: Optional[List[str]] = None, verbose: bool = True) -> List[Path]

Export bundled SKILL.md files to target_dir, skipping any that already exist there.

Same behaviour as :func:install_skills but with a mandatory destination and overwrite=False by default — use this when copying skills into a target directory and you only want to add missing ones.

Parameters¶

target_dir : str or Path Destination root. overwrite : bool, default False When False (default), skills already present at the destination are left untouched. Pass True to replace them unconditionally. skills, verbose See :func:install_skills.

Returns¶

list[pathlib.Path] Destination paths of every SKILL.md that was written (skipped files are not included).

Examples¶

import tdfs4ds tdfs4ds.export_skills('./my_agent/skills') # skip existing tdfs4ds.export_skills('./my_agent/skills', overwrite=True) # replace all tdfs4ds.export_skills('/srv/skills', skills=['fs-setup', 'fs-upload'])

install_skills_global ¶

install_skills_global(*, overwrite: bool = True, skills: Optional[List[str]] = None, verbose: bool = True) -> List[Path]

Install bundled SKILL.md files to the global Claude Code skills directory.

Convenience wrapper around :func:install_skills that targets ~/.claude/skills/ — the default Claude Code user-level skills location shared across all local projects.

Use this when you want to make tdfs4ds skills available to Claude Code globally (in your home directory), so they appear in the IDE extensions, CLI, and web app without repeating the installation per project.

Parameters¶

overwrite : bool, default True Replace existing SKILL.md files. Set to False to skip skills that have already been installed. skills : list[str], optional Subset of skill names to install. Defaults to all bundled skills. Example: skills=['fs-upload', 'fs-dataset']. verbose : bool, default True Print progress — one line per installed skill and a final summary.

Returns¶

list[pathlib.Path] Destination paths of every SKILL.md file that was written. Skipped files (when overwrite=False and already present) are not included in the return value.

Notes¶

This is equivalent to calling:

.. code-block:: python

install_skills(
    target_dir=Path.home() / ".claude" / "skills",
    overwrite=overwrite,
    skills=skills,
    verbose=verbose,
)

Examples¶

Install all bundled skills globally (one-time setup):

import tdfs4ds tdfs4ds.install_skills_global() installed fs-agent -> /Users/you/.claude/skills/fs-agent/SKILL.md installed fs-analyze -> /Users/you/.claude/skills/fs-analyze/SKILL.md ... 19 skill(s) installed to /Users/you/.claude/skills

Install only a few specific skills:

tdfs4ds.install_skills_global( ... skills=['fs-upload', 'fs-dataset', 'ca-search'], ... verbose=True ... )

Reinstall a skill (replace if already present):

tdfs4ds.install_skills_global( ... skills=['fs-upload'], ... overwrite=True ... )

install_skills_local ¶

install_skills_local(*, overwrite: bool = True, skills: Optional[List[str]] = None, verbose: bool = True) -> List[Path]

Install bundled SKILL.md files to the local project's Claude Code directory.

Convenience wrapper around :func:install_skills that targets ./.claude/skills/ — the project-level skills directory for Claude Code in the current working directory.

Use this when you want to version-control tdfs4ds skills alongside your project code (e.g. in a monorepo or framework where custom agents may modify or extend the skill set). Skills installed locally override the global installation for this project.

Parameters¶

overwrite : bool, default True Replace existing SKILL.md files. Set to False to skip skills that have already been installed locally. skills : list[str], optional Subset of skill names to install. Defaults to all bundled skills. Example: skills=['fs-upload', 'ca-explain']. verbose : bool, default True Print progress — one line per installed skill and a final summary.

Returns¶

list[pathlib.Path] Destination paths of every SKILL.md file that was written. Skipped files (when overwrite=False and already present) are not included in the return value.

Notes¶

This is equivalent to calling:

.. code-block:: python

install_skills(
    target_dir=Path.cwd() / ".claude" / "skills",
    overwrite=overwrite,
    skills=skills,
    verbose=verbose,
)

The local skills directory is created automatically if it does not exist.

Examples¶

Install all bundled skills locally (one-time setup in a project):

import tdfs4ds import os os.chdir('/path/to/my/project') tdfs4ds.install_skills_local() installed fs-agent -> /path/to/my/project/.claude/skills/fs-agent/SKILL.md installed fs-analyze -> /path/to/my/project/.claude/skills/fs-analyze/SKILL.md ... 19 skill(s) installed to /path/to/my/project/.claude/skills

Install only consumer-agent reference skills locally:

tdfs4ds.install_skills_local( ... skills=[ ... 'ca-search', 'ca-definition', 'ca-explain', 'ca-lineage', ... 'ca-summary', 'ca-usage', 'ca-freshness', 'ca-dataset' ... ] ... )

Add new skills to an existing local installation:

tdfs4ds.install_skills_local( ... skills=['fs-new-workflow'], ... overwrite=False # skip if already installed ... )

skill_catalog ¶

skill_catalog() -> Dict[str, Dict[str, str]]

Return a mapping of every bundled skill to its frontmatter metadata.

Each value contains description (one-line summary used by agent dispatchers) and path (absolute SKILL.md path). Frontmatter is parsed without a YAML dependency — only top-level key: value lines inside a leading --- block are extracted.

Returns¶

dict[str, dict[str, str]]

Examples¶

import tdfs4ds tdfs4ds.skill_catalog()['fs-upload']['description'][:60] 'Generate Python code to engineer features ...'

consumer_agent_skill_catalog ¶

consumer_agent_skill_catalog() -> Dict[str, Dict[str, str]]

Return metadata for all consumer-agent skills, keyed by skill name.

Consumer-agent skills are identified by the ca- name prefix convention. They are installed to ~/.claude/skills/ alongside other skills and are also used by the LangGraph consumer agent to build its intent classifier and skill registry dynamically.

Returns¶

dict[str, dict[str, str]] Skill name → frontmatter metadata (includes intent, description, and path).

Examples¶

import tdfs4ds tdfs4ds.consumer_agent_skill_catalog().keys() dict_keys(['ca-dataset', 'ca-definition', 'ca-explain', ...])

query_optimizer_skill_catalog ¶

query_optimizer_skill_catalog() -> Dict[str, Dict[str, str]]

Return metadata for all query-optimizer skills, keyed by skill name.

Query-optimizer skills are identified by the qo-skill- name prefix and must have an intent field in their frontmatter. They are used by the LangGraph query optimizer agent to build its intent classifier and skill registry dynamically.

Returns¶

dict[str, dict[str, str]] Skill name → frontmatter metadata (includes intent, description, and path).

Examples¶

import tdfs4ds tdfs4ds.query_optimizer_skill_catalog().keys() dict_keys(['qo-skill-explain', 'qo-skill-optimize', 'qo-skill-simplify'])

install_skills_cmd ¶

install_skills_cmd()

Entry point: tdfs4ds-install-skills.

tdfs4ds.cli¶

tdfs4ds.cli ¶

_SKILLS_SRC module-attribute ¶

_read_frontmatter ¶

_iter_skill_dirs ¶

_iter_plugin_skill_dirs ¶

list_skills ¶

Returns¶

Examples¶

skill_path ¶

Parameters¶

Returns¶

Raises¶

_read_skill_body ¶

_read_skill_classifier_examples ¶

_read_skill_enrichment_section ¶

get_plugin_enrichment_knowledge ¶

Parameters¶

Returns¶

skill_prompt ¶

Parameters¶

Returns¶

install_skills ¶

Parameters¶

Returns¶

Notes¶

export_skills ¶

Parameters¶

Returns¶

Examples¶

install_skills_global ¶

Parameters¶

Returns¶

Notes¶

Examples¶

See Also¶

install_skills_local ¶

Parameters¶

Returns¶

Notes¶

Examples¶

See Also¶

skill_catalog ¶

Returns¶

Examples¶

consumer_agent_skill_catalog ¶

Returns¶

Examples¶

query_optimizer_skill_catalog ¶

Returns¶

Examples¶

install_skills_cmd ¶

_SKILLS_SRC `module-attribute` ¶