Refresh extending-pi skill guidance

[tmustier]

Summary

• update extending-pi to emphasize extension-first customization before Pi internal patches
• broaden triggers for behavior changes and remove stale extension scaffolding/API snippets
• rename Pi-specific skill wording to Agent Skills across the skill, nested skill, README, and package metadata

Validation

• extending-pi/skill-creator/scripts/validate_skill.py extending-pi
• extending-pi/skill-creator/scripts/validate_skill.py extending-pi/skill-creator
• python3 -m json.tool on root and nested package manifests
• git diff --check
• npm pack --dry-run --json in extending-pi and extending-pi/skill-creator

[github-actions]

🔍 Tessl Skill Review

extending-pi/SKILL.md

Review Details

Review Details

Dimension	Score	Detail	Suggestion
conciseness	██░ 2/3	efficient and avoids explaining basic concepts, but some sections are verbose—particularly the patch policy and extension workflow sections repeat the 'read the docs' instruction multiple times. The table is well-structured but the surrounding prose could be tightened.	Add at least one minimal, executable scaffold example (e.g., a skeleton TypeScript extension or a minimal SKILL.md frontmatter) so the skill provides some copy-paste-ready starting point than purely routing to docs.
actionability	██░ 2/3	The skill provides concrete CLI commands for validation (e.g., pi --no-skills --skill /path/to/skill, pi -e ./path/to/extension.ts) and clear file paths, but deliberately avoids executable code examples, API signatures, or copy-paste-ready scaffolding. It routes to docs than providing directly actionable content, which is a design choice but reduces immediate actionability.	Consolidate repeated 'read the docs first' instructions across the behavior-change triage, extension workflow, and patch policy sections to reduce redundancy and improve token efficiency.
workflow clarity	███ 3/3	The behavior-change triage is a well-sequenced 5-step process with a clear escalation path and explicit gate before patching. The TypeScript extension workflow is a 6-step audit with validation checkpoints. The quick-start steps provide a clear overall sequence with validation for each artifact type. The patch policy includes a stop-and-verify checkpoint before proceeding.
progressive disclosure	███ 3/3	structured as a routing/overview document that explicitly points to specific docs, examples, and type files for each extension point. References are one level deep and clearly signaled in the table's 'Detailed source of truth' column. The skill explicitly states 'not an API reference' and routes to the right detailed sources.

---

extending-pi/skill-creator/SKILL.md

Review Details

Review Details

Dimension	Score	Detail	Suggestion
conciseness	██░ 2/3	efficient but includes some unnecessary explanation (e.g., explaining what README.md is for, the {baseDir} placeholder note, and some obvious guidance like 'Only add resource sub-directories that are needed'). Could be tightened in several places, though it avoids egregious padding.	Trim explanatory sentences that state the obvious (e.g., 'If you plan to share the skill with humans, a README.md helps discovery and installation') to improve conciseness.
actionability	███ 3/3	Provides concrete, executable commands throughout (mkdir, touch, bash validation commands, pi CLI invocations), specific frontmatter examples with correct YAML syntax, and clear directory structures. The guidance is copy-paste ready at each step.	Consider condensing the 'Agent Skills format' section into a more compact reference table than a bullet list with full sentences.
workflow clarity	███ 3/3	The 9-step workflow is clearly sequenced from clarification through publishing, with an explicit validation step (step 8) that includes multiple verification methods (validator script, loading with --no-skills, explicit invocation, /reload after edits). The progression is logical and each step builds on the previous one.
progressive disclosure	███ 3/3	Content is well-structured with a clear overview of the format, recommended structure, then a step-by-step workflow. References to external files (references/PUBLISHING.md) are one level deep and clearly signaled with when to consult them. The skill appropriately keeps the body as an overview and delegates detailed publishing info to a reference file.

---

Optional: add a Tessl API token as TESSL_API_TOKEN in your repo secrets. The action will suggest an optimized version automatically in future PRs.