gsd-pi 2.28.0 → 2.29.0-dev.2ccf3fb

package/src/resources/skills/create-skill/workflows/get-guidance.md

@@ -0,0 +1,121 @@
+# Workflow: Get Guidance on Skill Design
+
+<required_reading>
+**Read these reference files NOW:**
+1. references/core-principles.md
+2. references/recommended-structure.md
+</required_reading>
+
+<process>
+## Step 1: Understand the Problem Space
+
+Ask the user:
+- What task or domain are you trying to support?
+- Is this something you do repeatedly?
+- What makes it complex enough to need a skill?
+
+## Step 2: Determine If a Skill Is Right
+
+**Create a skill when:**
+- Task is repeated across multiple sessions
+- Domain knowledge doesn't change frequently
+- Complex enough to benefit from structure
+- Would save significant time if automated
+
+**Don't create a skill when:**
+- One-off task (just do it directly)
+- Changes constantly (will be outdated quickly)
+- Too simple (overhead isn't worth it)
+- Better as a slash command (user-triggered, no context needed)
+
+Share this assessment with user.
+
+## Step 3: Map the Workflows
+
+Ask: "What are the different things someone might want to do with this skill?"
+
+Common patterns:
+- Create / Read / Update / Delete
+- Build / Debug / Ship
+- Setup / Use / Troubleshoot
+- Import / Process / Export
+
+Each distinct workflow = potential workflow file.
+
+## Step 4: Identify Domain Knowledge
+
+Ask: "What knowledge is needed regardless of which workflow?"
+
+This becomes references:
+- API patterns
+- Best practices
+- Common examples
+- Configuration details
+
+## Step 5: Draft the Structure
+
+Based on answers, recommend structure:
+
+**If 1 workflow, simple knowledge:**
+```
+skill-name/
+└── SKILL.md (everything in one file)
+```
+
+**If 2+ workflows, shared knowledge:**
+```
+skill-name/
+├── SKILL.md (router)
+├── workflows/
+│   ├── workflow-a.md
+│   └── workflow-b.md
+└── references/
+    └── shared-knowledge.md
+```
+
+## Step 6: Identify Essential Principles
+
+Ask: "What rules should ALWAYS apply, no matter which workflow?"
+
+These become `<essential_principles>` in SKILL.md.
+
+Examples:
+- "Always verify before reporting success"
+- "Never store credentials in code"
+- "Ask before making destructive changes"
+
+## Step 7: Present Recommendation
+
+Summarize:
+- Recommended structure (simple vs router pattern)
+- List of workflows
+- List of references
+- Essential principles
+
+Ask: "Does this structure make sense? Ready to build it?"
+
+If yes → offer to switch to "Create a new skill" workflow
+If no → clarify and iterate
+</process>
+
+<decision_framework>
+## Quick Decision Framework
+
+| Situation | Recommendation |
+|-----------|----------------|
+| Single task, repeat often | Simple skill |
+| Multiple related tasks | Router + workflows |
+| Complex domain, many patterns | Router + workflows + references |
+| User-triggered, fresh context | Slash command, not skill |
+| One-off task | No skill needed |
+</decision_framework>
+
+<success_criteria>
+Guidance is complete when:
+- [ ] User understands if they need a skill
+- [ ] Structure is recommended and explained
+- [ ] Workflows are identified
+- [ ] References are identified
+- [ ] Essential principles are identified
+- [ ] User is ready to build (or decided not to)
+</success_criteria>

package/src/resources/skills/create-skill/workflows/upgrade-to-router.md

@@ -0,0 +1,161 @@
+# Workflow: Upgrade Skill to Router Pattern
+
+<required_reading>
+**Read these reference files NOW:**
+1. references/recommended-structure.md
+2. references/skill-structure.md
+</required_reading>
+
+<process>
+## Step 1: Select the Skill
+
+```bash
+ls ~/.claude/skills/
+```
+
+Present numbered list, ask: "Which skill should be upgraded to the router pattern?"
+
+## Step 2: Verify It Needs Upgrading
+
+Read the skill:
+```bash
+cat ~/.claude/skills/{skill-name}/SKILL.md
+ls ~/.claude/skills/{skill-name}/
+```
+
+**Already a router?** (has workflows/ and intake question)
+→ Tell user it's already using router pattern, offer to add workflows instead
+
+**Simple skill that should stay simple?** (under 200 lines, single workflow)
+→ Explain that router pattern may be overkill, ask if they want to proceed anyway
+
+**Good candidate for upgrade:**
+- Over 200 lines
+- Multiple distinct use cases
+- Essential principles that shouldn't be skipped
+- Growing complexity
+
+## Step 3: Identify Components
+
+Analyze the current skill and identify:
+
+1. **Essential principles** - Rules that apply to ALL use cases
+2. **Distinct workflows** - Different things a user might want to do
+3. **Reusable knowledge** - Patterns, examples, technical details
+
+Present findings:
+```
+## Analysis
+
+**Essential principles I found:**
+- [Principle 1]
+- [Principle 2]
+
+**Distinct workflows I identified:**
+- [Workflow A]: [description]
+- [Workflow B]: [description]
+
+**Knowledge that could be references:**
+- [Reference topic 1]
+- [Reference topic 2]
+```
+
+Ask: "Does this breakdown look right? Any adjustments?"
+
+## Step 4: Create Directory Structure
+
+```bash
+mkdir -p ~/.claude/skills/{skill-name}/workflows
+mkdir -p ~/.claude/skills/{skill-name}/references
+```
+
+## Step 5: Extract Workflows
+
+For each identified workflow:
+
+1. Create `workflows/{workflow-name}.md`
+2. Add required_reading section (references it needs)
+3. Add process section (steps from original skill)
+4. Add success_criteria section
+
+## Step 6: Extract References
+
+For each identified reference topic:
+
+1. Create `references/{reference-name}.md`
+2. Move relevant content from original skill
+3. Structure with semantic XML tags
+
+## Step 7: Rewrite SKILL.md as Router
+
+Replace SKILL.md with router structure:
+
+```markdown
+---
+name: {skill-name}
+description: {existing description}
+---
+
+<essential_principles>
+[Extracted principles - inline, cannot be skipped]
+</essential_principles>
+
+<intake>
+**Ask the user:**
+
+What would you like to do?
+1. [Workflow A option]
+2. [Workflow B option]
+...
+
+**Wait for response before proceeding.**
+</intake>
+
+<routing>
+| Response | Workflow |
+|----------|----------|
+| 1, "keywords" | `workflows/workflow-a.md` |
+| 2, "keywords" | `workflows/workflow-b.md` |
+</routing>
+
+<reference_index>
+[List all references by category]
+</reference_index>
+
+<workflows_index>
+| Workflow | Purpose |
+|----------|---------|
+| workflow-a.md | [What it does] |
+| workflow-b.md | [What it does] |
+</workflows_index>
+```
+
+## Step 8: Verify Nothing Was Lost
+
+Compare original skill content against new structure:
+- [ ] All principles preserved (now inline)
+- [ ] All procedures preserved (now in workflows)
+- [ ] All knowledge preserved (now in references)
+- [ ] No orphaned content
+
+## Step 9: Test
+
+Invoke the upgraded skill:
+- Does intake question appear?
+- Does each routing option work?
+- Do workflows load correct references?
+- Does behavior match original skill?
+
+Report any issues.
+</process>
+
+<success_criteria>
+Upgrade is complete when:
+- [ ] workflows/ directory created with workflow files
+- [ ] references/ directory created (if needed)
+- [ ] SKILL.md rewritten as router
+- [ ] Essential principles inline in SKILL.md
+- [ ] All original content preserved
+- [ ] Intake question routes correctly
+- [ ] Tested and working
+</success_criteria>

package/src/resources/skills/create-skill/workflows/verify-skill.md

@@ -0,0 +1,204 @@
+# Workflow: Verify Skill Content Accuracy
+
+<required_reading>
+**Read these reference files NOW:**
+1. references/skill-structure.md
+</required_reading>
+
+<purpose>
+Audit checks structure. **Verify checks truth.**
+
+Skills contain claims about external things: APIs, CLI tools, frameworks, services. These change over time. This workflow checks if a skill's content is still accurate.
+</purpose>
+
+<process>
+## Step 1: Select the Skill
+
+```bash
+ls ~/.claude/skills/
+```
+
+Present numbered list, ask: "Which skill should I verify for accuracy?"
+
+## Step 2: Read and Categorize
+
+Read the entire skill (SKILL.md + workflows/ + references/):
+```bash
+cat ~/.claude/skills/{skill-name}/SKILL.md
+cat ~/.claude/skills/{skill-name}/workflows/*.md 2>/dev/null
+cat ~/.claude/skills/{skill-name}/references/*.md 2>/dev/null
+```
+
+Categorize by primary dependency type:
+
+| Type | Examples | Verification Method |
+|------|----------|---------------------|
+| **API/Service** | manage-stripe, manage-gohighlevel | Context7 + WebSearch |
+| **CLI Tools** | build-macos-apps (xcodebuild, swift) | Run commands |
+| **Framework** | build-iphone-apps (SwiftUI, UIKit) | Context7 for docs |
+| **Integration** | setup-stripe-payments | WebFetch + Context7 |
+| **Pure Process** | create-agent-skills | No external deps |
+
+Report: "This skill is primarily [type]-based. I'll verify using [method]."
+
+## Step 3: Extract Verifiable Claims
+
+Scan skill content and extract:
+
+**CLI Tools mentioned:**
+- Tool names (xcodebuild, swift, npm, etc.)
+- Specific flags/options documented
+- Expected output patterns
+
+**API Endpoints:**
+- Service names (Stripe, Meta, etc.)
+- Specific endpoints documented
+- Authentication methods
+- SDK versions
+
+**Framework Patterns:**
+- Framework names (SwiftUI, React, etc.)
+- Specific APIs/patterns documented
+- Version-specific features
+
+**File Paths/Structures:**
+- Expected project structures
+- Config file locations
+
+Present: "Found X verifiable claims to check."
+
+## Step 4: Verify by Type
+
+### For CLI Tools
+```bash
+# Check tool exists
+which {tool-name}
+
+# Check version
+{tool-name} --version
+
+# Verify documented flags work
+{tool-name} --help | grep "{documented-flag}"
+```
+
+### For API/Service Skills
+Use Context7 to fetch current documentation:
+```
+mcp__context7__resolve-library-id: {service-name}
+mcp__context7__get-library-docs: {library-id}, topic: {relevant-topic}
+```
+
+Compare skill's documented patterns against current docs:
+- Are endpoints still valid?
+- Has authentication changed?
+- Are there deprecated methods being used?
+
+### For Framework Skills
+Use Context7:
+```
+mcp__context7__resolve-library-id: {framework-name}
+mcp__context7__get-library-docs: {library-id}, topic: {specific-api}
+```
+
+Check:
+- Are documented APIs still current?
+- Have patterns changed?
+- Are there newer recommended approaches?
+
+### For Integration Skills
+WebSearch for recent changes:
+```
+"[service name] API changes 2025"
+"[service name] breaking changes"
+"[service name] deprecated endpoints"
+```
+
+Then Context7 for current SDK patterns.
+
+### For Services with Status Pages
+WebFetch official docs/changelog if available.
+
+## Step 5: Generate Freshness Report
+
+Present findings:
+
+```
+## Verification Report: {skill-name}
+
+### ✅ Verified Current
+- [Claim]: [Evidence it's still accurate]
+
+### ⚠️ May Be Outdated
+- [Claim]: [What changed / newer info found]
+  → Current: [what docs now say]
+
+### ❌ Broken / Invalid
+- [Claim]: [Why it's wrong]
+  → Fix: [What it should be]
+
+### ℹ️ Could Not Verify
+- [Claim]: [Why verification wasn't possible]
+
+---
+**Overall Status:** [Fresh / Needs Updates / Significantly Stale]
+**Last Verified:** [Today's date]
+```
+
+## Step 6: Offer Updates
+
+If issues found:
+
+"Found [N] items that need updating. Would you like me to:"
+
+1. **Update all** - Apply all corrections
+2. **Review each** - Show each change before applying
+3. **Just the report** - No changes
+
+If updating:
+- Make changes based on verified current information
+- Add verification date comment if appropriate
+- Report what was updated
+
+## Step 7: Suggest Verification Schedule
+
+Based on skill type, recommend:
+
+| Skill Type | Recommended Frequency |
+|------------|----------------------|
+| API/Service | Every 1-2 months |
+| Framework | Every 3-6 months |
+| CLI Tools | Every 6 months |
+| Pure Process | Annually |
+
+"This skill should be re-verified in approximately [timeframe]."
+</process>
+
+<verification_shortcuts>
+## Quick Verification Commands
+
+**Check if CLI tool exists and get version:**
+```bash
+which {tool} && {tool} --version
+```
+
+**Context7 pattern for any library:**
+```
+1. resolve-library-id: "{library-name}"
+2. get-library-docs: "{id}", topic: "{specific-feature}"
+```
+
+**WebSearch patterns:**
+- Breaking changes: "{service} breaking changes 2025"
+- Deprecations: "{service} deprecated API"
+- Current best practices: "{framework} best practices 2025"
+</verification_shortcuts>
+
+<success_criteria>
+Verification is complete when:
+- [ ] Skill categorized by dependency type
+- [ ] Verifiable claims extracted
+- [ ] Each claim checked with appropriate method
+- [ ] Freshness report generated
+- [ ] Updates applied (if requested)
+- [ ] User knows when to re-verify
+</success_criteria>

package/src/resources/skills/make-interfaces-feel-better/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: make-interfaces-feel-better
+description: Design engineering principles for making interfaces feel polished. Use when building UI components, reviewing frontend code, implementing animations, hover states, shadows, borders, typography, micro-interactions, enter/exit animations, or any visual detail work. Triggers on UI polish, design details, "make it feel better", "feels off", stagger animations, border radius, optical alignment, font smoothing, tabular numbers, image outlines, box shadows.
+---
+
+# Details that make interfaces feel better
+
+Great interfaces rarely come from a single thing. It's usually a collection of small details that compound into a great experience. Apply these principles when building or reviewing UI code.
+
+## Quick Reference
+
+| Category | When to Use |
+| --- | --- |
+| [Typography](typography.md) | Text wrapping, font smoothing, tabular numbers |
+| [Surfaces](surfaces.md) | Border radius, optical alignment, shadows, image outlines, hit areas |
+| [Animations](animations.md) | Interruptible animations, enter/exit transitions, icon animations, scale on press |
+| [Performance](performance.md) | Transition specificity, `will-change` usage |
+
+## Core Principles
+
+### 1. Concentric Border Radius
+
+Outer radius = inner radius + padding. Mismatched radii on nested elements is the most common thing that makes interfaces feel off.
+
+### 2. Optical Over Geometric Alignment
+
+When geometric centering looks off, align optically. Buttons with icons, play triangles, and asymmetric icons all need manual adjustment.
+
+### 3. Shadows Over Borders
+
+Layer multiple transparent `box-shadow` values for natural depth. Shadows adapt to any background; solid borders don't.
+
+### 4. Interruptible Animations
+
+Use CSS transitions for interactive state changes — they can be interrupted mid-animation. Reserve keyframes for staged sequences that run once.
+
+### 5. Split and Stagger Enter Animations
+
+Don't animate a single container. Break content into semantic chunks and stagger each with ~100ms delay.
+
+### 6. Subtle Exit Animations
+
+Use a small fixed `translateY` instead of full height. Exits should be softer than enters.
+
+### 7. Contextual Icon Animations
+
+Animate icons with `opacity`, `scale`, and `blur` instead of toggling visibility. Use exactly these values: scale from `0.25` to `1`, opacity from `0` to `1`, blur from `4px` to `0px`. If the project has `motion` or `framer-motion` in `package.json`, use `transition: { type: "spring", duration: 0.3, bounce: 0 }` — bounce must always be `0`. If no motion library is installed, keep both icons in the DOM (one absolute-positioned) and cross-fade with CSS transitions using `cubic-bezier(0.2, 0, 0, 1)` — this gives both enter and exit animations without any dependency.
+
+### 8. Font Smoothing
+
+Apply `-webkit-font-smoothing: antialiased` to the root layout on macOS for crisper text.
+
+### 9. Tabular Numbers
+
+Use `font-variant-numeric: tabular-nums` for any dynamically updating numbers to prevent layout shift.
+
+### 10. Text Wrapping
+
+Use `text-wrap: balance` on headings. Use `text-wrap: pretty` for body text to avoid orphans.
+
+### 11. Image Outlines
+
+Add a subtle `1px` outline with low opacity to images for consistent depth.
+
+### 12. Scale on Press
+
+A subtle `scale(0.96)` on click gives buttons tactile feedback. Always use `0.96`. Never use a value smaller than `0.95` — anything below feels exaggerated. Add a `static` prop to disable it when motion would be distracting.
+
+### 13. Skip Animation on Page Load
+
+Use `initial={false}` on `AnimatePresence` to prevent enter animations on first render. Verify it doesn't break intentional entrance animations.
+
+### 14. Never Use `transition: all`
+
+Always specify exact properties: `transition-property: scale, opacity`. Tailwind's `transition-transform` covers `transform, translate, scale, rotate`.
+
+### 15. Use `will-change` Sparingly
+
+Only for `transform`, `opacity`, `filter` — properties the GPU can composite. Never use `will-change: all`. Only add when you notice first-frame stutter.
+
+### 16. Minimum Hit Area
+
+Interactive elements need at least 40×40px hit area. Extend with a pseudo-element if the visible element is smaller. Never let hit areas of two elements overlap.
+
+## Common Mistakes
+
+| Mistake | Fix |
+| --- | --- |
+| Same border radius on parent and child | Calculate `outerRadius = innerRadius + padding` |
+| Icons look off-center | Adjust optically with padding or fix SVG directly |
+| Hard borders between sections | Use layered `box-shadow` with transparency |
+| Jarring enter/exit animations | Split, stagger, and keep exits subtle |
+| Numbers cause layout shift | Apply `tabular-nums` |
+| Heavy text on macOS | Apply `antialiased` to root |
+| Animation plays on page load | Add `initial={false}` to `AnimatePresence` |
+| `transition: all` on elements | Specify exact properties |
+| First-frame animation stutter | Add `will-change: transform` (sparingly) |
+| Tiny hit areas on small controls | Extend with pseudo-element to 40×40px |
+
+## Review Checklist
+
+- [ ] Nested rounded elements use concentric border radius
+- [ ] Icons are optically centered, not just geometrically
+- [ ] Shadows used instead of borders where appropriate
+- [ ] Enter animations are split and staggered
+- [ ] Exit animations are subtle
+- [ ] Dynamic numbers use tabular-nums
+- [ ] Font smoothing is applied
+- [ ] Headings use text-wrap: balance
+- [ ] Images have subtle outlines
+- [ ] Buttons use scale on press where appropriate
+- [ ] AnimatePresence uses `initial={false}` for default-state elements
+- [ ] No `transition: all` — only specific properties
+- [ ] `will-change` only on transform/opacity/filter, never `all`
+- [ ] Interactive elements have at least 40×40px hit area
+
+## Reference Files
+
+- [typography.md](typography.md) — Text wrapping, font smoothing, tabular numbers
+- [surfaces.md](surfaces.md) — Border radius, optical alignment, shadows, image outlines
+- [animations.md](animations.md) — Interruptible animations, enter/exit transitions, icon animations, scale on press
+- [performance.md](performance.md) — Transition specificity, `will-change` usage