Draft
Conversation
There was a problem hiding this comment.
Pull request overview
This PR refactors the Pixeltable skill documentation from a mostly API-reference layout into a more agent-actionable structure centered on a mental model, usage modes, and common anti-pattern detection.
Changes:
- Reorganized SKILL.md into “Mental Model”, “How to Use This Skill”, and “Pixeltable Patterns”.
- Added wrong/right examples, an anti-pattern scan table, and debugging guidance to steer agents toward Pixeltable-native patterns.
- Expanded pattern coverage (schema evolution, views/iterators, computed columns workflow, embedding search, JSON path usage, export options, versioning concepts).
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
| if_exists='ignore' | ||
| ) | ||
| # Find rows with errors | ||
| t.where(t.analysis.errortype != None).select(t.analysis.errortype, t.analysis.errormsg).collect() |
Comment on lines
+321
to
+325
| t.update({'score': 1.0}, where=t.category == 'important') | ||
| t.delete(where=t.is_active == False) | ||
| pxt.move('dir1.my_table', 'dir2.my_table') # move between directories | ||
| pxt.drop_table('dir.my_table') # drop by catalog path | ||
| pxt.drop_table(t) # drop by handle |
| **Views** are derived from a table in three ways: | ||
| - With an **iterator** — splits rows into sub-rows (document chunks, video frames, audio segments) | ||
| - As a **filtered subset** — `pxt.create_view('dir.active', t.where(t.is_active == True))` | ||
| - As a **sample** — `pxt.create_view('dir.sample', t.sample(n=100, seed=42))` |
| ) | ||
| ```python | ||
| # --- Directories --- | ||
| pxt.create_dir('my_dir/sub_dir') |
Comment on lines
+366
to
+368
| @pxt.udf | ||
| def make_thumbnail(img: PIL.Image.Image) -> PIL.Image.Image: | ||
| return img.resize((320, 320)) |
| ``` | ||
| | Anti-pattern | What to look for | Fix | | ||
| |---|---|---| | ||
| | SDK call outside computed column | `openai.OpenAI()`, `anthropic.Anthropic()`, `requests.get(...)` in app/endpoint code | Move to `add_computed_column` using `pxtf.<provider>.*` | |
Comment on lines
+255
to
+259
| t = pxt.create_table('my_project.items', { | ||
| 'content': pxt.String, | ||
| 'uuid': pxtf.uuid.uuid7(), | ||
| 'created_at': pxt.Timestamp, | ||
| }, primary_key=['uuid']) |
| t.add_computed_column(cleaned=clean_text(t.content)) | ||
| # From CSV/Parquet — auto-infer schema, override media columns | ||
| t = pxt.create_table('my_project.data', source='data.csv', | ||
| schema_overrides={'image_path': pxt.Image, 'audio_path': pxt.Audio}) |
Comment on lines
+274
to
+278
| chunks = pxt.create_view('project.chunks', docs, | ||
| iterator=pxtf.document.document_splitter(docs.doc, separators='sentence', limit=300)) | ||
|
|
||
| results = search_documents('machine learning').collect() | ||
| frames = pxt.create_view('project.frames', videos, | ||
| iterator=pxtf.video.frame_iterator(videos.video, fps=1)) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Generated by Claude
Refactor core skill: mental model + anti-patterns
Background
Ran the Anthropic skill-creator evaluation against the v1 skill. The refactor follows Anthropic's skill authoring best practices — particularly wrong/right pattern framing, problem-first design, and keeping skills under 500 lines. Key findings:
Developed a 4-phase plan: fix core skill structure, eliminate API_REFERENCE.md, create specialized skills (RAG, media, agents, app), sweep imports.
What changed (Phase 1 — core skill)
Restructured from flat API sections into three that build on each other:
if_existsmisuse, async FastAPI, single-row tables, custom UDFs duplicating built-ins, defensive wrappers, UDFs called outside the table, external tools that duplicate built-in capabilities, manual JSON parsing)."I need X" → use Y) for tables, views, computed columns, CRUD operations, querying, embedding indexes, versioning, JSON path expressions, 4 export paths, and sampling.The biggest conceptual additions are things the v1 didn't need to say because they're obvious if you already know Pixeltable, but an agent doesn't know them:
t.describe()for lineage and time-travel queries for comparison.if_existshas three distinct use cases. Now explained as its own section:'error'for safety,'ignore'for setup scripts,'replace'for iteration.Also added: test-then-commit workflow (
.head()beforeadd_computed_column), JSON path expressions for navigating AI API responses, sampling with stratification, and a problem-first skill description for marketplace discoverability.Moved to specialized skills (future PRs):
@pxt.query, provider table, companion resourcesexport_sql(),.to_pytorch_dataset(),.to_coco_dataset()(specialized export paths)Still to do (future PRs)
pxtf.*imports