akunzai/agent-skills / skills/setup-agent-ready-repo
setup-agent-ready-repo
UnverifiedSet up a repository so agents can file tickets, open pull or merge requests, and verify their own changes.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.1 KB |
| agents/openai.yaml | config | 172 B |
| assets/guarantees.tsv | other | 3.7 KB |
| assets/templates/issue-tracker.md | markdown | 5.8 KB |
| assets/templates/pull-request.md | markdown | 4.9 KB |
| assets/templates/verification.md | markdown | 5.2 KB |
| references/capture.md | markdown | 4.9 KB |
| references/gitlab-cli.md | markdown | 2.1 KB |
| references/re-running.md | markdown | 2.1 KB |
| references/ticket-and-pr.md | markdown | 7.4 KB |
| references/verification.md | markdown | 8.0 KB |
| scripts/check-drift.shexecutable | script | 7.7 KB |
| scripts/install-templates.shexecutable | script | 7.2 KB |
| skill.oms.sig | other | 14.6 KB |
scripts/install-templates.sh
View on GitHub#!/usr/bin/env bash
set -euo pipefail
# Copies this skill's document templates into a target repository, and checks
# installed documents for what an instruction cannot prevent: an unresolved
# <angle placeholder>, a guarantee the current
# templates pin that the document no longer carries, and an @path file
# reference in any docs/agents/*.md.
#
# Copying is the point. A model asked to write a document from a template
# regenerates it, rewording the sentences guarantees.tsv matches. Copying the
# bytes and editing the placeholders in place keeps them.
usage() {
cat >&2 <<'USAGE'
usage: install-templates.sh --forge <github|gitlab|none> [--force] [DIR]
install-templates.sh --check [DIR]
--forge which ticket document to install beside verification.md:
github writes pull-request.md, gitlab writes merge-request.md,
none writes verification.md alone (no remote)
--force overwrite a destination that already exists
--check scan installed documents for unresolved placeholders,
guarantees the current templates pin but the document lost, and
@path file references in any docs/agents/*.md;
exits non-zero when it finds any
DIR repository root (default: current directory)
USAGE
}
SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
TEMPLATES="$SKILL_DIR/assets/templates"
GUARANTEES="$SKILL_DIR/assets/guarantees.tsv"
FORGE=""
MODE="install"
FORCE=false
DIR=""
while [ $# -gt 0 ]; do
case "$1" in
--forge)
[ $# -ge 2 ] || { echo "--forge needs a value" >&2; usage; exit 2; }
FORGE="$2"
shift
;;
--check) MODE="check" ;;
--force) FORCE=true ;;
-h|--help) usage; exit 0 ;;
-*) echo "unknown option: $1" >&2; usage; exit 2 ;;
*)
if [ -n "$DIR" ]; then
echo "unexpected argument: $1" >&2
usage
exit 2
fi
DIR="$1"
;;
esac
shift
done
DIR="${DIR:-.}"
[ -d "$DIR" ] || { echo "not a directory: $DIR" >&2; exit 2; }
DIR="$(cd "$DIR" && pwd)"
DEST="$DIR/docs/agents"
# Markdown hard-wraps prose and indents continuation lines, so a guarantee
# spanning more than a few words straddles a line break and picks up the
# indentation with it. Fold to one line and squeeze the runs, or where the wrap
# happens to fall decides whether a pattern is found.
fold_prose() {
tr '\n' ' ' | tr -s '[:space:]' ' '
}
# Reports a guarantee the current templates pin that this document no longer
# carries. The document keeps whatever the repo edited into it; what is
# reported is the guarantee, and where in the template to read the original.
check_guarantees() {
local target=$1 kind=$2 found=0 doc name pattern origin folded
folded="$(fold_prose < "$target")"
while IFS=$'\t' read -r doc name pattern origin; do
case "$doc" in \#*|"") continue ;; esac
[ "$doc" = "$kind" ] || continue
printf '%s' "$folded" | grep -qiE "$pattern" && continue
printf 'BEHIND %s no longer carries %s\n template: %s looked for: /%s/\n' \
"${target#"$DIR"/}" "$name" "$origin" "$pattern"
found=1
done < "$GUARANTEES"
return "$found"
}
# An @ file reference is '@' plus a repo-relative path. Copilot CLI and
# Claude Code expand those when the document is read. @me, @user, npm
# scopes (@types/node), emails (user@host), and owner/action@vN are not
# paths: emails and action pins have an alnum before '@', and a scope
# has a slash but no file extension and no matching path in the repo.
is_at_file_ref() {
local path=$1 last rel
path="${path%.}"
path="${path%,}"
[ -n "$path" ] || return 1
last="${path##*/}"
case "$path" in
*/*)
case "$last" in
*.*) return 0 ;;
esac
rel="${path#./}"
[ -e "$DIR/$rel" ]
;;
*.*)
return 0
;;
*)
return 1
;;
esac
}
check_at_path_refs() {
# A per-line `< <(...)` process substitution crashes bash 3.2 (exit
# 133/139, no output) after a few hundred lines: each iteration leaks a
# subshell/fd that the interpreter never reclaims. Prefixing every line
# with a space (so a line-leading @ref still matches the "non-alnum
# before @" rule) and running grep -n once over the whole file keeps the
# same match set and line numbers in a single process substitution.
local file=$1 rel=${1#"$DIR"/} found=0 lineno raw path
while IFS=: read -r lineno raw; do
[ -n "$raw" ] || continue
path="${raw#*@}"
path="${path%.}"
path="${path%,}"
if is_at_file_ref "$path"; then
printf 'ATPATH %s:%s @%s\n' "$rel" "$lineno" "$path"
found=1
fi
done < <(sed 's/^/ /' "$file" | grep -noE '[^A-Za-z0-9]@[A-Za-z0-9._/-]+' || true)
return "$found"
}
check_docs() {
local found=0 f leftover kind
for f in "$DEST/issue-tracker.md" "$DEST/pull-request.md" \
"$DEST/merge-request.md" "$DEST/verification.md"; do
[ -f "$f" ] || continue
# A placeholder inside a sample command (`gh issue view <number>`) is not a
# template artefact; a bare <language> or an alternation such as
# <gh | glab> is. `placeholder:...` and a ```placeholder fence are the
# reserved marker for everything else that still needs a real value:
# unlike an <angle> shape, the keyword itself says so, so nothing has to
# guess whether a given <bracket> is a value to fill in or an example to
# keep.
# shellcheck disable=SC2016 # backticks are literal, not command substitution
leftover=$(grep -oE '<language>|<[^<>]+ \| [^<>]+>|`placeholder:[^`]*`|^```placeholder$' "$f" | head -n 1 || true)
if [ -n "$leftover" ]; then
printf 'PLACEHOLDER %s still carries %s\n' "${f#"$DIR"/}" "$leftover"
found=1
fi
case "$(basename "$f")" in
pull-request.md|merge-request.md) kind=request ;;
*) kind="$(basename "$f" .md)" ;;
esac
check_guarantees "$f" "$kind" || found=1
done
if [ -d "$DEST" ]; then
for f in "$DEST"/*.md; do
[ -f "$f" ] || continue
check_at_path_refs "$f" || found=1
done
fi
if [ "$found" -eq 0 ]; then
echo "documents carry no unresolved placeholder, no @path file reference,"
echo "and are level with every guarantee the current templates pin"
fi
return "$found"
}
install_one() {
local src="$1" dst="$2"
[ -f "$src" ] || { echo "missing template: $src" >&2; exit 2; }
if [ -e "$dst" ] && [ "$FORCE" != true ]; then
printf 'skip %s already exists\n' "${dst#"$DIR"/}"
return 0
fi
cp "$src" "$dst"
printf 'copy %s\n' "${dst#"$DIR"/}"
}
if [ "$MODE" = check ]; then
check_docs
exit $?
fi
case "$FORGE" in
github|gitlab|none) ;;
"") echo "--forge is required to install" >&2; usage; exit 2 ;;
*) echo "unknown forge: $FORGE" >&2; usage; exit 2 ;;
esac
mkdir -p "$DEST"
install_one "$TEMPLATES/verification.md" "$DEST/verification.md"
case "$FORGE" in
github)
install_one "$TEMPLATES/issue-tracker.md" "$DEST/issue-tracker.md"
install_one "$TEMPLATES/pull-request.md" "$DEST/pull-request.md"
;;
gitlab)
install_one "$TEMPLATES/issue-tracker.md" "$DEST/issue-tracker.md"
install_one "$TEMPLATES/pull-request.md" "$DEST/merge-request.md"
;;
esac
echo "Now edit the copies in place: replace every <angle placeholder>, delete"
echo "the lines that do not apply, and leave the template's own sentences alone."
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |