leek/agent-skills / skills/to-spec
to-spec
VerifiedTurn the current conversation into a spec (PRD) saved under .scratch/, by synthesis, not interview. Use when the user wants a spec written from what a discussion, grilling, or wayfinder session settled, or an existing spec revised in place.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.2 KB |
| agents/openai.yaml | config | 201 B |
| scripts/publish-spec.shexecutable | script | 5.3 KB |
| scripts/test-publish-spec.shexecutable | script | 8.4 KB |
scripts/publish-spec.sh
View on GitHub#!/bin/bash
# Commit .scratch/<slug> where to-spec and to-tickets publish it, without moving the
# checkout or carrying another session's commits.
#
# Usage: publish-spec.sh <slug> -m <message> [--own <sha>]... [--default <branch>]
# <slug>: one directory name under .scratch/ (a trailing slash is dropped). A slug that
# is empty or ".", starts with "-", or holds "/" or ".." is a usage error: it
# would reach a path outside .scratch/<slug>.
# --own: a commit this session made on the current branch (repeat per sha). A fresh
# session passes none.
#
# Where it commits:
# - "ignored": `git check-ignore -q .scratch/<slug>/` holds; nothing is committed.
# - "docs-branch": the branch docs/<slug>-spec exists, or origin/<default>..HEAD holds a
# commit not passed as --own, or HEAD is detached (a commit there would be on no
# branch). The commit goes on docs/<slug>-spec (created from
# origin/<default> when missing) through the temporary worktree
# .claude/worktrees/docs-<slug>-spec, removed again without --force; the checkout
# stays where it is.
# - "current": otherwise, on the current branch, staging only .scratch/<slug>.
#
# Output: JSON {"where","branch","sha"} (sha "" when nothing changed or ignored). Needs jq.
set -e
usage() { echo "Usage: publish-spec.sh <slug> -m <message> [--own <sha>]... [--default <branch>]" >&2; exit 2; }
slug=${1:-}
while [ "${slug%/}" != "$slug" ]; do slug=${slug%/}; done
# The same rule as implement's start-branch.sh: the slug is one directory name.
case "$slug" in
"" | . | -* | */* | *..*) [ -z "$slug" ] || echo "Not a slug (one directory name under .scratch/): $slug" >&2; usage ;;
esac
shift
msg=""; own=(); default=""
while [ $# -gt 0 ]; do
case "$1" in
-m) msg=${2:-}; shift ;;
--own) [ -n "${2:-}" ] || { echo "--own needs a sha" >&2; exit 2; }; own+=("$(git rev-parse "$2")"); shift ;;
--default) default=${2:-}; shift ;;
*) echo "Unknown arg: $1" >&2; exit 2 ;;
esac
shift
done
[ -n "$msg" ] || { echo "-m <message> is required" >&2; exit 2; }
command -v jq >/dev/null 2>&1 || { echo "publish-spec.sh needs jq on PATH" >&2; exit 1; }
dir=".scratch/$slug"
[ -d "$dir" ] || { echo "No $dir in $(pwd)" >&2; exit 2; }
out() { jq -cn --arg where "$1" --arg branch "$2" --arg sha "$3" '{where: $where, branch: $branch, sha: $sha}'; }
# The slug's own directory, with the slash: a directory-only rule (.scratch/) and a
# contents rule (.scratch/*) both match it, whether or not the directory exists yet.
if git check-ignore -q -- "$dir/"; then
echo ">> .scratch is ignored here; nothing committed" >&2
out ignored "" ""; exit 0
fi
if [ -z "$default" ]; then
default=$(git symbolic-ref --short -q refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||') || true
[ -n "$default" ] || default=main
fi
git fetch -q origin
git rev-parse --verify -q "refs/remotes/origin/$default" >/dev/null \
|| { echo "origin/$default does not exist; pass --default <branch>" >&2; exit 2; }
docs="docs/$slug-spec"
foreign=""
# Assigned first: a failing rev-list inside `for … in $(…)` would not stop the script.
revs=$(git rev-list "origin/$default..HEAD")
for s in $revs; do
mine=0
for o in ${own[@]+"${own[@]}"}; do [ "$s" = "$o" ] && mine=1; done
[ "$mine" = 1 ] || { foreign=$s; break; }
done
detached=0
git symbolic-ref -q HEAD >/dev/null || detached=1
if [ -z "$foreign" ] && [ "$detached" = 0 ] && ! git rev-parse --verify -q "refs/heads/$docs" >/dev/null; then
git add -- "$dir"
if git diff --cached --quiet -- "$dir"; then
echo ">> $dir unchanged; nothing committed" >&2
out current "$(git branch --show-current)" ""; exit 0
fi
git commit -q --only -m "$msg" -- "$dir"
out current "$(git branch --show-current)" "$(git rev-parse HEAD)"; exit 0
fi
[ -z "$foreign" ] || echo ">> HEAD carries $foreign, not this session's; committing on $docs" >&2
[ "$detached" = 0 ] || echo ">> HEAD is detached; committing on $docs" >&2
main=$(git worktree list --porcelain | awk '/^worktree /{ print substr($0, 10); exit }')
wt="$main/.claude/worktrees/docs-$slug-spec"
src=$(pwd -P)/$dir
# A step that fails (a pre-commit hook, a full disk) must not leave the temporary worktree
# behind: the next run would stop at "already exists". The worktree is this run's own, so
# its uncommitted copy is discarded and it is removed without --force. The branch stays.
added=0
cleanup() {
[ "$added" = 1 ] && [ -d "$wt" ] || return 0
git -C "$wt" reset -q --hard HEAD 2>/dev/null || true
git -C "$wt" clean -fdq -- .scratch 2>/dev/null || true
git worktree remove "$wt" >&2 || echo ">> could not remove $wt; remove it before the next run" >&2
}
trap cleanup EXIT
[ ! -e "$wt" ] || { echo "$wt already exists; remove that worktree first (git worktree remove)" >&2; exit 1; }
added=1
if git rev-parse --verify -q "refs/heads/$docs" >/dev/null; then
git worktree add -q "$wt" "$docs" >&2
else
git worktree add -q -b "$docs" "$wt" "origin/$default" >&2
fi
rm -rf "${wt:?}/$dir"
mkdir -p "$wt/.scratch"
cp -R "$src" "$wt/.scratch/"
git -C "$wt" add -- "$dir"
sha=""
if git -C "$wt" diff --cached --quiet -- "$dir"; then
echo ">> $dir unchanged on $docs; nothing committed" >&2
else
git -C "$wt" commit -q -m "$msg" -- "$dir"
sha=$(git -C "$wt" rev-parse HEAD)
fi
git worktree remove "$wt" >&2 || echo ">> git worktree remove refused $wt; it stays" >&2
added=0
out docs-branch "$docs" "$sha"
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |