bps-kit 1.0.2 → 1.0.4

package/templates/skills_normal/plan-writing/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: plan-writing
-description: Structured task planning with clear breakdowns, dependencies, and verification criteria. Use when implementing features, refactoring, or any multi-step work.
-allowed-tools: Read, Glob, Grep
+description: "Structured task planning with clear breakdowns, dependencies, and verification criteria. Use when implementing features, refactoring, or any multi-step work."
+risk: unknown
+source: community
+date_added: "2026-02-27"
 ---
 
 # Plan Writing

package/templates/skills_normal/seo-fundamentals/SKILL.md

@@ -1,129 +1,175 @@
 ---
 name: seo-fundamentals
-description: SEO fundamentals, E-E-A-T, Core Web Vitals, and Google algorithm principles.
-allowed-tools: Read, Glob, Grep
+description: Core principles of SEO including E-E-A-T, Core Web Vitals, technical foundations, content quality, and how modern search engines evaluate pages.
+risk: unknown
+source: community
+date_added: '2026-02-27'
+---
+
 ---
 
 # SEO Fundamentals
 
-> Principles for search engine visibility.
+> **Foundational principles for sustainable search visibility.**
+> This skill explains _how search engines evaluate quality_, not tactical shortcuts.
 
 ---
 
-## 1. E-E-A-T Framework
+## 1. E-E-A-T (Quality Evaluation Framework)
+
+E-E-A-T is **not a direct ranking factor**.
+It is a framework used by search engines to **evaluate content quality**, especially for sensitive or high-impact topics.
 
-| Principle | Signals |
-|-----------|---------|
-| **Experience** | First-hand knowledge, real examples |
-| **Expertise** | Credentials, depth of knowledge |
-| **Authoritativeness** | Backlinks, mentions, industry recognition |
-| **Trustworthiness** | HTTPS, transparency, accurate info |
+| Dimension             | What It Represents                 | Common Signals                                      |
+| --------------------- | ---------------------------------- | --------------------------------------------------- |
+| **Experience**        | First-hand, real-world involvement | Original examples, lived experience, demonstrations |
+| **Expertise**         | Subject-matter competence          | Credentials, depth, accuracy                        |
+| **Authoritativeness** | Recognition by others              | Mentions, citations, links                          |
+| **Trustworthiness**   | Reliability and safety             | HTTPS, transparency, accuracy                       |
+
+> Pages competing in the same space are often differentiated by **trust and experience**, not keywords.
 
 ---
 
-## 2. Core Web Vitals
+## 2. Core Web Vitals (Page Experience Signals)
+
+Core Web Vitals measure **how users experience a page**, not whether it deserves to rank.
 
-| Metric | Target | Measures |
-|--------|--------|----------|
-| **LCP** | < 2.5s | Loading performance |
-| **INP** | < 200ms | Interactivity |
-| **CLS** | < 0.1 | Visual stability |
+| Metric  | Target  | What It Reflects    |
+| ------- | ------- | ------------------- |
+| **LCP** | < 2.5s  | Loading performance |
+| **INP** | < 200ms | Interactivity       |
+| **CLS** | < 0.1   | Visual stability    |
+
+**Important context:**
+
+- CWV rarely override poor content
+- They matter most when content quality is comparable
+- Failing CWV can _hold back_ otherwise good pages
 
 ---
 
 ## 3. Technical SEO Principles
 
-### Site Structure
+Technical SEO ensures pages are **accessible, understandable, and stable**.
 
-| Element | Purpose |
-|---------|---------|
-| XML sitemap | Help crawling |
-| robots.txt | Control access |
-| Canonical tags | Prevent duplicates |
-| HTTPS | Security signal |
+### Crawl & Index Control
 
-### Performance
+| Element           | Purpose                |
+| ----------------- | ---------------------- |
+| XML sitemaps      | Help discovery         |
+| robots.txt        | Control crawl access   |
+| Canonical tags    | Consolidate duplicates |
+| HTTP status codes | Communicate page state |
+| HTTPS             | Security and trust     |
 
-| Factor | Impact |
-|--------|--------|
-| Page speed | Core Web Vital |
-| Mobile-friendly | Ranking factor |
-| Clean URLs | Crawlability |
+### Performance & Accessibility
+
+| Factor                 | Why It Matters                |
+| ---------------------- | ----------------------------- |
+| Page speed             | User satisfaction             |
+| Mobile-friendly design | Mobile-first indexing         |
+| Clean URLs             | Crawl clarity                 |
+| Semantic HTML          | Accessibility & understanding |
 
 ---
 
 ## 4. Content SEO Principles
 
-### Page Elements
+### Page-Level Elements
 
-| Element | Best Practice |
-|---------|---------------|
-| Title tag | 50-60 chars, keyword front |
-| Meta description | 150-160 chars, compelling |
-| H1 | One per page, main keyword |
-| H2-H6 | Logical hierarchy |
-| Alt text | Descriptive, not stuffed |
+| Element          | Principle                    |
+| ---------------- | ---------------------------- |
+| Title tag        | Clear topic + intent         |
+| Meta description | Click relevance, not ranking |
+| H1               | Page’s primary subject       |
+| Headings         | Logical structure            |
+| Alt text         | Accessibility and context    |
 
-### Content Quality
+### Content Quality Signals
 
-| Factor | Importance |
-|--------|------------|
-| Depth | Comprehensive coverage |
-| Freshness | Regular updates |
-| Uniqueness | Original value |
-| Readability | Clear writing |
+| Dimension   | What Search Engines Look For |
+| ----------- | ---------------------------- |
+| Depth       | Fully answers the query      |
+| Originality | Adds unique value            |
+| Accuracy    | Factually correct            |
+| Clarity     | Easy to understand           |
+| Usefulness  | Satisfies intent             |
 
 ---
 
-## 5. Schema Markup Types
+## 5. Structured Data (Schema)
+
+Structured data helps search engines **understand meaning**, not boost rankings directly.
 
-| Type | Use |
-|------|-----|
-| Article | Blog posts, news |
-| Organization | Company info |
-| Person | Author profiles |
-| FAQPage | Q&A content |
-| Product | E-commerce |
-| Review | Ratings |
-| BreadcrumbList | Navigation |
+| Type           | Purpose                |
+| -------------- | ---------------------- |
+| Article        | Content classification |
+| Organization   | Entity identity        |
+| Person         | Author information     |
+| FAQPage        | Q&A clarity            |
+| Product        | Commerce details       |
+| Review         | Ratings context        |
+| BreadcrumbList | Site structure         |
+
+> Schema enables eligibility for rich results but does not guarantee them.
 
 ---
 
-## 6. AI Content Guidelines
+## 6. AI-Assisted Content Principles
+
+Search engines evaluate **output quality**, not authorship method.
+
+### Effective Use
+
+- AI as a drafting or research assistant
+- Human review for accuracy and clarity
+- Original insights and synthesis
+- Clear accountability
 
-### What Google Looks For
+### Risky Use
 
-| ✅ Do | ❌ Don't |
-|-------|----------|
-| AI draft + human edit | Publish raw AI content |
-| Add original insights | Copy without value |
-| Expert review | Skip fact-checking |
-| Follow E-E-A-T | Keyword stuffing |
+- Publishing unedited AI output
+- Factual errors or hallucinations
+- Thin or duplicated content
+- Keyword-driven text with no value
 
 ---
 
-## 7. Ranking Factors (Prioritized)
+## 7. Relative Importance of SEO Factors
 
-| Priority | Factor |
-|----------|--------|
-| 1 | Quality, relevant content |
-| 2 | Backlinks from authority sites |
-| 3 | Page experience (Core Web Vitals) |
-| 4 | Mobile optimization |
-| 5 | Technical SEO fundamentals |
+There is **no fixed ranking factor order**.
+However, when competing pages are similar, importance tends to follow this pattern:
+
+| Relative Weight | Factor                      |
+| --------------- | --------------------------- |
+| Highest         | Content relevance & quality |
+| High            | Authority & trust signals   |
+| Medium          | Page experience (CWV, UX)   |
+| Medium          | Mobile optimization         |
+| Baseline        | Technical accessibility     |
+
+> Technical SEO enables ranking; content quality earns it.
 
 ---
 
-## 8. Measurement
+## 8. Measurement & Evaluation
 
-| Metric | Tool |
-|--------|------|
-| Rankings | Search Console, Ahrefs |
-| Traffic | Analytics |
-| Core Web Vitals | PageSpeed Insights |
-| Indexing | Search Console |
-| Backlinks | Ahrefs, Semrush |
+SEO fundamentals should be validated using **multiple signals**, not single metrics.
+
+| Area        | What to Observe            |
+| ----------- | -------------------------- |
+| Visibility  | Indexed pages, impressions |
+| Engagement  | Click-through, dwell time  |
+| Performance | CWV field data             |
+| Coverage    | Indexing status            |
+| Authority   | Mentions and links         |
 
 ---
 
-> **Remember:** SEO is a long-term game. Quality content + technical excellence + patience = results.
+> **Key Principle:**
+> Sustainable SEO is built on _useful content_, _technical clarity_, and _trust over time_.
+> There are no permanent shortcuts.
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/templates/skills_normal/systematic-debugging/CREATION-LOG.md

@@ -0,0 +1,119 @@
+# Creation Log: Systematic Debugging Skill
+
+Reference example of extracting, structuring, and bulletproofing a critical skill.
+
+## Source Material
+
+Extracted debugging framework from `/Users/jesse/.claude/CLAUDE.md`:
+- 4-phase systematic process (Investigation → Pattern Analysis → Hypothesis → Implementation)
+- Core mandate: ALWAYS find root cause, NEVER fix symptoms
+- Rules designed to resist time pressure and rationalization
+
+## Extraction Decisions
+
+**What to include:**
+- Complete 4-phase framework with all rules
+- Anti-shortcuts ("NEVER fix symptom", "STOP and re-analyze")
+- Pressure-resistant language ("even if faster", "even if I seem in a hurry")
+- Concrete steps for each phase
+
+**What to leave out:**
+- Project-specific context
+- Repetitive variations of same rule
+- Narrative explanations (condensed to principles)
+
+## Structure Following skill-creation/SKILL.md
+
+1. **Rich when_to_use** - Included symptoms and anti-patterns
+2. **Type: technique** - Concrete process with steps
+3. **Keywords** - "root cause", "symptom", "workaround", "debugging", "investigation"
+4. **Flowchart** - Decision point for "fix failed" → re-analyze vs add more fixes
+5. **Phase-by-phase breakdown** - Scannable checklist format
+6. **Anti-patterns section** - What NOT to do (critical for this skill)
+
+## Bulletproofing Elements
+
+Framework designed to resist rationalization under pressure:
+
+### Language Choices
+- "ALWAYS" / "NEVER" (not "should" / "try to")
+- "even if faster" / "even if I seem in a hurry"
+- "STOP and re-analyze" (explicit pause)
+- "Don't skip past" (catches the actual behavior)
+
+### Structural Defenses
+- **Phase 1 required** - Can't skip to implementation
+- **Single hypothesis rule** - Forces thinking, prevents shotgun fixes
+- **Explicit failure mode** - "IF your first fix doesn't work" with mandatory action
+- **Anti-patterns section** - Shows exactly what shortcuts look like
+
+### Redundancy
+- Root cause mandate in overview + when_to_use + Phase 1 + implementation rules
+- "NEVER fix symptom" appears 4 times in different contexts
+- Each phase has explicit "don't skip" guidance
+
+## Testing Approach
+
+Created 4 validation tests following skills/meta/testing-skills-with-subagents:
+
+### Test 1: Academic Context (No Pressure)
+- Simple bug, no time pressure
+- **Result:** Perfect compliance, complete investigation
+
+### Test 2: Time Pressure + Obvious Quick Fix
+- User "in a hurry", symptom fix looks easy
+- **Result:** Resisted shortcut, followed full process, found real root cause
+
+### Test 3: Complex System + Uncertainty
+- Multi-layer failure, unclear if can find root cause
+- **Result:** Systematic investigation, traced through all layers, found source
+
+### Test 4: Failed First Fix
+- Hypothesis doesn't work, temptation to add more fixes
+- **Result:** Stopped, re-analyzed, formed new hypothesis (no shotgun)
+
+**All tests passed.** No rationalizations found.
+
+## Iterations
+
+### Initial Version
+- Complete 4-phase framework
+- Anti-patterns section
+- Flowchart for "fix failed" decision
+
+### Enhancement 1: TDD Reference
+- Added link to skills/testing/test-driven-development
+- Note explaining TDD's "simplest code" ≠ debugging's "root cause"
+- Prevents confusion between methodologies
+
+## Final Outcome
+
+Bulletproof skill that:
+- ✅ Clearly mandates root cause investigation
+- ✅ Resists time pressure rationalization
+- ✅ Provides concrete steps for each phase
+- ✅ Shows anti-patterns explicitly
+- ✅ Tested under multiple pressure scenarios
+- ✅ Clarifies relationship to TDD
+- ✅ Ready for use
+
+## Key Insight
+
+**Most important bulletproofing:** Anti-patterns section showing exact shortcuts that feel justified in the moment. When Claude thinks "I'll just add this one quick fix", seeing that exact pattern listed as wrong creates cognitive friction.
+
+## Usage Example
+
+When encountering a bug:
+1. Load skill: skills/debugging/systematic-debugging
+2. Read overview (10 sec) - reminded of mandate
+3. Follow Phase 1 checklist - forced investigation
+4. If tempted to skip - see anti-pattern, stop
+5. Complete all phases - root cause found
+
+**Time investment:** 5-10 minutes
+**Time saved:** Hours of symptom-whack-a-mole
+
+---
+
+*Created: 2025-10-03*
+*Purpose: Reference example for skill extraction and bulletproofing*