specstory-project-stats
Fetch project statistics from SpecStory Cloud. Run when user says "get project stats", "show SpecStory stats", "project statistics", "how many sessions", or "SpecStory metrics".
Best use case
specstory-project-stats is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Fetch project statistics from SpecStory Cloud. Run when user says "get project stats", "show SpecStory stats", "project statistics", "how many sessions", or "SpecStory metrics".
Teams using specstory-project-stats should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/specstory-project-stats/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How specstory-project-stats Compares
| Feature / Agent | specstory-project-stats | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Fetch project statistics from SpecStory Cloud. Run when user says "get project stats", "show SpecStory stats", "project statistics", "how many sessions", or "SpecStory metrics".
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# SpecStory Project Stats
Fetches project statistics from SpecStory's cloud platform, showing contributor counts, session activity, and other project metrics.
## How It Works
1. **Identifies** the project via `.specstory/.project.json`, git remote, or folder name
2. **Calls** the SpecStory Cloud API
3. **Returns** project statistics in JSON format
4. **Presents** the data in a readable summary
## Prerequisites
- Project must be synced to SpecStory Cloud
- Node.js must be available to run the script
## Usage
### Slash Command
| User says | Action |
|-----------|--------|
| `/specstory-project-stats` | Fetch stats for current project |
| `/specstory-project-stats` | Same as above (no arguments needed) |
### Direct Script Usage
```bash
# Fetch stats for current project
node skills/specstory-project-stats/scripts/get-stats.js
# With custom API endpoint (for development)
SPECSTORY_API_URL=http://localhost:5173 node skills/specstory-project-stats/scripts/get-stats.js
```
## Output
The script outputs JSON with project statistics:
```json
{
"project_id": "specstoryai/agent-skills",
"sessions": {
"total": 156,
"last_30_days": 47,
"last_7_days": 12
},
"contributors": {
"total": 5,
"active_last_30_days": 3
},
"activity": {
"first_session": "2025-10-15",
"last_session": "2026-01-28",
"avg_sessions_per_week": 8.2
}
}
```
## Project ID Resolution
The script determines project ID in this order:
1. **`.specstory/.project.json`** - Uses `git_id` or `workspace_id` field
2. **Git remote** - Extracts repo name from `origin` remote URL
3. **Folder name** - Falls back to current directory name
## Error Handling
| Error | Meaning | Action |
|-------|---------|--------|
| 404 | Project not found | Project needs to sync to SpecStory Cloud first |
| 401 | Unauthorized | API endpoint may require authentication |
| Network error | Can't reach API | Check internet connection |
## Present Results to User
After fetching stats, present them in a friendly format:
### Example Response (success)
```
Here are the stats for **specstoryai/agent-skills**:
**Sessions**
- Total: 156 sessions captured
- Last 30 days: 47 sessions
- Last 7 days: 12 sessions
**Contributors**
- Total: 5 contributors
- Active recently: 3
**Activity**
- First session: October 15, 2025
- Most recent: January 28, 2026
- Average: ~8 sessions per week
Your project has been actively using AI-assisted coding!
```
### Example Response (404 error)
```
This project doesn't exist on SpecStory Cloud yet.
To get started:
1. Make sure you have SpecStory installed
2. Run `specstory sync` to push your local sessions to the cloud
3. Try this command again
Need help? Check the docs at https://docs.specstory.com
```
## Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `SPECSTORY_API_URL` | `https://cloud.specstory.com` | API endpoint |
## Notes
- Statistics are fetched from SpecStory Cloud, not local history
- Project must have synced sessions to show meaningful stats
- The API is public and doesn't require authentication for basic statsRelated Skills
specstory-yak
Analyze your SpecStory AI coding sessions in .specstory/history for yak shaving - when your initial goal got derailed into rabbit holes. Run when user says "analyze my yak shaving", "check for rabbit holes", "how distracted was I", or "yak shave score".
specstory-session-summary
Summarize recent SpecStory AI coding sessions in standup format. Use when the user wants to review sessions from .specstory/history, prepare for standups, track work progress, or understand what was accomplished.
specstory-organize
Organize SpecStory AI coding sessions in .specstory/history into year/month folders. Run when user says "organize my history", "clean up specstory", "sort my sessions", or "organize specstory files".
specstory-link-trail
Track all URLs fetched during SpecStory AI coding sessions. Run when user says "show my link trail", "what URLs did I visit", "list fetched links", or "show web fetches".
specstory-guard
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".
project-alchemy-orchestrator
A strategic guide for managing complex creative portfolios as a system of "organs" (Art, Commerce, Tools), diagnosing lifecycle stages (Nigredo, Albedo, Rubedo), and balancing the "Four Fields" of creative labor.
claude-project-manifest
Creates annotated bibliography-style manifests for Claude projects, tracking files, conversation threads, and relationships with unique IDs and annotations. Use when documenting project contents, creating file inventories, tracking conversation history, or building navigable knowledge maps.
taxonomy-modeling-design
Phase 2 of the pentaphase structural-overhaul protocol. Classifies entities, standardizes attributes, establishes relationships, and designs the access framework. Use when the user invokes phase 2 of an overhaul, asks to "design the taxonomy" or "model the structure", or has completed a landscape audit and is ready to redesign. Consumes phase-1-landscape-report.md; produces phase-2-taxonomy-model.md.
systemic-ingestion-normalization
Phase 4 of the pentaphase structural-overhaul protocol. Purges redundancies, enriches and aligns legacy entities to the new schema, executes phased ingestion into the new environment, and audits integrity. Use when the user invokes phase 4 of an overhaul, asks to "migrate the data" or "ingest into the new system", or has a configured environment ready to accept legacy entities. Consumes phase-3-environment-spec.md; produces phase-4-ingestion-report.md.
system-environment-configuration
Phase 3 of the pentaphase structural-overhaul protocol. Translates the taxonomy model into objective technical criteria, evaluates candidate mechanisms or frameworks, instantiates the chosen architecture, and programs validation rules. Use when the user invokes phase 3 of an overhaul, asks to "select a system" or "configure the environment", or has a taxonomy model and is ready to choose technology. Consumes phase-2-taxonomy-model.md; produces phase-3-environment-spec.md.
pentaphase-orchestrator
Threads the full five-phase structural-overhaul protocol — landscape discovery, taxonomy design, environment configuration, systemic ingestion, governance evolution — for any substrate the user names. Use when the user requests a structural overhaul, system redesign, or end-to-end restructuring of a documentation system, asset registry, code monorepo, knowledge base, or operational workflow; or when they explicitly invoke the pentaphase methodology. Coordinates handoffs between phase-skills and seats validation gates between phases.
landscape-discovery-audit
Phase 1 of the pentaphase structural-overhaul protocol. Inventories assets, maps current flow, identifies friction, and defines value metrics for any substrate. Use when the user invokes phase 1 of an overhaul, requests a baseline audit, asks to "discover the landscape" of a system, or wants to understand current state before redesigning. Produces phase-1-landscape-report.md.