Agent skills¶

tdfs4ds ships with 22 discoverable SKILL.md files organized in four families that teach agents — Claude Code, custom LangGraph agents, or any LLM with file access — how to drive the feature store end-to-end.

What is a skill?¶

A skill is a Markdown file with YAML frontmatter declaring:

name — human-readable skill name (e.g., "Feature Store: Upload").
description — when an agent should pick this skill.
argument-hint — the inputs the skill expects (e.g., [source-table] [entity-column]).
allowed-tools — restricted tool list (Read, Edit, Write, Bash, Glob, Grep).

The body is a copy-paste-ready code pattern with <PLACEHOLDER> markers and a ## Rules block listing invariants. For query optimizer skills (qo-skill-*), additional nested prompt files live under prompts/ subfolders.

Bundle list¶

Feature Store Operations (`fs-*` — 10 skills)¶

Core feature store lifecycle from setup through analysis. All fs-* skills reference each other in their "Related skills" tables to help agents chain operations.

fs-setup

Connect to Teradata, run setup(), activate a data domain. First call of every session.

fs-upload

Engineer features in SQL or teradataml, persist as a view, register with upload_features.

fs-filter

Segmented ingestion with FilterManager — standard, under a TimeManager, hybrid, clone. The segments split the entity.

fs-rollout

run() at the business date, roll_out() to build a history, force_compute=True to rebuild it.

fs-dataset

Build a dataset view and choose its time: current, as_of, following a TimeManager, or the whole history.

fs-migrate

Promote lab work to production: plan, approve, migrate, rebuild the history.

fs-federation

Read other stores read-only: federated catalogs and datasets on their features.

fs-inspect

Browse process / feature / dataset catalogs and the follow-up table.

fs-document

LLM process documentation + EXPLAIN score 1–5.

fs-lineage

Build a dependency graph and render a Sankey diagram.

fs-analyze

Full scalability analysis — lineage + EXPLAIN + partition opportunities + FilterManager proposal.

fs-agent

Launch the consumer agent chatbot (LangGraph + Chroma + Gradio).

Query Optimization (`qo-skill-*` — 3 skills)¶

LLM-powered query rewriting pipeline. Each qo-skill-* contains multiple nested prompt files under prompts/ that implement specific optimization steps (e.g., EXPLAIN analysis, strategy generation, candidate refinement).

Skill	Purpose	Nested Prompts
qo-skill-explain	Analyze EXPLAIN plans and score query quality (1–5)	`qo-explain`, `qo-classify-items`, `qo-document-sql`
qo-skill-simplify	Flatten nesting and remove redundant wrappers	`qo-simplify`, `qo-syntax-fix`
qo-skill-optimize	Full optimization pipeline with strategy-based rewrites	`qo-strategies`, `qo-generate`, `qo-refine`, `qo-candidates`, `qo-compare`, `qo-summary`

Note: Nested prompts are discovered automatically via skill_prompt("qo-strategies") without needing to know which qo-skill-* they belong to. install_skills() copies the entire prompts/ folder structure.

Teradata Utilities (`td-*` — 1 skill)¶

td-explain

Interactive HTML flow diagram from any raw Teradata EXPLAIN plan.

Installing the bundle¶

import tdfs4ds

# Default — copy every SKILL.md to ~/.claude/skills/ (user-level, all projects)
tdfs4ds.install_skills()

# Or pick any target directory (works for non-Claude agents too)
tdfs4ds.export_skills('/path/to/agent/skills')

# Install a subset
tdfs4ds.install_skills(skills=['fs-setup', 'fs-upload'])

# Skip skills that already exist (export_skills default behaviour)
tdfs4ds.export_skills('.claude/skills')     # overwrite=False by default

# Discover what is bundled
tdfs4ds.list_skills()                       # ['fs-agent', 'fs-analyze', ...]
tdfs4ds.skill_catalog()                     # full frontmatter per skill
tdfs4ds.skill_path('fs-upload')             # absolute path to the SKILL.md

Or from the command line with the venv active:

tdfs4ds-install-skills                                # user-level ~/.claude/skills/
tdfs4ds-install-skills --target .claude/skills        # project-level
tdfs4ds-install-skills --skill fs-setup --skill fs-upload  # subset
tdfs4ds-install-skills --no-overwrite                 # skip existing
tdfs4ds-install-skills --list                         # list bundled names

`install_skills` vs `export_skills`¶

Function	Default `overwrite`	Typical use
`tdfs4ds.install_skills()`	`True`	Upgrade skills when you update the package
`tdfs4ds.export_skills(dir)`	`False`	Add only missing skills without touching existing customisations

Option A — Check `.claude/skills/` into git (recommended for teams)¶

The cleanest team setup is to commit .claude/skills/ to the shared repository. Teammates get every skill automatically on git pull — no install step needed.

Option B — Install from the package (colleague has `tdfs4ds` in their venv)¶

If each person installs tdfs4ds independently, they run one command after activating their virtual environment:

import tdfs4ds

# Add skills to the user-level directory (picked up in every project)
tdfs4ds.install_skills()                        # default: ~/.claude/skills/

# Or into the current project only, skipping skills already present
tdfs4ds.export_skills('.claude/skills')         # overwrite=False by default

Or from the terminal with the venv active:

# User-level (applies to all projects on this machine)
tdfs4ds-install-skills

# Project-level, skip existing
tdfs4ds-install-skills --target .claude/skills --no-overwrite

Where skills land¶

Target	Scope	When to use
`~/.claude/skills/` (default)	All projects for this user	Personal workstation setup
`.claude/skills/` in the project repo	This project only	Shared via git — no extra install step for teammates

Typical workflow chains¶

The skills are designed to chain. Each SKILL.md includes a "Related skills" table at the top so the dispatching agent knows where to go next.

First feature¶

fs-setup  →  fs-upload  →  fs-document

Slow process¶

fs-document  →  fs-analyze  →  fs-filter  →  fs-rollout

Lab to production¶

fs-upload  →  fs-rollout  →  fs-migrate  →  fs-rollout (in production)  →  fs-federation (from the lab)

Conversational consumer¶

fs-document  →  fs-agent

Bulk migration audit¶

fs-inspect  →  fs-lineage  →  graph_to_migration_manifest

Authoring a new skill¶

Create tdfs4ds/skills/<skill-id>/SKILL.md (e.g., tdfs4ds/skills/fs-upload/SKILL.md).
Add YAML frontmatter with:
name — human-readable display name (e.g., "Feature Store: Upload")
description — when an agent should pick this skill
argument-hint — input hints (e.g., [source-table] [entity-column])
allowed-tools — restricted tool list (Read, Edit, Write, Bash, Glob, Grep)
Begin the body with a ## Related skills table linking neighbours.
If your skill uses LLM prompts, store them as separate files under prompts/:
Create tdfs4ds/skills/<skill-id>/prompts/<prompt-name>.md
Reference them in the body with [prompt-name](prompts/prompt-name.md)
skill_prompt("prompt-name") auto-discovers nested prompts
Emit a single fenced Python block containing the pattern an agent should produce. Mark every user-supplied value as <PLACEHOLDER>.
Close with a ## Rules block listing the invariants (e.g., never construct selected_features manually).
Reinstall: pip install -e . — setup.py already globs skills/*/SKILL.md and skills/*/prompts/*.md.

tdfs4ds.list_skills() will pick up the new skill automatically. Nested prompts are accessible via tdfs4ds.skill_prompt("prompt-name") without naming which skill owns them.