Agent Skills for SpecStory
A collection of AI agent skills for working with SpecStory session histories. Built for developers who want Claude Code (or similar AI coding assistants) to help analyze, organize, and extract insights from their AI-assisted coding sessions.
Contributions welcome! Found a way to improve a skill or have a new one to add? Open a PR.
What are Skills?
Skills are markdown files that give AI agents specialized knowledge and workflows for specific tasks. When you add these to your project, Claude Code (or agents like Codex, Cursor, Gemini, Copilot) can recognize relevant tasks and apply the right frameworks and analysis patterns.
Prerequisites
These skills work with your local .specstory/history directory (or cloud.specstory.com APIs), which is created by SpecStory when capturing AI coding sessions.
Install SpecStory for your tool:
| Tool | Installation |
|---|
| Cursor / VS Code | Search "SpecStory" in Extensions (Cmd/Ctrl+Shift+X) |
| Claude Code / CLI agents | brew tap specstoryai/tap && brew install specstory |
Once installed, your AI conversations are automatically saved to .specstory/history/ in each project.
Note for contributors: Don't run npx skills add from within this repo - it will install skills into the repo directory. The .gitignore excludes these directories, but install skills in your actual projects instead.
Available Skills
| Skill | Description |
|---|
| specstory-guard | Install a pre-commit hook that scans .specstory/history for secrets before commits. Run when user says "set up secret... |
| specstory-link-trail | Track all URLs fetched during SpecStory AI coding sessions. Run when user says "show my link trail", "what URLs did I... |
| specstory-organize | Organize SpecStory AI coding sessions in .specstory/history into year/month folders. Run when user says "organize my... |
| specstory-project-stats | Fetch project statistics from SpecStory Cloud. Run when user says "get project stats", "show SpecStory stats", "project... |
| specstory-session-summary | Summarize recent SpecStory AI coding sessions in standup format. Use when the user wants to review sessions from... |
| specstory-yak | Analyze your SpecStory AI coding sessions in .specstory/history for yak shaving - when your initial goal got derailed... |
Installation
Option 1: Skills CLI (Recommended)
Use npx skills to install skills directly:
# Install all skills
npx skills add specstoryai/agent-skills
# Install specific skills
npx skills add specstoryai/agent-skills --skill specstory-yak specstory-session-summary
# List available skills
npx skills add specstoryai/agent-skills --list
This installs skills to .agents/skills/ and symlinks them to each detected agent's directory (.claude/skills/, .cursor/skills/, .codex/skills/, etc.). The CLI auto-detects which agents you have installed.
Option 2: Clone and Copy
Clone the entire repo and copy the skills folder:
git clone https://github.com/specstoryai/agent-skills.git
cp -r agent-skills/skills/* .claude/skills/
Option 3: Git Submodule
Add as a submodule for easy updates:
git submodule add https://github.com/specstoryai/agent-skills.git .claude/agent-skills
Then reference skills from .claude/agent-skills/skills/.
Option 4: Fork and Customize
- Fork this repository
- Customize skills for your specific needs
- Clone your fork into your projects
Usage
Once installed, just ask Claude Code to help with SpecStory-related tasks:
"Analyze my yak shaving for the last 30 days"
→ Uses specstory-yak skill
"Summarize my coding sessions from this week"
→ Uses specstory-session-summary skill
"Organize my specstory history folder"
→ Uses specstory-organize skill
"What URLs did I visit in my last session?"
→ Uses specstory-link-trail skill
"Set up secret scanning for my specstory files"
→ Uses specstory-guard skill
You can also invoke skills directly:
/specstory-yak
/specstory-session-summary
/specstory-organize
/specstory-link-trail
/specstory-guard
Skill Categories
Session Analysis
specstory-yak - Detect rabbit holes and scope creep in your coding sessionsspecstory-session-summary - Generate standup-ready summaries of recent workspecstory-link-trail - Track all URLs fetched during sessions
Organization & Maintenance
specstory-organize - Keep history files organized by year/monthspecstory-guard - Pre-commit hook to catch secrets in history files
Contributing
Found a way to improve a skill? Have a new skill to suggest? PRs and issues welcome!
See CONTRIBUTING.md for detailed guidelines on:
- Repository structure and GitHub workflows
- How to add a new skill
- Naming conventions and PR checklist
License
Apache 2.0 - Use these however you want.
