refactor(ai): migrate prompts into skills and port docs to .agents (#930)

lmeyerov · web-flow · commit 2f12a7953149 · 2026-03-02T19:20:22.000-08:00
* refactor(ai): migrate prompts into skills and port docs

* docs(changelog): note ai skills and .agents migration

* refactor(ai): make .agents skills canonical for claude
diff --git a/.agents/README.md b/.agents/README.md
@@ -0,0 +1,45 @@
+# .agents
+
+Assistant-facing support material for this repository.
+
+## Purpose
+
+- Keep reusable agent docs and helper scripts in one place.
+- Keep task-oriented skill definitions in `.agents/skills/`.
+
+## Layout
+
+```text
+.agents/
+├── README.md
+├── assets/
+│   ├── find_dynamic_imports.sh
+│   ├── generate_comment_inventory.sh
+│   └── pysa_extract_callers.py
+└── docs/
+    └── gfql/
+        ├── README.md
+        ├── calls_checklist.md
+        ├── conformance.md
+        ├── oracle.md
+        └── predicates_checklist.md
+```
+
+## Related Paths
+
+- Skills: `.agents/skills/`
+- Skill index: `.agents/skills/SKILLS.md`
+- Plans (gitignored): `plans/`
+
+## Quick Commands
+
+```bash
+# Generate dynamic import inventory for refactors
+./.agents/assets/find_dynamic_imports.sh master plans/<task>/dynamic_imports.md
+
+# Generate comment inventory for cleanup passes
+./.agents/assets/generate_comment_inventory.sh master plans/<task>/comment_inventory.md
+
+# Extract callers from pysa call graph
+python3 .agents/assets/pysa_extract_callers.py pysa_results/call-graph.json PlotterBase.PlotterBase.bind
+```
diff --git a/.agents/assets/find_dynamic_imports.sh b/.agents/assets/find_dynamic_imports.sh
@@ -1,14 +1,14 @@
 #!/bin/bash
 # Find Dynamic Imports for HOISTIMPORTS Protocol
 #
-# Usage: ./ai/assets/find_dynamic_imports.sh [base_branch] [output_file]
+# Usage: ./.agents/assets/find_dynamic_imports.sh [base_branch] [output_file]
 #
 # This script automates Phase 1 of the HOISTIMPORTS protocol by extracting all
 # dynamic imports (imports inside functions/methods/conditionals) added in a PR
 # and formatting them with context for categorization.
 #
 # Example:
-#   ./ai/assets/find_dynamic_imports.sh master plans/my-feature/dynamic_imports.md
+#   ./.agents/assets/find_dynamic_imports.sh master plans/my-feature/dynamic_imports.md
 
 set -euo pipefail
 
diff --git a/.agents/assets/generate_comment_inventory.sh b/.agents/assets/generate_comment_inventory.sh
@@ -1,13 +1,13 @@
 #!/bin/bash
 # Generate Comment Inventory for DECOMMENT Protocol
 #
-# Usage: ./ai/assets/generate_comment_inventory.sh [base_branch] [output_file]
+# Usage: ./.agents/assets/generate_comment_inventory.sh [base_branch] [output_file]
 #
 # This script automates Phase 1 of the DECOMMENT protocol by extracting all
 # comments added in a PR and formatting them with context for categorization.
 #
 # Example:
-#   ./ai/assets/generate_comment_inventory.sh master plans/my-feature/comment_inventory.md
+#   ./.agents/assets/generate_comment_inventory.sh master plans/my-feature/comment_inventory.md
 
 set -euo pipefail
 
diff --git a/.agents/assets/pysa_extract_callers.py b/.agents/assets/pysa_extract_callers.py
@@ -2,10 +2,10 @@
 """Extract caller information from Pysa call-graph.json
 
 Usage:
-    python3 ai/assets/pysa_extract_callers.py path/to/call-graph.json method1 method2 ...
+    python3 .agents/assets/pysa_extract_callers.py path/to/call-graph.json method1 method2 ...
 
 Example:
-    python3 ai/assets/pysa_extract_callers.py \\
+    python3 .agents/assets/pysa_extract_callers.py \\
         pysa_results/call-graph.json \\
         PlotterBase.PlotterBase.bind \\
         PlotterBase.PlotterBase.nodes
diff --git a/.agents/docs/gfql/README.md b/.agents/docs/gfql/README.md
@@ -8,7 +8,7 @@ Guide for AI assistants working with GFQL (Graph Frame Query Language) in PyGrap
 - [`calls_checklist.md`](./calls_checklist.md) — Required steps for exposing or updating GFQL `call()` functions.
 - [`predicates_checklist.md`](./predicates_checklist.md) — End-to-end checklist for predicate implementations.
 - [`conformance.md`](./conformance.md) — Cypher TCK conformance harness and CI wiring.
-- [`../prompts/GFQL_LLM_GUIDE_MAINTENANCE.md`](../prompts/GFQL_LLM_GUIDE_MAINTENANCE.md) — Guidance for keeping AI assistants aligned with GFQL changes.
+- [`../../skills/gfql-llm-guide-maintenance/SKILL.md`](../../skills/gfql-llm-guide-maintenance/SKILL.md) — Guidance for keeping AI assistants aligned with GFQL changes.
 
 ### Essential GFQL Operations
 ```python
diff --git a/.agents/docs/gfql/calls_checklist.md b/.agents/docs/gfql/calls_checklist.md
@@ -4,7 +4,7 @@ When exposing or updating GFQL `call()` functions, the change is **multi-system*
 runtime executors, JSON schema validators, static typing, documentation, and tests
 all need to stay in sync. Use this playbook (paired with
 [`predicates_checklist.md`](./predicates_checklist.md) and the guidance in
-[`../prompts/GFQL_LLM_GUIDE_MAINTENANCE.md`](../../prompts/GFQL_LLM_GUIDE_MAINTENANCE.md))
+[`../../skills/gfql-llm-guide-maintenance/SKILL.md`](../../skills/gfql-llm-guide-maintenance/SKILL.md))
 to avoid regressions.
 
 > **Scope**: Items below are required for *every* new or modified `call()` entry.
@@ -90,7 +90,7 @@ to avoid regressions.
 ## 📎 Optional (Promote When User-Facing)
 
 - **Marketing / blog teaser** when the call is a marquee feature.
-- **LLM prompt updates** (`ai/prompts/gfql/*`) beyond baseline instructions.
+- **LLM prompt updates** (`.agents/skills/gfql-llm-guide-maintenance/SKILL.md`) beyond baseline instructions.
 - **Customer templates** or dataset refreshes referencing the new capability.
 
 Keep this file synchronized with future GFQL evolutions—open a PR to amend when the onboarding surface changes.
diff --git a/.agents/docs/gfql/conformance.md b/.agents/docs/gfql/conformance.md
diff --git a/.agents/docs/gfql/oracle.md b/.agents/docs/gfql/oracle.md
diff --git a/.agents/docs/gfql/predicates_checklist.md b/.agents/docs/gfql/predicates_checklist.md
diff --git a/.agents/skills/SKILLS.md b/.agents/skills/SKILLS.md
@@ -0,0 +1,11 @@
+# Skills Catalog
+
+Each skill is a folder containing `SKILL.md` with YAML frontmatter.
+
+- `conventional-commits`
+- `decomment`
+- `gfql-llm-guide-maintenance`
+- `hoist-imports`
+- `lint-types-check`
+- `plan`
+- `pyre-analysis`
diff --git a/.agents/skills/conventional-commits/SKILL.md b/.agents/skills/conventional-commits/SKILL.md
@@ -1,6 +1,11 @@
+---
+name: conventional-commits
+description: "Create atomic PyGraphistry commits with conventional commit messages and patch-based staging. Use when preparing commit sequences, selecting staged hunks, or writing commit messages."
+---
+
 # Conventional Commits Guide for PyGraphistry
 
-**⚠️ BEFORE STARTING: Reread [ai/prompts/PLAN.md](PLAN.md). Reuse existing `plans/*/plan.md` if one exists, else start a new one.**
+**⚠️ BEFORE STARTING: Reread [the planning skill](../plan/SKILL.md). Reuse existing `plans/*/plan.md` if one exists, else start a new one.**
 
 PyGraphistry-specific commit conventions only. See PLAN.md for execution protocol.
 
diff --git a/.agents/skills/decomment/SKILL.md b/.agents/skills/decomment/SKILL.md
@@ -1,3 +1,8 @@
+---
+name: decomment
+description: "Remove low-value comments from pull requests while preserving necessary documentation. Use before review or merge when cleaning up explanatory comments in changed code."
+---
+
 # Decomment Protocol
 
 **Purpose:** Remove unnecessary comments from PRs while preserving valuable documentation.
@@ -15,7 +20,7 @@ This protocol guides the systematic removal of redundant comments from code chan
 
 ## Prerequisites
 
-1. **Plan File**: Ensure you have a current plan file (see `ai/prompts/PLAN.md`)
+1. **Plan File**: Ensure you have a current plan file (see `../plan/SKILL.md`)
    - If no plan exists for this work, create one following PLAN.md template
    - If plan exists but is stale, refresh it with current state
 2. **Clean Git State**: All changes committed to feature branch
@@ -39,7 +44,7 @@ This protocol guides the systematic removal of redundant comments from code chan
 **Commands:**
 ```bash
 # Automated inventory generation (RECOMMENDED)
-./ai/assets/generate_comment_inventory.sh master plans/[task]/comment_inventory.md
+./.agents/assets/generate_comment_inventory.sh master plans/[task]/comment_inventory.md
 
 # Manual alternatives:
 # Get base branch
@@ -217,7 +222,7 @@ Phase 4: Verification Results
 ls plans/[current-task]/plan.md
 
 # If no plan exists:
-# 1. Create plan following ai/prompts/PLAN.md template
+# 1. Create plan following ../plan/SKILL.md template
 # 2. Document decomment work as Phase N.A: "Remove redundant comments"
 
 # If plan exists but stale:
diff --git a/.agents/skills/gfql-llm-guide-maintenance/SKILL.md b/.agents/skills/gfql-llm-guide-maintenance/SKILL.md
@@ -1,3 +1,8 @@
+---
+name: gfql-llm-guide-maintenance
+description: "Maintain GFQL LLM guidance docs when call surfaces, predicates, algorithms, or common failure patterns change. Use for release updates and guide conformance checks."
+---
+
 # LLM_GUIDE.md Maintenance Process
 
 **Purpose**: Update `LLM_GUIDE.md` when GFQL features change or user patterns emerge.
@@ -13,7 +18,7 @@
 5. **LLMs generating invalid JSON** → [LLM Failures](#llm-failures)
 6. **Multiple changes** → [Multi-Change Releases](#multi-change-releases)
 
-**See also**: the end-to-end checklist in `ai/docs/gfql/calls_checklist.md`
+**See also**: the end-to-end checklist in `.agents/docs/gfql/calls_checklist.md`
 whenever a `call()` surface changes.
 
 ## Update Triggers
@@ -97,7 +102,7 @@ grep "new_fn" graphistry/tests/compute/ -rn
 ```
 
 **Update**: `## Graph Algorithms` (add example) + `## Call Functions` (list)
-- Cross-check `ai/docs/gfql/calls_checklist.md` for required code/tests/doc updates
+- Cross-check `.agents/docs/gfql/calls_checklist.md` for required code/tests/doc updates
 
 **Format**:
 ```markdown
diff --git a/.agents/skills/hoist-imports/SKILL.md b/.agents/skills/hoist-imports/SKILL.md
@@ -1,10 +1,15 @@
+---
+name: hoist-imports
+description: "Refactor dynamic imports to top-level imports with an inventory, categorization, and verification workflow. Use during cleanup or review-prep when import placement needs standardization."
+---
+
 # Hoist Imports Protocol
 
 **Purpose:** Move dynamic imports to top-level unless there's a documented reason not to.
 
 ## Quick Reference (60-second version)
 
-1. **Identify**: Run `./ai/assets/find_dynamic_imports.sh master plans/[task]/dynamic_imports.md`
+1. **Identify**: Run `./.agents/assets/find_dynamic_imports.sh master plans/[task]/dynamic_imports.md`
 2. **Categorize**: Review each as HOIST (move to top) or KEEP (document reason)
 3. **Hoist**: Move imports to top-level following PEP 8 section ordering
 4. **Verify**: Run tests, confirm no circular imports or heavy load issues
@@ -27,7 +32,7 @@ This protocol guides the systematic refactoring of dynamic imports (imports insi
 
 ## Prerequisites
 
-1. **Plan File**: Ensure you have a current plan file (see `ai/prompts/PLAN.md`)
+1. **Plan File**: Ensure you have a current plan file (see `../plan/SKILL.md`)
 2. **Clean Git State**: All changes committed to feature branch
 3. **PR Context**: Know which branch the PR will land into (usually `master` or `main`)
 
@@ -50,7 +55,7 @@ This protocol guides the systematic refactoring of dynamic imports (imports insi
 **Commands:**
 ```bash
 # Automated inventory generation (RECOMMENDED)
-./ai/assets/find_dynamic_imports.sh master plans/[task]/dynamic_imports.md
+./.agents/assets/find_dynamic_imports.sh master plans/[task]/dynamic_imports.md
 
 # Manual alternatives (if automation script unavailable):
 # Get base branch
@@ -324,7 +329,7 @@ Add this phase to your plan:
 
 **Tool Calls:**
 ```bash
-./ai/assets/find_dynamic_imports.sh master plans/[task]/dynamic_imports.md
+./.agents/assets/find_dynamic_imports.sh master plans/[task]/dynamic_imports.md
 # [edit commands]
 git commit -m "refactor: Hoist dynamic imports to top-level"
 git push
diff --git a/.agents/skills/lint-types-check/SKILL.md b/.agents/skills/lint-types-check/SKILL.md
@@ -1,3 +1,8 @@
+---
+name: lint-types-check
+description: "Run iterative lint and typecheck remediation for PyGraphistry. Use when fixing flake8/mypy issues and driving a branch to clean validation results."
+---
+
 # Lint and Type Check Template for PyGraphistry
 
 <!-- FILE TRACKING HEADER - FILL IN WHEN FILE CREATED -->
diff --git a/.agents/skills/plan/SKILL.md b/.agents/skills/plan/SKILL.md
@@ -1,3 +1,8 @@
+---
+name: plan
+description: "Create and maintain a resumable phased execution plan for complex tasks. Use when work spans multiple steps or sessions and requires strict status tracking."
+---
+
 # Task Plan Template
 
 <!-- ═══════════════════════════════════════════════════════════════════════════
@@ -126,8 +131,8 @@ git log --oneline -n 10
 - Tests: `graphistry/tests/` (mirrors source structure: `graphistry/foo/bar.py` → `graphistry/tests/foo/test_bar.py`)
 - Docs: `docs/`
 - Plans: `plans/` (gitignored - safe for auxiliary files, temp secrets, working data; Codex: avoid `~/.codex/plans`; if used, copy here then delete)
-- AI prompts: `ai/prompts/`
-- AI docs: `ai/docs/`
+- AI skills: `.agents/skills/`
+- AI docs: `.agents/docs/`
 
 ### Security & Working Files
 
@@ -143,7 +148,7 @@ echo "export GRAPHISTRY_SERVER='https://hub.graphistry.com'" >> plans/[task]/.en
 source plans/[task]/.env
 ```
 
-**For commits:** See [ai/prompts/CONVENTIONAL_COMMITS.md](CONVENTIONAL_COMMITS.md)
+**For commits:** See [the conventional commits skill](../conventional-commits/SKILL.md)
 
 ## Phase Protocol
 
diff --git a/.agents/skills/pyre-analysis/SKILL.md b/.agents/skills/pyre-analysis/SKILL.md
@@ -1,3 +1,8 @@
+---
+name: pyre-analysis
+description: "Run Pyre/Pysa analysis for call graphs and caller extraction in PyGraphistry. Use for type-aware refactors, indirect dependency tracing, and call-chain debugging."
+---
+
 # Pyre/Pysa Analysis for PyGraphistry
 
 **Recommendation**: Use AST (< 1s) for direct patterns, then Pysa (~60s) for call chains
@@ -15,14 +20,14 @@ docker run --rm -v $(pwd):/workspace -w /workspace python:3.12-slim \
 ls -lh pysa_results/call-graph.json  # Should be ~16MB, 37626 functions
 ```
 
-**3. Extract callers** (see `ai/assets/pysa_extract_callers.py`):
+**3. Extract callers** (see `.agents/assets/pysa_extract_callers.py`):
 ```bash
 # Single method
-python3 ai/assets/pysa_extract_callers.py pysa_results/call-graph.json \
+python3 .agents/assets/pysa_extract_callers.py pysa_results/call-graph.json \
   PlotterBase.PlotterBase.bind
 
 # Multiple methods
-python3 ai/assets/pysa_extract_callers.py pysa_results/call-graph.json \
+python3 .agents/assets/pysa_extract_callers.py pysa_results/call-graph.json \
   PlotterBase.PlotterBase.bind \
   PlotterBase.PlotterBase.nodes \
   PlotterBase.PlotterBase.edges
diff --git a/.gitignore b/.gitignore
@@ -105,3 +105,7 @@ AI_PROGRESS/
 plans/
 tmp/
 test_env/
+
+# Claude Code local setup
+.claude/settings.local.json
+.claude/skills
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -22,6 +22,9 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 ### Tests
 - **Collections**: Added `test_collections.py` covering encoding, GFQL Chain/AST normalization, wire-protocol acceptance, validation modes, and helper constructors.
 
+### Docs
+- **AI tooling**: Migrated legacy assistant prompts from `ai/prompts/` into structured skills under `.agents/skills/*/SKILL.md` (with frontmatter), and moved assistant docs/assets into `.agents/` with updated internal references (#930).
+
 ## [0.50.6 - 2026-01-27]
 
 ### Fixed
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -1 +1,11 @@
-See [ai/README.md](ai/README.md) for AI assistant development guidance.
+@AGENTS.md
+
+## Claude Code Setup
+
+If no repo skills appear in Claude Code (check with `/skills`), configure the local symlink:
+
+```bash
+ln -s ../.agents/skills .claude/skills
+```
+
+If `.claude/skills` already exists and is wrong, replace it with the symlink above.
diff --git a/ai/README.md b/ai/README.md

Original file line number	Diff line number	Diff line change
`@@ -1,14 +1,14 @@`
`1`	`1`	`#!/bin/bash`
`2`	`2`	`# Find Dynamic Imports for HOISTIMPORTS Protocol`
`3`	`3`	`#`
`4`		`-# Usage: ./ai/assets/find_dynamic_imports.sh [base_branch] [output_file]`
	`4`	`+# Usage: ./.agents/assets/find_dynamic_imports.sh [base_branch] [output_file]`
`5`	`5`	`#`
`6`	`6`	`# This script automates Phase 1 of the HOISTIMPORTS protocol by extracting all`
`7`	`7`	`# dynamic imports (imports inside functions/methods/conditionals) added in a PR`
`8`	`8`	`# and formatting them with context for categorization.`
`9`	`9`	`#`
`10`	`10`	`# Example:`
`11`		`-# ./ai/assets/find_dynamic_imports.sh master plans/my-feature/dynamic_imports.md`
	`11`	`+# ./.agents/assets/find_dynamic_imports.sh master plans/my-feature/dynamic_imports.md`
`12`	`12`
`13`	`13`	`set -euo pipefail`
`14`	`14`
Original file line number	Diff line number	Diff line change
`@@ -1,13 +1,13 @@`
`1`	`1`	`#!/bin/bash`
`2`	`2`	`# Generate Comment Inventory for DECOMMENT Protocol`
`3`	`3`	`#`
`4`		`-# Usage: ./ai/assets/generate_comment_inventory.sh [base_branch] [output_file]`
	`4`	`+# Usage: ./.agents/assets/generate_comment_inventory.sh [base_branch] [output_file]`
`5`	`5`	`#`
`6`	`6`	`# This script automates Phase 1 of the DECOMMENT protocol by extracting all`
`7`	`7`	`# comments added in a PR and formatting them with context for categorization.`
`8`	`8`	`#`
`9`	`9`	`# Example:`
`10`		`-# ./ai/assets/generate_comment_inventory.sh master plans/my-feature/comment_inventory.md`
	`10`	`+# ./.agents/assets/generate_comment_inventory.sh master plans/my-feature/comment_inventory.md`
`11`	`11`
`12`	`12`	`set -euo pipefail`
`13`	`13`