Skip to content

Commit 6fcb769

Browse files
committed
Add skill installer and maintainer templates
1 parent f099782 commit 6fcb769

8 files changed

Lines changed: 250 additions & 2 deletions

File tree

.github/ISSUE_TEMPLATE/config.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
blank_issues_enabled: true
Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: Workflow improvement
2+
description: Suggest a maintainer workflow, skill, example, or validation improvement.
3+
title: "[workflow] "
4+
labels: ["workflow"]
5+
body:
6+
- type: textarea
7+
id: problem
8+
attributes:
9+
label: Maintainer problem
10+
description: What repeated maintenance task or false-pass path should this improve?
11+
validations:
12+
required: true
13+
- type: textarea
14+
id: proposed
15+
attributes:
16+
label: Proposed reusable pattern
17+
description: Describe the smallest reusable workflow, skill, example, or script that would help.
18+
validations:
19+
required: true
20+
- type: textarea
21+
id: evidence
22+
attributes:
23+
label: Evidence and validation
24+
description: What would prove the improvement works?
25+
validations:
26+
required: true
27+
- type: checkboxes
28+
id: safety
29+
attributes:
30+
label: Publication safety
31+
options:
32+
- label: This can be described without private project names, secrets, local paths, or account-specific context.
33+
required: true

.github/PULL_REQUEST_TEMPLATE.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
## Summary
2+
3+
- Describe the change in one or two bullets.
4+
5+
## Maintenance Surface
6+
7+
- [ ] Issue triage
8+
- [ ] Prompt/skill workflow
9+
- [ ] Validation or release tooling
10+
- [ ] Documentation or example
11+
12+
## Validation
13+
14+
- [ ] `bash scripts/validate.sh`
15+
- [ ] Public/private context reviewed
16+
- [ ] Release notes or changelog updated when user-facing behavior changed
17+
18+
## Risk
19+
20+
Name any false-pass path, private-context risk, or follow-up that should remain visible after merge.

CHANGELOG.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
# Changelog
22

3+
## 0.3.0 - 2026-06-01
4+
5+
- Added a skill installer script and install/use guide so maintainers can adopt the kit more directly.
6+
- Added GitHub issue and pull request templates to support public triage, review, validation, and release habits.
7+
38
## 0.2.0 - 2026-06-01
49

510
- Added a conversation capture receipts skill for turning rough chat, voice-note, or inbox-dump input into human-useful no-write receipts.

README.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,8 +37,8 @@ cp templates/AGENTS.md AGENTS.md
3737
Copy one or more skills into your local Codex skills directory:
3838

3939
```bash
40-
mkdir -p ~/.codex/skills
41-
cp -R skills/* ~/.codex/skills/
40+
bash scripts/install-skills.sh --dry-run
41+
bash scripts/install-skills.sh
4242
```
4343

4444
Validate this repository:
@@ -60,11 +60,13 @@ bash scripts/check-publication-risk.sh
6060
- `skills/oss-maintainer-triage/SKILL.md` - issue, PR, and bounty-style evidence triage
6161
- `skills/milestone-review/SKILL.md` - milestone and adversarial completion review workflow
6262
- `docs/maintenance-model.md` - the operating model behind the kit
63+
- `docs/install-and-use.md` - installer and adoption guide
6364
- `docs/workflows.md` - copyable maintainer workflows
6465
- `docs/publication-risk.md` - how to screen workflow packs before publishing
6566
- `examples/` - sanitized example packets and receipts
6667
- `docs/codex-for-oss-application.md` - application packet and field-ready answers
6768
- `scripts/validate.sh` - local validation checks
69+
- `scripts/install-skills.sh` - install all or selected skills into a Codex skills directory
6870
- `scripts/check-publication-risk.sh` - conservative private-context leak scanner
6971

7072
## Maintenance Posture

docs/install-and-use.md

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Install And Use
2+
3+
Codex Operator Kit is meant to be copied into real maintainer work. The fastest path is to install one or more skills into a Codex skills directory, then use the workflow docs and examples as prompts or checklists.
4+
5+
## List Skills
6+
7+
```bash
8+
bash scripts/install-skills.sh --list
9+
```
10+
11+
Current skills:
12+
13+
- `conversation-capture-receipts`
14+
- `milestone-review`
15+
- `oss-maintainer-triage`
16+
17+
## Dry Run
18+
19+
```bash
20+
bash scripts/install-skills.sh --dry-run
21+
```
22+
23+
The installer replaces same-named skill directories in the target. Use `--dry-run` first when installing into an existing Codex setup.
24+
25+
## Install All Skills
26+
27+
```bash
28+
bash scripts/install-skills.sh
29+
```
30+
31+
By default, the script installs to:
32+
33+
```text
34+
${CODEX_HOME:-$HOME/.codex}/skills
35+
```
36+
37+
Set a target explicitly when needed:
38+
39+
```bash
40+
bash scripts/install-skills.sh --target "$HOME/.codex/skills"
41+
```
42+
43+
## Install One Skill
44+
45+
```bash
46+
bash scripts/install-skills.sh conversation-capture-receipts
47+
```
48+
49+
## Use The Kit Without Installing
50+
51+
You can also copy individual files into a repository:
52+
53+
- `templates/AGENTS.md` for prompt intake and completion review
54+
- `docs/workflows.md` for issue triage, capture receipts, PR review, release readiness, publication risk, and completion critic gates
55+
- `examples/` for sanitized examples
56+
57+
## Validate Before Publishing Changes
58+
59+
```bash
60+
bash scripts/validate.sh
61+
```
62+
63+
Validation checks required files, skill front matter, application-field lengths, and publication-risk patterns.

scripts/install-skills.sh

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
#!/usr/bin/env bash
2+
set -euo pipefail
3+
4+
root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
5+
target="${CODEX_SKILLS_DIR:-${CODEX_HOME:-$HOME/.codex}/skills}"
6+
dry_run=0
7+
list_only=0
8+
skills=()
9+
10+
usage() {
11+
cat <<'USAGE'
12+
Usage: bash scripts/install-skills.sh [--target DIR] [--dry-run] [--list] [skill...]
13+
14+
Installs Codex Operator Kit skills into a Codex skills directory.
15+
16+
Examples:
17+
bash scripts/install-skills.sh --list
18+
bash scripts/install-skills.sh --dry-run
19+
bash scripts/install-skills.sh conversation-capture-receipts
20+
bash scripts/install-skills.sh --target "$HOME/.codex/skills"
21+
USAGE
22+
}
23+
24+
while [[ $# -gt 0 ]]; do
25+
case "$1" in
26+
--target)
27+
[[ $# -ge 2 ]] || { echo "--target requires a directory" >&2; exit 2; }
28+
target="$2"
29+
shift 2
30+
;;
31+
--dry-run)
32+
dry_run=1
33+
shift
34+
;;
35+
--list)
36+
list_only=1
37+
shift
38+
;;
39+
-h|--help)
40+
usage
41+
exit 0
42+
;;
43+
-*)
44+
echo "unknown option: $1" >&2
45+
usage >&2
46+
exit 2
47+
;;
48+
*)
49+
skills+=("$1")
50+
shift
51+
;;
52+
esac
53+
done
54+
55+
available=()
56+
while IFS= read -r -d '' skill_dir; do
57+
available+=("$(basename "$skill_dir")")
58+
done < <(find "$root/skills" -mindepth 1 -maxdepth 1 -type d -print0 | sort -z)
59+
60+
if [[ "$list_only" -eq 1 ]]; then
61+
printf '%s\n' "${available[@]}"
62+
exit 0
63+
fi
64+
65+
if [[ "${#skills[@]}" -eq 0 ]]; then
66+
skills=("${available[@]}")
67+
fi
68+
69+
for skill in "${skills[@]}"; do
70+
if [[ ! "$skill" =~ ^[a-z0-9-]+$ ]]; then
71+
echo "invalid skill name: $skill" >&2
72+
echo "skill names must use lowercase letters, numbers, and hyphens" >&2
73+
exit 1
74+
fi
75+
if [[ ! -d "$root/skills/$skill" ]]; then
76+
echo "unknown skill: $skill" >&2
77+
echo "available skills:" >&2
78+
printf ' %s\n' "${available[@]}" >&2
79+
exit 1
80+
fi
81+
done
82+
83+
if [[ "$dry_run" -eq 0 ]]; then
84+
mkdir -p "$target"
85+
fi
86+
87+
for skill in "${skills[@]}"; do
88+
src="$root/skills/$skill"
89+
dst="$target/$skill"
90+
if [[ "$dry_run" -eq 1 ]]; then
91+
echo "would install $skill -> $dst"
92+
else
93+
if [[ -e "$dst" ]]; then
94+
echo "replacing existing $dst"
95+
fi
96+
rm -rf "$dst"
97+
cp -R "$src" "$dst"
98+
echo "installed $skill -> $dst"
99+
fi
100+
done

scripts/validate.sh

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,10 @@ required=(
1010
"SECURITY.md"
1111
"CHANGELOG.md"
1212
"LICENSE"
13+
".github/PULL_REQUEST_TEMPLATE.md"
14+
".github/ISSUE_TEMPLATE/config.yml"
15+
".github/ISSUE_TEMPLATE/workflow-improvement.yml"
16+
"docs/install-and-use.md"
1317
"docs/maintenance-model.md"
1418
"docs/publication-risk.md"
1519
"docs/workflows.md"
@@ -22,6 +26,7 @@ required=(
2226
"skills/oss-maintainer-triage/SKILL.md"
2327
"skills/milestone-review/SKILL.md"
2428
"templates/AGENTS.md"
29+
"scripts/install-skills.sh"
2530
"scripts/check-publication-risk.sh"
2631
)
2732

@@ -47,6 +52,25 @@ done
4752

4853
"$root/scripts/check-publication-risk.sh"
4954

55+
"$root/scripts/install-skills.sh" --list >/dev/null
56+
"$root/scripts/install-skills.sh" --dry-run >/dev/null
57+
58+
install_tmp="$(mktemp -d)"
59+
trap 'rm -rf "$install_tmp"' EXIT
60+
while IFS= read -r -d '' skill_dir; do
61+
skill_name="$(basename "$skill_dir")"
62+
if ! grep -q -- "- \`$skill_name\`" "$root/docs/install-and-use.md"; then
63+
echo "install guide is missing skill: $skill_name" >&2
64+
exit 1
65+
fi
66+
67+
"$root/scripts/install-skills.sh" --target "$install_tmp/skills" "$skill_name" >/dev/null
68+
if [[ ! -s "$install_tmp/skills/$skill_name/SKILL.md" ]]; then
69+
echo "installer smoke test failed for: $skill_name" >&2
70+
exit 1
71+
fi
72+
done < <(find "$root/skills" -mindepth 1 -maxdepth 1 -type d -print0 | sort -z)
73+
5074
python3 - "$root/docs/codex-for-oss-application.md" <<'PY'
5175
import re
5276
import sys

0 commit comments

Comments
 (0)