@chankov/agent-skills 0.1.0

package/docs/skill-anatomy.md

@@ -0,0 +1,129 @@
+# Skill Anatomy
+
+This document describes the structure and format of agent-skills skill files. Use this as a guide when contributing new skills or understanding existing ones.
+
+## File Location
+
+Every skill lives in its own directory under `skills/`:
+
+```
+skills/
+  skill-name/
+    SKILL.md          # Required: The skill definition
+    supporting-file.md # Optional: Reference material loaded on demand
+```
+
+## SKILL.md Format
+
+### Frontmatter (Required)
+
+```yaml
+---
+name: skill-name-with-hyphens
+description: Brief statement of what the skill does. Use when [specific trigger conditions].
+---
+```
+
+**Rules:**
+- `name`: Lowercase, hyphen-separated. Must match the directory name.
+- `description`: Starts with what the skill does (third person), followed by trigger conditions. Include both *what* and *when*. Maximum 1024 characters.
+
+**Why this matters:** Agents discover skills by reading descriptions. The description is injected into the system prompt, so it must tell the agent both what the skill provides and when to activate it. Do not summarize the workflow — if the description contains process steps, the agent may follow the summary instead of reading the full skill.
+
+### Standard Sections
+
+```markdown
+# Skill Title
+
+## Overview
+One-two sentences explaining what this skill does and why it matters.
+
+## When to Use
+- Bullet list of triggering conditions (symptoms, task types)
+- When NOT to use (exclusions)
+
+## [Core Process / The Workflow / Steps]
+The main workflow, broken into numbered steps or phases.
+Include code examples where they help.
+Use flowcharts (ASCII) where decision points exist.
+
+## [Specific Techniques / Patterns]
+Detailed guidance for specific scenarios.
+Code examples, templates, configuration.
+
+## Common Rationalizations
+| Rationalization | Reality |
+|---|---|
+| Excuse agents use to skip steps | Why the excuse is wrong |
+
+## Red Flags
+- Behavioral patterns indicating the skill is being violated
+- Things to watch for during review
+
+## Verification
+After completing the skill's process, confirm:
+- [ ] Checklist of exit criteria
+- [ ] Evidence requirements
+```
+
+## Section Purposes
+
+### Overview
+The "elevator pitch" for the skill. Should answer: What does this skill do, and why should an agent follow it?
+
+### When to Use
+Helps agents and humans decide if this skill applies to the current task. Include both positive triggers ("Use when X") and negative exclusions ("NOT for Y").
+
+### Core Process
+The heart of the skill. This is the step-by-step workflow the agent follows. Must be specific and actionable — not vague advice.
+
+**Good:** "Run `npm test` and verify all tests pass"
+**Bad:** "Make sure the tests work"
+
+### Common Rationalizations
+The most distinctive feature of well-crafted skills. These are excuses agents use to skip important steps, paired with rebuttals. They prevent the agent from rationalizing its way out of following the process.
+
+Think of every time an agent has said "I'll add tests later" or "This is simple enough to skip the spec" — those go here with a factual counter-argument.
+
+### Red Flags
+Observable signs that the skill is being violated. Useful during code review and self-monitoring.
+
+### Verification
+The exit criteria. A checklist the agent uses to confirm the skill's process is complete. Every checkbox should be verifiable with evidence (test output, build result, screenshot, etc.).
+
+## Supporting Files
+
+Create supporting files only when:
+- Reference material exceeds 100 lines (keep the main SKILL.md focused)
+- Code tools or scripts are needed
+- Checklists are long enough to justify separate files
+
+Keep patterns and principles inline when under 50 lines.
+
+## Writing Principles
+
+1. **Process over knowledge.** Skills are workflows, not reference docs. Steps, not facts.
+2. **Specific over general.** "Run `npm test`" beats "verify the tests".
+3. **Evidence over assumption.** Every verification checkbox requires proof.
+4. **Anti-rationalization.** Every skip-worthy step needs a counter-argument in the rationalizations table.
+5. **Progressive disclosure.** Main SKILL.md is the entry point. Supporting files are loaded only when needed.
+6. **Token-conscious.** Every section must justify its inclusion. If removing it wouldn't change agent behavior, remove it.
+7. **Prompting-patterns applied.** Before finalizing a skill, verify its language against `references/prompting-patterns.md` — positive instructions over prohibitions, explain *why* behind non-obvious rules, no ALL-CAPS or reward/punishment language.
+
+## Naming Conventions
+
+- Skill directories: `lowercase-hyphen-separated`
+- Skill files: `SKILL.md` (always uppercase)
+- Supporting files: `lowercase-hyphen-separated.md`
+- References: stored in `references/` at the project root, not inside skill directories
+
+## Cross-Skill References
+
+Reference other skills by name:
+
+```markdown
+Follow the `test-driven-development` skill for writing tests.
+If the build breaks, use the `debugging-and-error-recovery` skill.
+```
+
+Don't duplicate content between skills — reference and link instead.

package/docs/windsurf-setup.md

@@ -0,0 +1,48 @@
+# Using agent-skills with Windsurf
+
+## Setup
+
+### Project Rules
+
+Windsurf uses `.windsurfrules` for project-specific agent instructions:
+
+```bash
+# Create a combined rules file from your most important skills
+cat /path/to/agent-skills/skills/test-driven-development/SKILL.md > .windsurfrules
+echo "\n---\n" >> .windsurfrules
+cat /path/to/agent-skills/skills/incremental-implementation/SKILL.md >> .windsurfrules
+echo "\n---\n" >> .windsurfrules
+cat /path/to/agent-skills/skills/code-review-and-quality/SKILL.md >> .windsurfrules
+```
+
+### Global Rules
+
+For skills you want across all projects, add them to Windsurf's global rules:
+
+1. Open Windsurf → Settings → AI → Global Rules
+2. Paste the content of your most-used skills
+
+## Recommended Configuration
+
+Keep `.windsurfrules` focused on 2-3 essential skills to stay within context limits:
+
+```
+# .windsurfrules
+# Essential agent-skills for this project
+
+[Paste test-driven-development SKILL.md]
+
+---
+
+[Paste incremental-implementation SKILL.md]
+
+---
+
+[Paste code-review-and-quality SKILL.md]
+```
+
+## Usage Tips
+
+1. **Be selective** — Windsurf's context is limited. Choose skills that address your biggest quality gaps.
+2. **Reference in conversation** — Paste additional skill content into the chat when working on specific phases (e.g., paste `security-and-hardening` when building auth).
+3. **Use references as checklists** — Paste `references/security-checklist.md` and ask Windsurf to verify each item.

package/hooks/SIMPLIFY-IGNORE.md

@@ -0,0 +1,90 @@
+# simplify-ignore hook
+
+Block-level protection for `/code-simplify`. Mark code that should never be simplified — the model won't see it.
+
+## Setup
+
+1. Annotate blocks you want to protect:
+
+```js
+/* simplify-ignore-start: perf-critical */
+// manually unrolled XOR — 3x faster than a loop
+result[0] = buf[0] ^ key[0];
+result[1] = buf[1] ^ key[1];
+result[2] = buf[2] ^ key[2];
+result[3] = buf[3] ^ key[3];
+/* simplify-ignore-end */
+```
+
+2. Add hooks to `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [{ "type": "command", "command": "bash ${CLAUDE_PROJECT_DIR}/hooks/simplify-ignore.sh" }]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [{ "type": "command", "command": "bash ${CLAUDE_PROJECT_DIR}/hooks/simplify-ignore.sh" }]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [{ "type": "command", "command": "bash ${CLAUDE_PROJECT_DIR}/hooks/simplify-ignore.sh" }]
+      }
+    ]
+  }
+}
+```
+
+3. Run `/code-simplify` — protected blocks become `/* BLOCK_de115a1d: perf-critical */` placeholders. The model reasons about surrounding code without seeing the protected implementation.
+
+> **Note:** The hook stores temporary backups in `.claude/.simplify-ignore-cache/`. Make sure this path is in your `.gitignore`.
+
+## How it works
+
+One script, three hook events:
+
+| Event | Action |
+|---|---|
+| `PreToolUse Read` | Backs up file, replaces blocks with `BLOCK_<hash>` placeholders in-place |
+| `PostToolUse Edit\|Write` | Expands placeholders back to real code, saves model's changes, re-filters |
+| `Stop` | Restores all files from backup when session ends |
+
+Each block is content-hashed (8 hex chars via `shasum`/`sha1sum`) so the round-trip is unambiguous even if the model duplicates or reorders placeholders. Cache is project-scoped to prevent cross-session interference.
+
+## Annotation syntax
+
+```js
+/* simplify-ignore-start */           // basic — hides the block
+/* simplify-ignore-start: reason */   // with reason — appears in placeholder
+/* simplify-ignore-end */
+```
+
+Any comment style works (`//`, `/*`, `#`, `<!--`). Multiple blocks per file and single-line blocks supported. Placeholders preserve the original comment syntax (e.g. `# BLOCK_xxx` for Python, `<!-- BLOCK_xxx -->` for HTML).
+
+## Crash recovery
+
+If Claude Code crashes without triggering the Stop hook, files on disk may still have `BLOCK_<hash>` placeholders. To restore manually:
+
+```bash
+echo '{}' | bash hooks/simplify-ignore.sh
+```
+
+Backups are stored in `.claude/.simplify-ignore-cache/` within your project directory.
+
+## Known limitations
+
+- **Single-line blocks hide the entire line.** If `simplify-ignore-start` and `simplify-ignore-end` appear on the same line as other code, the whole line is hidden from the model, not just the annotated portion. Use dedicated lines for annotations.
+- **Comment suffix detection covers `*/` and `-->` only.** Template engines with non-standard comment closers (ERB `%>`, Blade `--}}`) may produce unbalanced placeholders. Use `#` or `//` style comments instead.
+- **Fallback expansion is progressive, not exact.** If the model alters a placeholder's formatting (e.g. changes the reason text), the hook tries progressively simpler matches: full placeholder → prefix+hash+suffix → hash-only. The hash-only fallback may leave cosmetic debris (e.g. stray `:` or reason text). A warning is printed to stderr when this happens.
+- **File renaming leaves placeholders.** If the model renames or moves a file via a shell command, the new file will retain `BLOCK_<hash>` placeholders. The original code is saved as `<old-filename>.recovered` when the session stops. You must manually restore the recovered code into the new file.
+
+## Requirements
+
+- `jq`, `shasum` or `sha1sum` (auto-detected), Bash 3.2+

package/hooks/hooks.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/session-start.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+# agent-skills session start hook
+# Injects the using-agent-skills meta-skill into every new session
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SKILLS_DIR="$(dirname "$SCRIPT_DIR")/skills"
+META_SKILL="$SKILLS_DIR/using-agent-skills/SKILL.md"
+
+if [ -f "$META_SKILL" ]; then
+  CONTENT=$(cat "$META_SKILL")
+  # Output as JSON for Claude Code hook consumption
+  cat <<EOF
+{
+  "priority": "IMPORTANT",
+  "message": "agent-skills loaded. Use the skill discovery flowchart to find the right skill for your task.\n\n$CONTENT"
+}
+EOF
+else
+  echo '{"priority": "INFO", "message": "agent-skills: using-agent-skills meta-skill not found. Skills may still be available individually."}'
+fi

package/hooks/simplify-ignore-test.sh

@@ -0,0 +1,247 @@
+#!/bin/bash
+# simplify-ignore-test.sh — Tests for the simplify-ignore hook
+#
+# Exercises filter_file by extracting function definitions from the hook.
+# Run: bash hooks/simplify-ignore-test.sh
+
+set -euo pipefail
+
+PASS=0 FAIL=0
+TMPDIR=$(mktemp -d)
+trap 'rm -rf "$TMPDIR"' EXIT
+
+export CACHE="$TMPDIR/cache"
+mkdir -p "$CACHE"
+
+# Extract function definitions we need
+hash_cmd() {
+  if command -v shasum >/dev/null 2>&1; then shasum
+  elif command -v sha1sum >/dev/null 2>&1; then sha1sum
+  else printf '%s\n' "error: missing shasum or sha1sum" >&2; exit 1; fi
+}
+file_id() { printf '%s' "$1" | hash_cmd | cut -c1-16; }
+block_hash() { printf '%s' "$1" | hash_cmd | cut -c1-8; }
+escape_glob() {
+  local s="$1"
+  s="${s//\\/\\\\}"
+  s="${s//\*/\\*}"
+  s="${s//\?/\\?}"
+  s="${s//\[/\\[}"
+  printf '%s' "$s"
+}
+
+# Extract filter_file from the hook script (line 59 "filter_file()" to line 142 closing brace)
+eval "$(sed -n '/^filter_file()/,/^}/p' hooks/simplify-ignore.sh)"
+
+assert_eq() {
+  local label="$1" expected="$2" actual="$3"
+  if [ "$expected" = "$actual" ]; then
+    PASS=$((PASS + 1))
+    printf '  PASS: %s\n' "$label"
+  else
+    FAIL=$((FAIL + 1))
+    printf '  FAIL: %s\n' "$label" >&2
+    printf '    expected: %s\n' "$(printf '%s' "$expected" | cat -v)" >&2
+    printf '    actual:   %s\n' "$(printf '%s' "$actual" | cat -v)" >&2
+  fi
+}
+
+# ── Test 1: Single-line block produces exactly one placeholder ────────────
+printf 'Test 1: Single-line block (start+end on same line)\n'
+rm -f "$CACHE"/*
+
+SRC="$TMPDIR/single-line.js"
+DEST="$TMPDIR/single-line-filtered.js"
+cat > "$SRC" <<'EOF'
+const a = 1;
+/* simplify-ignore-start */ const secret = 42; /* simplify-ignore-end */
+const b = 2;
+EOF
+
+FID="test_single"
+filter_file "$SRC" "$DEST" "$FID"
+
+placeholder_count=$(grep -c 'BLOCK_' "$DEST")
+assert_eq "exactly one placeholder line" "1" "$placeholder_count"
+assert_eq "line before block preserved" "1" "$(grep -c 'const a = 1' "$DEST")"
+assert_eq "line after block preserved" "1" "$(grep -c 'const b = 2' "$DEST")"
+
+block_files=$(ls "$CACHE/${FID}".block.* 2>/dev/null | wc -l | tr -d ' ')
+assert_eq "one block file in cache" "1" "$block_files"
+
+block_content=$(cat "$CACHE/${FID}".block.*)
+assert_eq "block content matches" \
+  "/* simplify-ignore-start */ const secret = 42; /* simplify-ignore-end */" \
+  "$block_content"
+
+# ── Test 2: Multi-line block ─────────────────────────────────────────────
+printf '\nTest 2: Multi-line block\n'
+rm -f "$CACHE"/*
+
+SRC="$TMPDIR/multi-line.js"
+DEST="$TMPDIR/multi-line-filtered.js"
+cat > "$SRC" <<'EOF'
+const a = 1;
+// simplify-ignore-start
+const secret1 = 42;
+const secret2 = 99;
+// simplify-ignore-end
+const b = 2;
+EOF
+
+FID="test_multi"
+filter_file "$SRC" "$DEST" "$FID"
+
+placeholder_count=$(grep -c 'BLOCK_' "$DEST")
+assert_eq "exactly one placeholder for multi-line block" "1" "$placeholder_count"
+
+output_lines=$(wc -l < "$DEST" | tr -d ' ')
+assert_eq "output has 3 lines (before + placeholder + after)" "3" "$output_lines"
+
+# ── Test 3: Multiple blocks in one file ──────────────────────────────────
+printf '\nTest 3: Multiple blocks in one file\n'
+rm -f "$CACHE"/*
+
+SRC="$TMPDIR/multi-block.js"
+DEST="$TMPDIR/multi-block-filtered.js"
+cat > "$SRC" <<'EOF'
+line1
+// simplify-ignore-start
+blockA
+// simplify-ignore-end
+line2
+// simplify-ignore-start
+blockB
+// simplify-ignore-end
+line3
+EOF
+
+FID="test_multiblock"
+filter_file "$SRC" "$DEST" "$FID"
+
+placeholder_count=$(grep -c 'BLOCK_' "$DEST")
+assert_eq "two placeholders for two blocks" "2" "$placeholder_count"
+
+block_files=$(ls "$CACHE/${FID}".block.* 2>/dev/null | wc -l | tr -d ' ')
+assert_eq "two block files in cache" "2" "$block_files"
+
+# ── Test 4: Reason string preserved ──────────────────────────────────────
+printf '\nTest 4: Reason string in placeholder\n'
+rm -f "$CACHE"/*
+
+SRC="$TMPDIR/reason.js"
+DEST="$TMPDIR/reason-filtered.js"
+cat > "$SRC" <<'EOF'
+// simplify-ignore-start: perf-critical
+hot_loop();
+// simplify-ignore-end
+EOF
+
+FID="test_reason"
+filter_file "$SRC" "$DEST" "$FID"
+
+assert_eq "placeholder includes reason" "1" "$(grep -c 'perf-critical' "$DEST")"
+
+reason_files=$(ls "$CACHE/${FID}".reason.* 2>/dev/null | wc -l | tr -d ' ')
+assert_eq "reason file saved" "1" "$reason_files"
+assert_eq "reason content" "perf-critical" "$(cat "$CACHE/${FID}".reason.*)"
+
+# ── Test 5: Trailing newline preservation ────────────────────────────────
+printf '\nTest 5: Trailing newline preservation\n'
+rm -f "$CACHE"/*
+
+SRC="$TMPDIR/no-trailing-nl.js"
+DEST="$TMPDIR/no-trailing-nl-filtered.js"
+printf 'line1\n// simplify-ignore-start\nsecret\n// simplify-ignore-end' > "$SRC"
+
+FID="test_trail"
+filter_file "$SRC" "$DEST" "$FID"
+
+# Source has no trailing newline; dest should also have no trailing newline
+src_has_nl=$(tail -c 1 "$SRC" | wc -l | tr -d ' ')
+dest_has_nl=$(tail -c 1 "$DEST" | wc -l | tr -d ' ')
+assert_eq "dest preserves no-trailing-newline from source" "$src_has_nl" "$dest_has_nl"
+
+# ── Test 6: No blocks → return 1 ────────────────────────────────────────
+printf '\nTest 6: No blocks returns 1\n'
+rm -f "$CACHE"/*
+
+SRC="$TMPDIR/no-blocks.js"
+DEST="$TMPDIR/no-blocks-filtered.js"
+cat > "$SRC" <<'EOF'
+const a = 1;
+const b = 2;
+EOF
+
+FID="test_noblocks"
+rc=0
+filter_file "$SRC" "$DEST" "$FID" || rc=$?
+assert_eq "returns 1 when no blocks found" "1" "$rc"
+
+# ── Test 7: Unclosed block emits warning and flushes ─────────────────────
+printf '\nTest 7: Unclosed block\n'
+rm -f "$CACHE"/*
+
+SRC="$TMPDIR/unclosed.js"
+DEST="$TMPDIR/unclosed-filtered.js"
+cat > "$SRC" <<'EOF'
+line1
+// simplify-ignore-start
+orphan code
+EOF
+
+FID="test_unclosed"
+stderr_out=$(filter_file "$SRC" "$DEST" "$FID" 2>&1) || true
+assert_eq "warning emitted for unclosed block" "1" "$(printf '%s' "$stderr_out" | grep -c 'unclosed')"
+assert_eq "orphan code flushed to output" "1" "$(grep -c 'orphan code' "$DEST")"
+
+# ── Test 8: Single-line block with reason ────────────────────────────────
+printf '\nTest 8: Single-line block with reason\n'
+rm -f "$CACHE"/*
+
+SRC="$TMPDIR/single-reason.js"
+DEST="$TMPDIR/single-reason-filtered.js"
+cat > "$SRC" <<'EOF'
+before
+/* simplify-ignore-start: hot-path */ x = compute(); /* simplify-ignore-end */
+after
+EOF
+
+FID="test_single_reason"
+filter_file "$SRC" "$DEST" "$FID"
+
+placeholder_count=$(grep -c 'BLOCK_' "$DEST")
+assert_eq "exactly one placeholder for single-line+reason" "1" "$placeholder_count"
+assert_eq "reason in placeholder" "1" "$(grep -c 'hot-path' "$DEST")"
+
+# ── Test 9: HTML comment syntax ──────────────────────────────────────────
+printf '\nTest 9: HTML comment syntax\n'
+rm -f "$CACHE"/*
+
+SRC="$TMPDIR/html.html"
+DEST="$TMPDIR/html-filtered.html"
+cat > "$SRC" <<'EOF'
+<div>
+<!-- simplify-ignore-start -->
+<secret-component />
+<!-- simplify-ignore-end -->
+</div>
+EOF
+
+FID="test_html"
+filter_file "$SRC" "$DEST" "$FID"
+
+placeholder_count=$(grep -c 'BLOCK_' "$DEST")
+assert_eq "HTML block replaced" "1" "$placeholder_count"
+assert_eq "HTML suffix preserved" "1" "$(grep -c '\-\->' "$DEST")"
+
+# ── Test 10: JSON parsing error warning ──────────────────────────────────
+printf '\nTest 10: Malformed JSON input produces warning\n'
+
+warning_out=$(echo 'NOT_JSON{{{' | bash hooks/simplify-ignore.sh 2>&1) || true
+assert_eq "warning on bad JSON" "1" "$(printf '%s' "$warning_out" | grep -c 'Warning.*failed to parse')"
+
+# ── Summary ──────────────────────────────────────────────────────────────
+printf '\n══════════════════════════════════════════\n'
+printf 'Results: %d passed, %d failed\n' "$PASS" "$FAIL"
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1