dev-agent-skills

Agent skills and hooks for development workflows - Git, GitHub, skill authoring, safety guardrails, public-repo privacy, and decision records.

These skills are designed for Claude Code, the CLI tool by Anthropic.

Why these skills?

Claude Code already knows how to commit, create PRs, and review code. But without structured guidance it tends to:

• Use inconsistent commit formats across a session
• Skip target branch confirmation and create PRs against the wrong branch
• Not search for task documentation or validate task completion before opening a PR
• Suggest labels that don't exist in the project
• Process review comments in random order instead of by severity
• Use the wrong GitHub API syntax for replying to threads (-f instead of --input -)
• Generate verbose merge messages that clutter the git log
• Merge without verifying all review comments have been addressed

These skills add structured workflows that prevent these issues. They don't replace Claude's capabilities - they guide them through the right sequence of steps.

There are no official Anthropic skills for Git/GitHub workflows. This plugin fills that gap.

Quick install

# Add marketplace
/plugin marketplace add fvadicamo/dev-agent-skills

# Install plugins
/plugin install github-workflow@dev-agent-skills
/plugin install skill-authoring@dev-agent-skills
/plugin install guardrails@dev-agent-skills
/plugin install privacy-guard@dev-agent-skills
/plugin install decision-records@dev-agent-skills

How skills work

Skills are model-invoked - Claude automatically activates them based on your request:

• "Create a commit" -> activates git-commit
• "Open a PR" -> activates github-pr-creation
• "Merge the PR" -> activates github-pr-merge
• "Address review comments" -> activates github-pr-review
• "Help me create a skill" -> activates creating-skills
• "Set up the privacy guard on this public repo" -> activates privacy-guard
• "Record this decision" / "check our ADRs" -> activates decision-records

Plugin: github-workflow

Skills for Git and GitHub workflows following Conventional Commits.

git-commit

Creates commits following Conventional Commits format with type/scope/subject.

What it adds over Claude's default behavior:

Additional features:

• Checks CLAUDE.md for project-specific commit conventions
• Extra commit type security beyond standard CC

github-pr-creation

Creates Pull Requests with automated validation, task tracking, and label suggestions.

What it adds over Claude's default behavior:

github-pr-merge

Merges Pull Requests after validating a pre-merge checklist.

What it adds over Claude's default behavior:

github-pr-review

Handles PR review comments and feedback resolution.

What it adds over Claude's default behavior:

Plugin: skill-authoring

creating-skills

Guide for creating Claude Code skills following Anthropic's official best practices.

What it adds over Claude's default behavior:

Claude knows the basics of skill creation, but this skill provides a comprehensive, up-to-date reference covering features that Claude may not know about or consistently apply.

• Complete frontmatter reference (all 10 fields including allowed-tools, context, agent, hooks)
• Invocation control matrix (disable-model-invocation, user-invocable)
• Dynamic features: context injection (!`cmd`), string substitutions ($ARGUMENTS), subagent execution
• Degrees of freedom concept for matching specificity to task fragility
• Directory structure with scripts/, references/, and assets/ resource types
• Description formula, naming conventions, progressive disclosure patterns

Comparison with the official skill-creator

This skill complements the official skill-creator from Anthropic. They serve different purposes and can be used together.

In short: this skill is a practical, up-to-date reference for all available features. The official skill is a conceptual guide with scaffolding/packaging tools. Install both for the most complete experience.

Plugin: guardrails

Safety guardrails for running Claude Code with reduced supervision (for example under --dangerously-skip-permissions). It currently ships one PreToolUse hook; more checks may follow. Unlike the skills, the hook is not model-invoked: it runs automatically on every Bash tool call, before the command executes.

guard-destructive

What it adds over Claude's default behavior:

The hook is harness-only - it adds no token cost to the model context.

Plugin: privacy-guard

For people who run private infrastructure (a home lab, a VPS fleet, client machines) and also publish open-source repos. The public repo is the boundary: hostnames, internal project names, local usernames, home paths and VPN addresses must not cross it, in files or anywhere else.

privacy-guard

What it adds over Claude's default behavior:

Setup is per-repo and scripted by the skill: copy check_privacy.sh into scripts/, fill .local/privacy-denylist.txt from the shipped placeholder template, add the gitleaks + denylist blocks to .pre-commit-config.yaml, then arm-check it with a throwaway file containing a known token. A repo that already sets core.hooksPath cannot run pre-commit install; the skill documents the variant that calls the script from the existing hook instead.

Note the deliberate trade-offs: the guard is client-side and only protects commits made from a machine that has the denylist; it scans what a commit adds, so it stops new leaks and does not audit history; and it does not cover pastes into the GitHub web UI. That is what the behavioral rules are for.

Plugin: decision-records

For a repo that already keeps decision records (ADRs) and has stopped trusting them: numbers that collide, an index that no longer matches the directory, a record that says it was superseded and does not say by what. The skill writes records, and mainly holds a collection to its own convention.

decision-records

What it adds over Claude's default behavior:

check-decisions.sh [--require "A,B"] [--status "a,b"] [--portable] DIR
# 0 clean, 1 violations, 2 usage error or nothing to check

Where this sits next to what already exists. ADR linters are not new and some are much more capable: mdbook-lint ships 17 ADR rules, madr-lint covers MADR v2 to v4 and ships its own Claude skills, adrkit finds supersession cycles and contradicting decisions. They all validate against a published spec, Nygard or MADR, chosen by auto-detecting between those. A collection whose convention is neither, say date-prefixed filenames with a house section set, has its own convention reported to it as violations. That case is what this one is for, and it needs no toolchain: it is one bash script.

Deliberate limits. It ships no template file into your repo, because a template beside the records is a second home for the convention and the two diverge in silence. It does not scan for private tokens: hostnames, instance names and identity are privacy-guard's denylist, and a second copy of that list here would be the same mistake with worse consequences. --portable covers only what breaks when a record is copied: absolute paths, and links that climb out of the collection directory.

Development

Three plugins ship executable logic, and each has a regression suite:

bash plugins/guardrails/tests/run.sh        # guard-destructive.sh
bash plugins/privacy-guard/tests/run.sh     # check_privacy.sh, check-sync.sh
bash plugins/decision-records/tests/run.sh  # check-decisions.sh

All exit non-zero on failure and run on macOS and Linux. Each accepts an override
(GUARD_HOOK=, PRIVACY_SCRIPT=, SYNC_SCRIPT=, CHECK_SCRIPT=) that points it at a
candidate script: point it at the version from before a fix and the suite must go red. A
bench nobody has seen fail says nothing. Stronger where a suite claims to hold one guard
down: remove that guard from the real script and check that its case goes red and the
others do not, because a case can pass beside the guard it names.

After cloning the repo to work on either, enable the shared git hooks (they live in the
versioned .githooks/, not in .git/hooks/):

git config core.hooksPath .githooks      # one-time, per clone

With that set, a pre-commit hook runs a plugin's suite whenever that plugin's shipped
files or its tests are staged, and blocks the commit on a regression (bypass once with
git commit --no-verify). It also runs this repo's own privacy check on the staged
lines. There is no CI: that hook is the only gate, and it only fires for whoever set
core.hooksPath.

If you change anything under plugins/<name>/, bump that plugin's version in
plugins/<name>/.claude-plugin/plugin.json and in its marketplace.json entry. The
pre-commit hook blocks the commit otherwise, and the reason is not bookkeeping:
claude plugin update compares the version number, so a change shipped under a frozen
number never reaches an installed copy — the node keeps running the old files while the
version claims they are current. Everything in the plugin directory is shipped, tests
included. .githooks/tests/run.sh benches that check.

See each suite's tests/README.md for the case format and CLAUDE.md for contributor
guidance.

License

MIT License - see LICENSE for details.

{
  "name": "dev-agent-skills",
  "owner": {
    "name": "Francesco Vadicamo",
    "email": "fvadicamo@gmail.com"
  },
  "metadata": {
    "description": "Agent skills and hooks for development workflows - Git, GitHub, skill authoring, safety guardrails, public-repo privacy, and decision records",
    "version": "1.16.0"
  },
  "plugins": [
    {
      "name": "github-workflow",
      "description": "Git commit, PR creation, review, and merge skills following Conventional Commits",
      "source": "./plugins/github-workflow",
      "version": "1.4.2",
      "strict": false
    },
    {
      "name": "skill-authoring",
      "description": "Guide for creating Claude Code skills following Anthropic's best practices",
      "source": "./plugins/skill-authoring",
      "version": "1.4.0",
      "strict": false
    },
    {
      "name": "guardrails",
      "description": "Safety guardrails for running Claude Code with reduced supervision. The guard-destructive PreToolUse hook matches against a normalized view of each command (heredoc bodies and comments stripped, quoted strings neutralized except interpreter arguments like ssh / sh -c / eval / su / doas), so a command that merely mentions a destructive pattern is not flagged. It hard-blocks catastrophic Bash commands (rm -rf /, rsync --delete, docker volume rm) and makes rm/rmdir scope-aware: operations whose operands all resolve inside the allowed workspace (the session project root, temp dirs, any $GUARD_ALLOWED_EXTRA root, or a variable assigned from a bare mktemp earlier in the same command) run silently, while anything outside it (or any glob/variable/escape it cannot resolve) raises a single reflective confirmation. git reset --hard / clean / restore, shred, dd, mkfs still always prompt.",
      "source": "./plugins/guardrails",
      "version": "1.7.6",
      "strict": false
    },
    {
      "name": "privacy-guard",
      "description": "Keeps private infrastructure details out of public repositories. Ships the privacy-guard skill: session rules for what must never cross the public boundary, plus a per-repo pre-commit gate built on a gitignored local denylist and gitleaks. The denylist is never committed, so the hook is a no-op for external contributors and in CI while gitleaks still covers generic secrets.",
      "source": "./plugins/privacy-guard",
      "version": "1.3.3",
      "strict": false
    },
    {
      "name": "decision-records",
      "description": "Creates, supersedes and validates decision records (ADRs) against the convention a collection already follows, instead of against a published spec it may never have adopted. Ships the decision-records skill: a propose-then-write flow that never rewrites an accepted record, and check-decisions.sh, a validator that deduces the filename scheme, section set and status vocabulary from the records already present and reports eight classes of violation with a stable code and an exit status. Ships no template into the target repo, and delegates private-token scanning to privacy-guard rather than keeping a second denylist.",
      "source": "./plugins/decision-records",
      "version": "0.3.0",
      "strict": false
    }
  ]
}