@maxiaochao/pi-toolkit 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -1,4 +1,9 @@
-## 2026-08-19 - v0.1.6
+## 2026-08-21 - v0.1.7
+
+- add the html-artifact skill for interactive HTML explanations and codebase visualizations
+- register and package the skill for Pi discovery
+- prefer `.cache/html/` for generated temporary HTML artifacts
+
 
 - expand global agent guidance and reuse-before-writing rules
 

package/global/AGENTS.md

@@ -102,4 +102,9 @@ After each significant step:
 
 ---
 
-**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
+
+## Output Format Preference
+
+For complex explanations, prefer a runnable HTML artifact over a long Markdown-only response when the content benefits from visual structure or interaction. This includes workflows, code/module relationships, state machines, event/data flows, architecture maps, timelines, comparisons, dashboards, and interactive demonstrations. Keep ordinary prose, short answers, diffs, and focused code reviews in Markdown.
+
+When using HTML, create a self-contained, responsive artifact in the project's established output location, or `.cache/html/<descriptive-name>.html` when no convention exists. Use semantic HTML, accessible controls, escaped code blocks, and small useful interactions. Return a concise Markdown summary with a clickable local file path; if a preview/server tool is available, start it and return the preview URL only after verifying the page is not blank and its assets load.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Personal pi coding agent toolkit: /todos extension + /cache_export interactive cache dashboard.",
   "type": "module",
   "keywords": [
@@ -12,7 +12,8 @@
     "README.md",
     "CHANGELOG.md",
     "global/AGENTS.md",
-    "scripts/install-agents.mjs"
+    "scripts/install-agents.mjs",
+    "skills"
   ],
   "repository": {
     "type": "git",
@@ -22,6 +23,9 @@
     "extensions": [
       "./extensions/todo.ts",
       "./extensions/cache-export/index.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "peerDependencies": {

package/skills/html-artifact/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: html-artifact
+description: Create self-contained, responsive HTML artifacts for complex explanations that benefit from visual structure or interaction, including workflows, code/module relationships, state machines, event/data flows, architecture maps, timelines, comparisons, dashboards, and interactive demonstrations. Use Markdown for ordinary prose, short answers, diffs, and focused code reviews.
+---
+
+# HTML Artifact
+
+Use this skill when the user needs to understand or explore a complex process, codebase relationship, system design, state transition, comparison, or other content where static Markdown would be hard to scan or interact with.
+
+## Decide the format
+
+Use Markdown when the response is short, linear, text-first, or primarily a focused code review. Use an HTML artifact when visual layout, filtering, expanding details, tabs, highlighting, diagrams, timelines, or interactive state changes materially improve understanding.
+
+Do not create HTML merely to wrap a small answer. The artifact should reduce cognitive load and make the subject easier to inspect.
+
+## Create the artifact
+
+1. Read the relevant code and verify names, relationships, and behavior before visualizing them.
+2. Follow the project's existing output convention. If none exists, write to `.cache/html/<descriptive-name>.html`.
+3. Prefer one self-contained HTML file with inline CSS and JavaScript so it can be opened or previewed without a build step.
+4. Use semantic HTML, responsive layout, keyboard-accessible controls, visible focus states, and stable dimensions for interactive elements.
+5. Use restrained styling suited to the domain. Keep diagrams and panels scannable; do not hide important information behind interaction.
+6. Escape source code before placing it in `<pre><code>` blocks. Do not alter code identifiers, paths, or quoted source text for presentation.
+7. Add only interactions that answer a real viewing need: tabs, expand/collapse, search/filter, step-through state, highlighting, or a reset control.
+8. Keep external dependencies out unless the project already uses them. If a library is necessary, document the dependency and provide a usable fallback when practical.
+
+## Verify and report
+
+After writing the file, verify that it exists and contains a complete document. If a preview or dev-server tool is available, start it and check the returned health status before reporting success. Use the preview URL returned by that tool; never present `localhost` as a user-facing online URL when the environment uses a reverse proxy.
+
+Respond with a concise Markdown summary and a clickable file path or verified preview URL. Mention any limitation, such as a preview service not being available. Do not paste the entire HTML into the chat unless the user explicitly asks for it.