feat: install full skill pack
This commit is contained in:
Andy Dixon
@@ -0,0 +1,84 @@
|
||||
---
|
||||
name: summarise
|
||||
description: Generate or update a repository SUMMARY.md that explains what a software project is, what it does, and how it evolved through Git history. Use when the user asks to summarise a codebase, create project history documentation, produce a v3-style management-readable technical narrative, analyse milestones from Git tags, or document significant commits and their product impact.
|
||||
---
|
||||
|
||||
# Summarise
|
||||
|
||||
## Goal
|
||||
|
||||
Create a `SUMMARY.md` in the repository root unless the user names another file. The document should feel like a polished project-evolution report: technically accurate, management-readable, British English, friendly, crisp, and lightly ADHD without becoming gimmicky.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Inspect the project before writing:
|
||||
- read high-signal files such as `README*`, package manifests, docs, plugin/app metadata, build files, and the main source tree layout;
|
||||
- identify the project type, audience, core capabilities, and current state;
|
||||
- do not rely only on commit messages.
|
||||
|
||||
2. Gather Git evidence:
|
||||
- run `git status --short` and avoid mixing unrelated dirty work into the summary unless it is relevant;
|
||||
- list tags in chronological order and treat them as milestones;
|
||||
- compare milestone ranges with `git diff --shortstat <from>..<to>`;
|
||||
- inspect significant commits with `git show --stat --summary <commit>` and, where useful, `git show --name-only <commit>`;
|
||||
- consider merge commits, large diffs, new packages, major docs, tests, security work, UX changes, and architecture shifts as candidates for deeper explanation.
|
||||
|
||||
3. Use the helper script when useful:
|
||||
- run `~/.codex/skills/summarise/scripts/git-summary-evidence.sh [repo]`;
|
||||
- use its output as evidence, not as the final document;
|
||||
- inspect extra commits manually when the script highlights something important.
|
||||
|
||||
4. Write `SUMMARY.md` with this shape unless the project strongly suggests another:
|
||||
- title and short version;
|
||||
- executive summary;
|
||||
- line-count/change-size table;
|
||||
- timeline from Git commits, with tags as milestone headings;
|
||||
- what the project does now;
|
||||
- architecture and main components;
|
||||
- major feature areas;
|
||||
- significant commits and why they mattered;
|
||||
- security, testing, documentation, and operational maturity;
|
||||
- what it is good at;
|
||||
- what it is not yet;
|
||||
- recommended rollout/readout narrative;
|
||||
- final read.
|
||||
|
||||
5. Keep the writing honest:
|
||||
- distinguish implemented features from foundations, prototypes, and future work;
|
||||
- never inflate weak evidence into certainty;
|
||||
- call out uncertainty if commit messages are vague;
|
||||
- avoid corporate filler, but make it readable for non-specialists.
|
||||
|
||||
## Style
|
||||
|
||||
- Use British English.
|
||||
- Prefer concrete product impact over raw technical trivia.
|
||||
- Explain technical terms briefly when they matter.
|
||||
- Keep a lively, human tone: direct, warm, occasionally wry.
|
||||
- Avoid overdoing jokes; one sharp line beats six forced ones.
|
||||
- Use crisp headings and tables where they help scanning.
|
||||
- Use exact commit hashes, tag names, dates, and file counts where available.
|
||||
|
||||
## Significant Commit Heuristics
|
||||
|
||||
Give more detail to commits that:
|
||||
|
||||
- introduce or remove a package, service, plugin, app, or major subsystem;
|
||||
- add a new user-facing workflow;
|
||||
- change data flow, storage, auth, permissions, or trust boundaries;
|
||||
- add detector/model/algorithm families;
|
||||
- introduce a new UI paradigm or configuration system;
|
||||
- add tests around risky behaviour;
|
||||
- harden security, input bounds, sanitisation, or error handling;
|
||||
- create or update major documentation;
|
||||
- have unusually large line counts or many touched files.
|
||||
|
||||
Do not treat every commit equally. A small commit can matter if it changes the product shape; a large commit can be mechanical. Say which is which.
|
||||
|
||||
## Output Rules
|
||||
|
||||
- Create or update `SUMMARY.md` using normal file-editing tools.
|
||||
- If a project already has a versioned summary such as `v3.md`, use it as a style reference but do not blindly copy it.
|
||||
- If the user asks for a specific filename, use that filename instead.
|
||||
- Include enough detail that a manager can understand the journey without reading the source, while an engineer can still trust the evidence.
|
||||
- Before finishing, run `git diff --check` if a Git repository is present.
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "Summarise"
|
||||
short_description: "Generate project evolution summaries"
|
||||
default_prompt: "Use $summarise to create a SUMMARY.md for this repository."
|
||||
Executable
+77
@@ -0,0 +1,77 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
repo="${1:-.}"
|
||||
cd "$repo"
|
||||
|
||||
if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
|
||||
echo "Not inside a Git repository: $repo" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "# Repository"
|
||||
printf "Root: %s\n" "$(git rev-parse --show-toplevel)"
|
||||
printf "HEAD: %s\n" "$(git log -1 --format='%h %ad %s' --date=short)"
|
||||
echo
|
||||
|
||||
echo "# Working Tree"
|
||||
git status --short || true
|
||||
echo
|
||||
|
||||
echo "# Tags Chronological"
|
||||
tags=()
|
||||
while IFS= read -r tag; do
|
||||
tags+=("$tag")
|
||||
done < <(git tag --sort=creatordate)
|
||||
if ((${#tags[@]} == 0)); then
|
||||
echo "No tags found."
|
||||
else
|
||||
for tag in "${tags[@]}"; do
|
||||
printf "%s | %s | %s\n" \
|
||||
"$tag" \
|
||||
"$(git log -1 --format='%ad' --date=short "$tag")" \
|
||||
"$(git log -1 --format='%h %s' "$tag")"
|
||||
done
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "# Milestone Diff Stats"
|
||||
if ((${#tags[@]} > 0)); then
|
||||
first_commit="$(git rev-list --max-parents=0 HEAD | tail -n 1)"
|
||||
prev="$first_commit"
|
||||
prev_label="first commit ${first_commit:0:7}"
|
||||
for tag in "${tags[@]}"; do
|
||||
printf "## %s -> %s\n" "$prev_label" "$tag"
|
||||
git diff --shortstat "$prev".."$tag" || true
|
||||
prev="$tag"
|
||||
prev_label="$tag"
|
||||
done
|
||||
printf "## %s -> HEAD\n" "$prev_label"
|
||||
git diff --shortstat "$prev"..HEAD || true
|
||||
else
|
||||
git diff --shortstat "$(git rev-list --max-parents=0 HEAD | tail -n 1)"..HEAD || true
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "# Recent Commit Timeline"
|
||||
git log --date=short --pretty=format:'%h | %ad | %s' --reverse --max-count=120
|
||||
echo
|
||||
echo
|
||||
|
||||
echo "# Largest Commits By Changed Files"
|
||||
git log --pretty=format:'%h' --max-count=300 |
|
||||
while read -r commit; do
|
||||
files="$(git show --shortstat --format= "$commit" | awk '/files? changed/ {print $1 + 0}')"
|
||||
printf "%06d %s %s\n" "${files:-0}" "$commit" "$(git log -1 --format='%ad | %s' --date=short "$commit")"
|
||||
done | sort -rn | head -n 30
|
||||
echo
|
||||
|
||||
echo "# Largest Commits By Line Churn"
|
||||
git log --pretty=format:'%h' --max-count=300 |
|
||||
while read -r commit; do
|
||||
stat="$(git show --shortstat --format= "$commit")"
|
||||
inserted="$(awk '/insertions?\(\+\)/ {for (i=1;i<=NF;i++) if ($i ~ /insertions?\(\+\)/) print $(i-1)}' <<<"$stat")"
|
||||
deleted="$(awk '/deletions?\(-\)/ {for (i=1;i<=NF;i++) if ($i ~ /deletions?\(-\)/) print $(i-1)}' <<<"$stat")"
|
||||
churn="$(( ${inserted:-0} + ${deleted:-0} ))"
|
||||
printf "%08d %s %s\n" "$churn" "$commit" "$(git log -1 --format='%ad | %s' --date=short "$commit")"
|
||||
done | sort -rn | head -n 30
|
||||
Reference in New Issue
Block a user