{"id":"7d415689-c3d0-412d-8a85-5d61b8f63969","shortId":"4Ruaha","kind":"skill","title":"specstory-guard","tagline":"Install a pre-commit hook that scans .specstory/history for secrets before commits. Run when user says \"set up secret scanning\", \"install specstory guard\", \"protect my history\", or \"check for secrets\".","description":"# SpecStory Guard\n\nA pre-commit guardrail that scans `.specstory/history` for potential secrets and blocks commits until they are removed or redacted.\n\n## How It Works\n\n1. **Installs** a git pre-commit hook in your repository\n2. **Scans** `.specstory/history` files on every commit\n3. **Detects** common secret patterns (API keys, tokens, private keys)\n4. **Blocks** the commit if secrets are found\n5. **Reports** findings with redacted previews for safe review\n\n## Why Use Guard?\n\nAI coding sessions may inadvertently capture sensitive data:\n- API keys you pasted into chat\n- Environment variables in command output\n- Private keys or tokens in error messages\n- Credentials in configuration examples\n\nGuard prevents accidental commits of these secrets.\n\n## Usage\n\n### Slash Command\n\n| User says | Action |\n|-----------|--------|\n| `/specstory-guard` | Install the pre-commit hook |\n| `/specstory-guard install` | Install the pre-commit hook |\n| `/specstory-guard scan` | Run a manual scan without installing |\n| `/specstory-guard check` | Alias for scan |\n| `/specstory-guard uninstall` | Remove the pre-commit hook |\n\n### Direct Script Usage\n\n```bash\n# Install the pre-commit hook\npython skills/specstory-guard/scripts/guard.py install\n\n# Run a manual scan\npython skills/specstory-guard/scripts/guard.py scan --root .\n\n# Uninstall the hook\npython skills/specstory-guard/scripts/guard.py uninstall\n\n# Scan with custom allowlist\nSPECSTORY_GUARD_ALLOWLIST='example-key,PLACEHOLDER_.*' \\\n  python skills/specstory-guard/scripts/guard.py scan --root .\n```\n\n## Output\n\n### Scan with findings:\n\n```\nSpecStory Guard - Security Scan\n===============================\n\nScanning .specstory/history/...\n\nALERT: Potential secrets found!\n\nFile: .specstory/history/2026-01-22_19-20-56Z-api-setup.md\n  Line 142: AWS_SECRET_ACCESS_KEY=AKIA...redacted...XYZ\n  Line 289: private_key: \"-----BEGIN RSA PRIVATE KEY-----...\"\n\nFile: .specstory/history/2026-01-20_10-15-33Z-debug-auth.md\n  Line 56: Authorization: Bearer eyJhbG...redacted...\n\nTotal: 3 potential secrets in 2 files\n\nCommit blocked. Please redact or remove these secrets before committing.\n```\n\n### Clean scan:\n\n```\nSpecStory Guard - Security Scan\n===============================\n\nScanning .specstory/history/...\n\nAll clear! No secrets detected in 47 files.\n```\n\n### Installation success:\n\n```\nSpecStory Guard - Setup\n=======================\n\nPre-commit hook installed at .git/hooks/pre-commit\n\nThe hook will now scan .specstory/history/ before each commit.\nTo test: python skills/specstory-guard/scripts/guard.py scan --root .\n```\n\n## Detected Patterns\n\nGuard scans for these common secret patterns:\n\n| Pattern | Example |\n|---------|---------|\n| AWS Keys | `AKIA...`, `aws_secret_access_key` |\n| API Tokens | `Bearer ...`, `token: ...` |\n| Private Keys | `-----BEGIN RSA PRIVATE KEY-----` |\n| GitHub Tokens | `ghp_...`, `github_pat_...` |\n| Generic Secrets | `password=`, `secret=`, `api_key=` |\n\n## Tuning with Allowlist\n\nIf you have false positives (example keys, placeholders), use the allowlist:\n\n```bash\n# Environment variable (comma-separated regex patterns)\nSPECSTORY_GUARD_ALLOWLIST='example-key,PLACEHOLDER_.*,test-token' \\\n  python skills/specstory-guard/scripts/guard.py scan --root .\n```\n\n## Remediation\n\nWhen secrets are found:\n\n1. **Open the file** - Find the line number from the report\n2. **Redact the secret** - Replace with `[REDACTED]` or remove the line\n3. **Re-run scan** - Verify the fix with another scan\n4. **Commit** - The pre-commit hook will pass\n\n## Present Results to User\n\nAfter running guard commands:\n\n1. **For install** - Confirm the hook is installed and explain what it does\n2. **For scan with findings** - List the findings and offer to help redact them\n3. **For clean scan** - Confirm no secrets were found\n\n### Example Response (findings)\n\n```\nI found 3 potential secrets in your SpecStory history:\n\n1. **AWS credentials** in `2026-01-22_19-20-56Z-api-setup.md` (line 142)\n2. **Private key** in the same file (line 289)\n3. **Bearer token** in `2026-01-20_10-15-33Z-debug-auth.md` (line 56)\n\nWould you like me to help redact these? I can replace them with `[REDACTED]`\nwhile preserving the rest of the conversation context.\n```\n\n## Notes\n\n- Uses no external dependencies (pure Python)\n- Hook runs automatically on `git commit`\n- Scan is fast - typically under 1 second for hundreds of files\n- Allowlist patterns are regular expressions","tags":["specstory","guard","agent","skills","specstoryai","agent-skills","claude-code-plugin"],"capabilities":["skill","source-specstoryai","skill-specstory-guard","topic-agent-skills","topic-claude-code-plugin","topic-skills"],"categories":["agent-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/specstoryai/agent-skills/specstory-guard","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add specstoryai/agent-skills","source_repo":"https://github.com/specstoryai/agent-skills","install_from":"skills.sh"}},"qualityScore":"0.462","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 24 github stars · SKILL.md body (4,413 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-22T01:01:28.573Z","embedding":null,"createdAt":"2026-04-18T22:23:44.868Z","updatedAt":"2026-04-22T01:01:28.573Z","lastSeenAt":"2026-04-22T01:01:28.573Z","tsv":"'/specstory-guard':151,158,166,174,179 '1':60,410,460,508,571 '142':246,514 '2':71,275,421,473,515 '2026-01-20_10-15-33z-debug-auth.md':528 '2026-01-22_19-20-56z-api-setup.md':512 '289':255,523 '3':78,271,432,487,501,524 '4':88,443 '47':301 '5':96 '56':265,530 'access':249,346 'accident':140 'action':150 'ai':108 'akia':251,343 'alert':239 'alia':176 'allowlist':217,220,371,382,393,577 'anoth':441 'api':83,116,348,367 'author':266 'automat':562 'aw':247,341,344,509 'bash':190,383 'bearer':267,350,525 'begin':258,354 'block':49,89,278 'captur':113 'chat':121 'check':32,175 'clean':287,489 'clear':296 'code':109 'comma':387 'comma-separ':386 'command':125,147,459 'commit':8,16,40,50,66,77,91,141,156,164,185,195,277,286,310,323,444,448,565 'common':80,336 'configur':136 'confirm':463,491 'context':552 'convers':551 'credenti':134,510 'custom':216 'data':115 'depend':557 'detect':79,299,330 'direct':187 'environ':122,384 'error':132 'everi':76 'exampl':137,222,340,377,395,496 'example-key':221,394 'explain':469 'express':581 'extern':556 'eyjhbg':268 'fals':375 'fast':568 'file':74,243,262,276,302,413,521,576 'find':98,232,414,477,480,498 'fix':439 'found':95,242,409,495,500 'generic':363 'ghp':360 'git':63,564 'git/hooks/pre-commit':314 'github':358,361 'guard':3,27,36,107,138,219,234,290,306,332,392,458 'guardrail':41 'help':484,536 'histori':30,507 'hook':9,67,157,165,186,196,210,311,316,449,465,560 'hundr':574 'inadvert':112 'instal':4,25,61,152,159,160,173,191,199,303,312,462,467 'key':84,87,117,128,223,250,257,261,342,347,353,357,368,378,396,517 'like':533 'line':245,254,264,416,431,513,522,529 'list':478 'manual':170,202 'may':111 'messag':133 'note':553 'number':417 'offer':482 'open':411 'output':126,229 'pass':451 'password':365 'past':119 'pat':362 'pattern':82,331,338,339,390,578 'placehold':224,379,397 'pleas':279 'posit':376 'potenti':46,240,272,502 'pre':7,39,65,155,163,184,194,309,447 'pre-commit':6,38,64,154,162,183,193,308,446 'present':452 'preserv':546 'prevent':139 'preview':101 'privat':86,127,256,260,352,356,516 'protect':28 'pure':558 'python':197,204,211,225,326,401,559 're':434 're-run':433 'redact':56,100,252,269,280,422,427,485,537,544 'regex':389 'regular':580 'remedi':405 'remov':54,181,282,429 'replac':425,541 'report':97,420 'repositori':70 'respons':497 'rest':548 'result':453 'review':104 'root':207,228,329,404 'rsa':259,355 'run':17,168,200,435,457,561 'safe':103 'say':20,149 'scan':11,24,43,72,167,171,178,203,206,214,227,230,236,237,288,292,293,319,328,333,403,436,442,475,490,566 'script':188 'second':572 'secret':14,23,34,47,81,93,144,241,248,273,284,298,337,345,364,366,407,424,493,503 'secur':235,291 'sensit':114 'separ':388 'session':110 'set':21 'setup':307 'skill' 'skill-specstory-guard' 'skills/specstory-guard/scripts/guard.py':198,205,212,226,327,402 'slash':146 'source-specstoryai' 'specstori':2,26,35,218,233,289,305,391,506 'specstory-guard':1 'specstory/history':12,44,73,238,294,320 'specstory/history/2026-01-20_10-15-33z-debug-auth.md':263 'specstory/history/2026-01-22_19-20-56z-api-setup.md':244 'success':304 'test':325,399 'test-token':398 'token':85,130,349,351,359,400,526 'topic-agent-skills' 'topic-claude-code-plugin' 'topic-skills' 'total':270 'tune':369 'typic':569 'uninstal':180,208,213 'usag':145,189 'use':106,380,554 'user':19,148,455 'variabl':123,385 'verifi':437 'without':172 'work':59 'would':531 'xyz':253","prices":[{"id":"1751e487-2584-4ef8-ba8d-30a32eae2a03","listingId":"7d415689-c3d0-412d-8a85-5d61b8f63969","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"specstoryai","category":"agent-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T22:23:44.868Z"}],"sources":[{"listingId":"7d415689-c3d0-412d-8a85-5d61b8f63969","source":"github","sourceId":"specstoryai/agent-skills/specstory-guard","sourceUrl":"https://github.com/specstoryai/agent-skills/tree/main/skills/specstory-guard","isPrimary":false,"firstSeenAt":"2026-04-18T22:23:44.868Z","lastSeenAt":"2026-04-22T01:01:28.573Z"}],"details":{"listingId":"7d415689-c3d0-412d-8a85-5d61b8f63969","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"specstoryai","slug":"specstory-guard","github":{"repo":"specstoryai/agent-skills","stars":24,"topics":["agent-skills","claude-code-plugin","skills"],"license":"apache-2.0","html_url":"https://github.com/specstoryai/agent-skills","pushed_at":"2026-01-31T01:24:32Z","description":"SpecStory's official collection of agent skills. Summarize, organize and create with `.specstory/history`","skill_md_sha":"4bae6e4d261d1092efa680add0fdc8bd670c3124","skill_md_path":"skills/specstory-guard/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/specstoryai/agent-skills/tree/main/skills/specstory-guard"},"layout":"multi","source":"github","category":"agent-skills","frontmatter":{"name":"specstory-guard","license":"Apache-2.0","description":"Install a pre-commit hook that scans .specstory/history for secrets before commits. Run when user says \"set up secret scanning\", \"install specstory guard\", \"protect my history\", or \"check for secrets\"."},"skills_sh_url":"https://skills.sh/specstoryai/agent-skills/specstory-guard"},"updatedAt":"2026-04-22T01:01:28.573Z"}}