refactor(skillbook): enforce ONE skill format, remove bundled option

BREAKING: Eliminate Format A/B decision tree. All skills use atomic format.

Changes:
- Update skillbook agent docs (claude, copilot-cli, vs-code-agents)
- Update shared template with simplified format section
- Delete skill-format-selection-decision-tree.md memory
- Remove entry from skills-documentation-index.md
- Create Validate-SkillFormat.ps1 script
- Add skill format enforcement to pre-commit hook

The new format requirement:
- ONE skill per file. No bundled skills. No exceptions.
- Pre-commit blocks new bundled-format skill files
- Legacy bundled files remain (non-blocking warning)

Strong opinion: Consistency over complexity. One format always.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: rjmurillo-bot

.githooks/pre-commit

@@ -683,6 +683,42 @@ else
     echo_info "No memory files staged. Skipping memory index validation."
 fi
 
+#
+# Skill Format Validation (BLOCKING for new files)
+#
+# Enforces ADR-017 atomic format: ONE skill per file. No bundled skills.
+# Blocks commits that add new bundled-format skill files.
+# Legacy bundled files are allowed (non-blocking warning only).
+#
+# Related: ADR-017, Issue #307
+#
+SKILL_FORMAT_SCRIPT="$REPO_ROOT/scripts/Validate-SkillFormat.ps1"
+
+if [ -n "$STAGED_MEMORY_FILES" ]; then
+    echo_info "Checking skill format (ADR-017: one skill per file)..."
+
+    # MEDIUM-002: Reject symlinks for security
+    if [ -L "$SKILL_FORMAT_SCRIPT" ]; then
+        echo_warning "Skipping skill format validation: script path is a symlink"
+    elif [ -f "$SKILL_FORMAT_SCRIPT" ]; then
+        if command -v pwsh &> /dev/null; then
+            # Run skill format validation on staged files only
+            # -StagedOnly checks only new/modified files (not legacy bundled files)
+            if ! pwsh -NoProfile -File "$SKILL_FORMAT_SCRIPT" -StagedOnly -CI 2>&1; then
+                echo_error "Skill format validation FAILED."
+                echo_info "  ADR-017 requires ONE skill per file. Split bundled skills."
+                EXIT_STATUS=1
+            else
+                echo_success "Skill format validation: PASS"
+            fi
+        else
+            echo_warning "PowerShell not available. Skipping skill format validation."
+        fi
+    else
+        echo_info "Skill format validation script not found. Skipping."
+    fi
+fi
+
 #
 # Final Summary
 #

.serena/memories/skill-format-selection-decision-tree.md

@@ -4,6 +4,5 @@
 | fallback tool call graceful degradation mcp serena | documentation-fallback-pattern |
 | user-facing content internal PR issue session exclude | documentation-user-facing |
 | self-contained artifact handoff agent amnesia autonomous | documentation-self-contained |
-| skill format standalone bundled decision tree mermaid P0 | skill-format-selection-decision-tree |
 | index selection domain routing keyword overlap create new | skill-index-selection-decision-tree |
 | verification critic amnesiac completeness objective PASS FAIL protocol | documentation-verification-protocol |

.serena/memories/skills-documentation-index.md

@@ -0,0 +1,107 @@
+<#
+.SYNOPSIS
+    Validates skill files follow the atomic format (one skill per file).
+
+.DESCRIPTION
+    Enforces ADR-017 skill format requirements:
+    - One skill per file (no bundled skills)
+    - Files with `## Skill-` headers are flagged as bundled format
+
+    This validation runs on staged .serena/memories/ files during pre-commit.
+
+.PARAMETER Path
+    Path to the memories directory. Defaults to .serena/memories/.
+
+.PARAMETER CI
+    Run in CI mode (stricter output, exit codes).
+
+.PARAMETER StagedOnly
+    Only check staged files (for pre-commit hook).
+
+.EXAMPLE
+    pwsh scripts/Validate-SkillFormat.ps1
+
+.EXAMPLE
+    pwsh scripts/Validate-SkillFormat.ps1 -StagedOnly
+
+.NOTES
+    Related: ADR-017, Issue #307
+#>
+[CmdletBinding()]
+param(
+    [string]$Path = ".serena/memories",
+    [switch]$CI,
+    [switch]$StagedOnly
+)
+
+$ErrorActionPreference = 'Stop'
+$script:ExitCode = 0
+$script:BundledFiles = @()
+
+# Get files to check
+if ($StagedOnly) {
+    # Get staged memory files from git
+    $stagedFiles = git diff --cached --name-only --diff-filter=ACMR 2>$null |
+        Where-Object { $_ -match '^\.serena/memories/.*\.md$' -and $_ -notmatch 'skills-.*-index\.md$' }
+
+    if (-not $stagedFiles) {
+        Write-Host "No skill files staged. Skipping format validation." -ForegroundColor Gray
+        exit 0
+    }
+
+    $filesToCheck = $stagedFiles | ForEach-Object { Get-Item $_ -ErrorAction SilentlyContinue }
+} else {
+    # Check all skill files (exclude index files)
+    $filesToCheck = Get-ChildItem -Path $Path -Filter "*.md" -ErrorAction SilentlyContinue |
+        Where-Object { $_.Name -notmatch '^skills-.*-index\.md$' -and $_.Name -ne 'memory-index.md' }
+}
+
+if (-not $filesToCheck) {
+    Write-Host "No skill files found to validate." -ForegroundColor Gray
+    exit 0
+}
+
+Write-Host "Validating skill format (ADR-017: one skill per file)..." -ForegroundColor Cyan
+
+foreach ($file in $filesToCheck) {
+    $content = Get-Content $file.FullName -Raw -ErrorAction SilentlyContinue
+    if (-not $content) { continue }
+
+    # Count skill headers (## Skill-*-NNN:)
+    $skillHeaders = [regex]::Matches($content, '(?m)^## Skill-[A-Za-z]+-[0-9]+:')
+
+    if ($skillHeaders.Count -gt 1) {
+        # Bundled format detected
+        Write-Host "  BUNDLED: $($file.Name) contains $($skillHeaders.Count) skills" -ForegroundColor Yellow
+        $script:BundledFiles += @{
+            File = $file.Name
+            Count = $skillHeaders.Count
+        }
+        $script:ExitCode = 1
+    }
+}
+
+# Summary
+Write-Host ""
+if ($script:BundledFiles.Count -gt 0) {
+    Write-Host "=== Bundled Format Detected ===" -ForegroundColor Yellow
+    Write-Host "The following files contain multiple skills:" -ForegroundColor Yellow
+    $script:BundledFiles | ForEach-Object {
+        Write-Host "  - $($_.File): $($_.Count) skills" -ForegroundColor Yellow
+    }
+    Write-Host ""
+    Write-Host "ADR-017 requires ONE skill per file. No exceptions." -ForegroundColor Red
+    Write-Host "Split bundled skills into separate atomic files." -ForegroundColor Red
+    Write-Host ""
+
+    if ($CI) {
+        Write-Host "Result: FAILED" -ForegroundColor Red
+        exit 1
+    } else {
+        Write-Host "Result: WARNING (non-blocking for legacy files)" -ForegroundColor Yellow
+        exit 0
+    }
+} else {
+    Write-Host "Result: PASSED - All skill files are atomic format" -ForegroundColor Green
+    exit 0
+}

scripts/Validate-SkillFormat.ps1

@@ -169,13 +169,11 @@ Correct format (maximum token efficiency):
 | `skills-{domain}-index.md` | L2 routing table | `skills-pr-review-index.md` |
 | `{domain}-{topic}.md` | L3 atomic content | `pr-review-security.md` |
 
-## Skill File Formats (ADR-017)
+## Skill File Format (ADR-017)
 
-Skills are stored as markdown files in `.serena/memories/`. Two canonical formats exist:
+**ONE format. ALWAYS consistent. No exceptions.**
 
-### Format A: Standalone Skill (Major Skills)
-
-Use for skills that are referenced independently or represent major capabilities.
+Skills are stored as atomic markdown files in `.serena/memories/`. Every skill uses this format:
 
 ```markdown
 # Skill-{Category}-{NNN}: {Title}
@@ -194,14 +192,11 @@ Use for skills that are referenced independently or represent major capabilities
 
 ## Anti-Pattern
 
-{What NOT to do}
-
-## Related
-
-- **BLOCKS**: {Skills this blocks}
-- **ENABLES**: {Skills this enables}
+{What NOT to do - optional, include only if there's a common mistake}
 ```
 
+**One skill per file.** No bundling. No decision trees. No exceptions.
+
 **Example** (from `session-init-serena.md`):
 
 ```markdown
@@ -221,102 +216,11 @@ Use for skills that are referenced independently or represent major capabilities
 3. Proceed with work
 ```
 
-### Format B: Bundled Skills (Related Workflows)
-
-Use for multiple related skills that share a workflow context.
-
-```markdown
-# {Domain}: {Topic Title}
-
-## Skill-{Category}-{NNN}: {First Skill Title}
-
-**Statement**: {Atomic strategy}
-
-**Atomicity**: {%} | **Impact**: {1-10}
-
-{Code example}
-
-## Skill-{Category}-{NNN}: {Second Skill Title}
-
-**Statement**: {Atomic strategy}
-
-**Atomicity**: {%} | **Impact**: {1-10}
-
-{Code example}
-```
-
-**Example** (from `pr-review-acknowledgment.md`):
-
-```markdown
-# PR Review: Acknowledgment Protocol
-
-## Skill-PR-Comment-001: Acknowledgment BLOCKING Gate
-
-**Statement**: Phase 3 BLOCKED until eyes count equals comment count.
-
-**Atomicity**: 100% | **Tag**: critical
-
-## Skill-PR-Comment-002: Session-Specific Work Tracking
-
-**Statement**: Track 'NEW this session' separately from 'DONE prior'.
-
-**Atomicity**: 100% | **Tag**: critical
-```
-
-### Format Selection Decision Tree
-
-```mermaid
-flowchart TD
-    START([New Skill]) --> Q1{CRITICAL/BLOCKING?<br/>See criteria below}
-    Q1 -->|YES| A1[Format A<br/>Standalone]
-    Q1 -->|NO| Q2{2+ related skills<br/>same workflow?}
-    Q2 -->|YES| B1[Format B<br/>Bundled]
-    Q2 -->|NO| Q3{Has BLOCKS/ENABLES<br/>relationships?}
-    Q3 -->|YES| A2[Format A<br/>Standalone]
-    Q3 -->|NO| EITHER[Either Format<br/>Acceptable]
-
-    A1 --> DONE([Create File])
-    A2 --> DONE
-    B1 --> DONE
-    EITHER --> DONE
-```
-
-**CRITICAL/BLOCKING Definition** (any one triggers Format A):
-
-- Impact score >= 9
-- Blocks a protocol gate (SESSION-PROTOCOL.md)
-- Tagged with `#P0` or `#BLOCKING`
-- Referenced in `.agents/SESSION-PROTOCOL.md`
-
-**"Has BLOCKS/ENABLES relationships"**: Skill will be cited in other skills' Related sections.
-
-### Index Selection Decision Tree
-
-```mermaid
-flowchart TD
-    START([New Skill]) --> Q1{Skill topic matches<br/>existing domain index?}
-    Q1 -->|YES| ADD[Add to existing<br/>skills-DOMAIN-index.md]
-    Q1 -->|NO| Q2{5+ skills expected<br/>in this topic area?}
-    Q2 -->|YES| CREATE[Create new<br/>skills-DOMAIN-index.md]
-    Q2 -->|NO| Q3{Closest related<br/>domain?}
-    Q3 --> RELATED[Add to related<br/>domain index]
-
-    ADD --> UPDATE[Update memory-index.md<br/>if new keywords]
-    CREATE --> UPDATE
-    RELATED --> UPDATE
-```
-
-**Index Selection Rules:**
-
-1. **Match existing domain**: Check `memory-index.md` keywords. If skill keywords overlap >50% with existing domain, add there.
-2. **Create new domain**: Only if 5+ skills expected AND no existing domain covers topic.
-3. **Fallback to related**: If <5 skills expected, add to closest related domain.
-
-**Example decisions:**
+### Index Selection
 
-- Skill about PR security → `skills-pr-review-index.md` (PR workflow context)
-- Skill about skill formatting → `skills-documentation-index.md` (documentation context)
-- Skill about Pester mocking → `skills-pester-testing-index.md` (testing context)
+1. Check `memory-index.md` for matching domain keywords
+2. Add skill to existing domain index if keywords overlap >50%
+3. Create new domain index only if 5+ skills exist AND no domain covers topic
 
 ### Activation Vocabulary Rules