Rewrite pi-skill-creator SKILL.md as context-driven guidance
Session from pi-extensions-sessions on Hugging Face by thomasmustier · MIT · condensed by Coders Talk
Compare two skill-authoring SKILL.md files, then iteratively refine the pi-skill-creator skill (structure, phrasing, references) into a concise, standalone, context-framed skill, and publish the release.
- +0Prompt · +0Review two skill files (codex-skill-creator vs pi-skill-creator SKILL.md) and opine on which is clearer/more helpful.
- +0mAgent did · +0mRead both SKILL.md files and produced a detailed comparison table plus prose analysis of strengths/weaknesses of each version.
- +1mPrompt · +1mInclude the good bits from the Codex version into the Pi skill.
- +1mAgent did · +1mRead existing reference files, wrote a new references/design-patterns.md distilling degrees-of-freedom, progressive disclosure and requirements-gathering, and linked it from SKILL.md.
- +2mPrompt · +2mApplied feedback from another agent: justify the README rule, clarify skeleton step, move name rules near workflow, explain optional frontmatter fields.
- +5mPrompt · +5mStop repeating the README rule twice, and generally reframe instructions as context rather than directives.
- +5mAgent did · +5mDeduplicated the README mention, then went through the whole SKILL.md renaming 'Core principles' and reframing conciseness, progressive disclosure, activation and directive lines as context-based explanations.
- +28mIntervention · +28mRejected the README.md requirement in Step 3, wanted name rules centralized in the format section not duplicated, and rewrote the context-principle example to a clearer 'X helps Y because Z' framing.Why: A skill only truly needs a directory containing SKILL.md, and the example for the context principle felt off — I wanted a clearer, more general phrasing.
- +32mPrompt · +32mReview the remaining reference docs, then decide whether design-patterns.md is even needed, and fold anything essential back into a standalone SKILL.md before deleting it.
- +32mAgent did · +32mReviewed and merged three reference files into one, then concluded most content was redundant with a capable agent's own knowledge, folded the two Pi-specific reference guidelines into SKILL.md step 7, and deleted the references directory entirely — SKILL.md now standalone at ~131 lines.
- Break · 37m away, not counted
- +36mPrompt · +36mOnce done, follow RELEASING.md and commit/push/release/publish the changes.
- +36mOutcome · +36mCommitted (7 files changed, 10 insertions, 214 deletions), tagged pi-skill-creator/v0.2.0, pushed, published @tmustier/[email protected] and [email protected] to npm, and created the GitHub release.
Next time I'd open by stating the 'context over directives' principle up front, since that ended up driving almost every later edit — it would have saved a couple of rounds of rewriting. The correction that did the most work was pushing back on the duplicated README rule and the weak context-principle example, which forced a real audit of directive-vs-context phrasing across the whole file rather than a surface pass. Deciding to delete the references file entirely and fold only the truly non-obvious bits into SKILL.md was the right call for keeping the skill standalone and concise.