Give your agent skill its own scripts.

claude -p "Write release notes for this repo." --allowedTools "Skill(release-notes)"

## 2.0.0 (2026-11-01)
 
### Breaking changes
- The `--port` flag is removed. Set the `PORT` environment variable instead. (7fee000)
- Node 22 or newer is now required. Upgrade Node before installing this release. (ac89a29)
 
### Features
- auth: sign in with a passkey (846113c)
 
### Fixes
- api: return 400 on an empty request body (c11d5ab)
 
### Other
Performance work caches the search tokenizer between queries (8fe2d62), adds a self-hosting guide (9203db6), bumps undici to 7.16.0 (7584b07), and updates the README screenshots (ec96b53).
 
Thanks to Asha Rao, Ben Okafor, and Chen Wei.
 
…

release-notes/
├── SKILL.md
├── scripts/
│   └── collect.py
└── references/
    └── format.md

#!/usr/bin/env python3
"""Collect the commits since the last tag as JSON, grouped by Conventional Commit type.
 
The agent runs this instead of reading `git log` itself: the facts come out the
same every time, and only the prose is left to the model.
"""
import argparse
import json
import re
import subprocess
import sys
 
# type(scope)!: subject
HEADER = re.compile(r"^(?P<type>[a-z]+)(?:\((?P<scope>[^)]+)\))?(?P<bang>!)?: (?P<subject>.+)$")
GROUPS = ["feat", "fix", "perf", "refactor", "docs", "test", "build", "ci", "chore"]
FIELD, RECORD = "\x1f", "\x1e"
 
 
def git(repo, *args):
    result = subprocess.run(["git", "-C", repo, *args], capture_output=True, text=True)
    if result.returncode != 0:
        raise RuntimeError(result.stderr.strip() or f"git {' '.join(args)} failed")
    return result.stdout
 
 
def last_tag(repo, until):
    try:
        return git(repo, "describe", "--tags", "--abbrev=0", until).strip()
    except RuntimeError:
        return None  # no tags yet: take the whole history
 
 
def commits(repo, since, until):
    rev = f"{since}..{until}" if since else until
    fmt = FIELD.join(["%h", "%an", "%s", "%b"]) + RECORD
    out = git(repo, "log", "--no-merges", f"--format={fmt}", rev)
    for raw in filter(str.strip, out.split(RECORD)):
        sha, author, subject, body = raw.strip("\n").split(FIELD)
        yield sha, author, subject, body.strip()
 
 
def parse(sha, author, subject, body):
    m = HEADER.match(subject)
    kind = m["type"] if m and m["type"] in GROUPS else "other"
    note = re.search(r"^BREAKING[ -]CHANGE: (.+)$", body, re.M)
    breaking = bool(m and m["bang"]) or bool(note)
    scope = f"{m['scope']}: " if m and m["scope"] else ""
    text = m["subject"] if m else subject
    line = f"{sha} {scope}{text} ({author})"
    return kind, line, author, (f"{sha} {note[1] if note else text}" if breaking else None)
 
 
def main():
    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    ap.add_argument("--repo", default=".", help="path to the git repository (default: .)")
    ap.add_argument("--since", help="start ref, exclusive (default: the latest tag)")
    ap.add_argument("--until", default="HEAD", help="end ref, inclusive (default: HEAD)")
    args = ap.parse_args()
 
    try:
        since = args.since or last_tag(args.repo, args.until)
        items = [parse(*c) for c in commits(args.repo, since, args.until)]
    except RuntimeError as e:
        print(f"collect: {e}", file=sys.stderr)
        return 2
 
    groups = {g: [] for g in GROUPS + ["other"]}
    authors = {}
    for kind, line, author, breaking in items:
        if not breaking:  # listed once, under "breaking", so the notes don't repeat it
            groups[kind].append(line)
        authors[author] = authors.get(author, 0) + 1
 
    json.dump(
        {
            "range": {"from": since, "to": args.until},
            "total": len(items),
            "breaking": [b for *_, b in items if b],
            "groups": {k: v for k, v in groups.items() if v},
            "authors": dict(sorted(authors.items(), key=lambda a: -a[1])),
        },
        sys.stdout,
        indent=2,
    )
    print()
    return 0
 
 
if __name__ == "__main__":
    sys.exit(main())

commit "Asha Rao"   "feat: first public release"
git tag v1.0.0
commit "Asha Rao"   "feat(auth): sign in with a passkey"
commit "Ben Okafor" "fix(api): return 400 on an empty request body"
commit "Asha Rao"   "perf(search): cache the tokenizer between queries"
commit "Ben Okafor" "feat!: require Node 22 or newer"
commit "Chen Wei"   "docs: add a self-hosting guide"
commit "Ben Okafor" "$(printf 'fix(config): read PORT from the environment\n\nBREAKING CHANGE: the --port flag is removed; set PORT instead.')"
commit "Chen Wei"   "chore(deps): bump undici to 7.16.0"
commit "Asha Rao"   "Update README screenshots"

docker build -t skill-tutorial .
docker run --rm skill-tutorial sh -c \
  'fixture/make-fixture.sh ~/demo-app && cd ~/demo-app && python3 ~/tutorial/release-notes/scripts/collect.py'

{
  "range": {
    "from": "v1.0.0",
    "to": "HEAD"
  },
  "total": 8,
  "breaking": [
    "7fee000 the --port flag is removed; set PORT instead.",
    "ac89a29 require Node 22 or newer"
  ],
  "groups": {
    "feat": [
      "846113c auth: sign in with a passkey (Asha Rao)"
    ],
    "fix": [
      "c11d5ab api: return 400 on an empty request body (Ben Okafor)"
    ],
    "perf": [
      "8fe2d62 search: cache the tokenizer between queries (Asha Rao)"
    ],
    "docs": [
      "9203db6 add a self-hosting guide (Chen Wei)"
    ],
    "chore": [
      "7584b07 deps: bump undici to 7.16.0 (Chen Wei)"
    ],
    "other": [
      "ec96b53 Update README screenshots (Asha Rao)"
    ]
  },
  "authors": {
    "Asha Rao": 3,
    "Ben Okafor": 3,
    "Chen Wei": 2
  }
}

docker run --rm skill-tutorial python3 -m unittest -v tests/test_collect.py

test_finds_both_kinds_of_breaking_change (tests.test_collect.CollectTest.test_finds_both_kinds_of_breaking_change) ... ok
test_groups_commits_since_the_last_tag (tests.test_collect.CollectTest.test_groups_commits_since_the_last_tag) ... ok
test_not_a_repo_fails_loudly (tests.test_collect.CollectTest.test_not_a_repo_fails_loudly) ... ok
test_since_overrides_the_tag (tests.test_collect.CollectTest.test_since_overrides_the_tag) ... ok
 
----------------------------------------------------------------------
Ran 4 tests in 0.189s
 
OK

---
name: release-notes
description: Draft release notes from the git history since the last tag. Use when the user asks for release notes, a changelog entry, or what changed since the last release.
allowed-tools: Bash(python3 ${CLAUDE_SKILL_DIR}/scripts/collect.py *) Read
---
 
# Release notes
 
Never read `git log` yourself. The script below collects the commits; your job is the writing.
 
1. From the root of the user's repository, run the collector that ships with this skill:
 
   ```bash
   python3 <this skill's directory>/scripts/collect.py
   ```
 
   It prints JSON: the tag range, breaking changes, commits grouped by type, and authors.
   Pass `--since <ref>` if the user names a different starting point. If it exits non-zero, show the user its error and stop.
 
2. Read `references/format.md` in this skill's directory and write the notes in that format.
 
3. Use only what the JSON contains. Do not invent changes, numbers or migration steps, and keep every commit's short hash.

# Release notes format
 
```markdown
## <next version> (<today, YYYY-MM-DD>)
 
### Breaking changes
- <what changed and what the reader must do> (<sha>)
 
### Features
- <scope>: <subject, rewritten for a user> (<sha>)
 
### Fixes
- …
 
### Other
<one line summing up perf, docs, chore and other commits>
 
Thanks to <authors, most commits first>.
```
 
- Next version: bump major if there are breaking changes, minor if there are features, otherwise patch.
- Leave out a section that would be empty.
- Write for someone who uses the project, not someone who reads its code.

mkdir -p .agents/skills .claude
cp -r release-notes .agents/skills/
ln -s ../.agents/skills .claude/skills   # Claude Code reads .claude/skills only

claude -p "Write release notes for this repo." --model claude-haiku-5-5 --allowedTools "Skill(release-notes)"

docker run --rm -e ANTHROPIC_API_KEY skill-tutorial ./try.sh claude

claude -p "Write release notes for this repo." --model claude-haiku-5-5 \
  --allowedTools "Skill(release-notes)" --output-format stream-json --verbose \
  | jq -r 'select(.type=="assistant") | .message.content[]? | select(.type=="tool_use") | "\(.name) \(.input|tojson)"'

Skill {"skill":"release-notes"}
Bash {"command":"python3 /home/node/demo-app/.claude/skills/release-notes/scripts/collect.py; echo \"EXIT=$?\"", …}
Bash {"command":"python3 /home/node/demo-app/.claude/skills/release-notes/scripts/collect.py", …}
Read {"file_path":"/home/node/demo-app/.claude/skills/release-notes/references/format.md"}

pi -p "Write release notes for this repo." --model "anthropic/claude-haiku-5-5" --approve --no-session

docker run --rm -e ANTHROPIC_API_KEY skill-tutorial ./try.sh pi

## 2.0.0 (2026-11-01)
 
### Breaking changes
- The `--port` flag is removed. Set the `PORT` environment variable instead. (7fee000)
- Node 22 or newer is now required. (ac89a29)
 
### Features
- auth: sign in with a passkey. (846113c)
 
### Fixes
- api: return 400 on an empty request body. (c11d5ab)
 
### Other
Performance, docs, dependency and maintenance work: the search tokenizer is now cached between queries (8fe2d62), a self-hosting guide was added (9203db6), undici was bumped to 7.16.0 (7584b07), and the README screenshots were updated (ec96b53).
 
Thanks to Asha Rao, Ben Okafor and Chen Wei.
 
…

<available_skills>
  <skill>
    <name>release-notes</name>
    <description>Draft release notes from the git history since the last tag. Use when the user asks for release notes, a changelog entry, or what changed since the last release.</description>
    <location>/home/node/demo-app/.agents/skills/release-notes/SKILL.md</location>
  </skill>
</available_skills>

    for kind, line, author, breaking in items:
        if not breaking:  # listed once, under "breaking", so the notes don't repeat it
            groups[kind].append(line)

FROM node:24-bookworm-slim
 
RUN apt-get update \
 && apt-get install -y --no-install-recommends git python3 ca-certificates \
 && rm -rf /var/lib/apt/lists/*
 
# Two harnesses that both load SKILL.md: Claude Code and Pi.
RUN npm install -g @anthropic-ai/claude-code@2.1.316 \
 && npm install -g --ignore-scripts @earendil-works/pi-coding-agent@1.4.0
 
# Agents refuse to skip permission prompts as root, and you shouldn't want them to.
USER node
WORKDIR /home/node/tutorial
COPY --chown=node:node . .
RUN git config --global user.name tutorial && git config --global user.email tutorial@example.com

git clone https://github.com/a2coder-tutorials/agent-skill-with-scripts && cd agent-skill-with-scripts
docker build -t skill-tutorial .
docker run --rm -e ANTHROPIC_API_KEY skill-tutorial ./try.sh claude

I couldn't generate the release notes yet. The collector script needs Bash permission, and the call came back as "requires approval" without running.
 
I haven't worked around it. The skill says not to read `git log` directly, so I didn't try that.