⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
decision-records
Creates, supersedes and validates decision records (ADRs) against the convention a collection already follows, instead of imposing a published one. Use when the user wants to record a decision, write an ADR, supersede an existing decision, audit or lint a decisions folder, check that an ADR index is in sync, or asks "why did we decide X". Deduces the filename scheme, section set and status vocabulary from the records already there; ships a validator with an exit code, so the audit is a check and not an opinion.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
// README
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 (
-finstead 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:
| Without this skill | With this skill |
|---|---|
| Inconsistent commit format across a session | Enforces CC format with required scope, max 50 chars, imperative tense |
| Ignores existing commit style in the project | Dynamic context injection loads recent commits so Claude matches the style |
| Sometimes uses generic messages ("update code") | Strict rules against vague messages |
| No HEREDOC for multi-line commits | Provides HEREDOC pattern for clean multi-line messages |
Additional features:
- Checks CLAUDE.md for project-specific commit conventions
- Extra commit type
securitybeyond standard CC
github-pr-creation
Creates Pull Requests with automated validation, task tracking, and label suggestions.
What it adds over Claude's default behavior:
| Without this skill | With this skill |
|---|---|
| Often skips target branch confirmation | Always asks user to confirm base branch |
| Doesn't search for task documentation | Searches Kiro, Cursor, Trae, GitHub Issues, and generic paths for task specs |
| No task completion validation | Maps commits to tasks and reports missing sub-tasks before creating PR |
| Suggests labels that may not exist in the project | Checks gh label list first, matches available labels, suggests creating missing ones |
| Generic PR body | 7 type-specific templates (feature, release, bugfix, hotfix, refactoring, docs, CI/CD) |
| May skip tests | Tests must pass before PR creation |
github-pr-merge
Merges Pull Requests after validating a pre-merge checklist.
What it adds over Claude's default behavior:
| Without this skill | With this skill |
|---|---|
| May merge without checking review comments | Detects unreplied comments via jq query, stops merge and redirects to review skill |
| Inconsistent merge strategy | Always merge commit (--merge), never squash/rebase |
| Verbose or empty merge messages | Concise format: 3-5 bullets + reviews/tests/refs (~10 lines max) |
| May skip CI/lint checks | Full pre-merge checklist (tests, lint, CI, comments) with summary shown to user |
| Forgets branch cleanup | Auto-deletes remote branch, switches to develop and pulls |
github-pr-review
Handles PR review comments and feedback resolution.
What it adds over Claude's default behavior:
| Without this skill | With this skill |
|---|---|
| Processes comments in random order | Classifies by severity (CRITICAL > HIGH > MEDIUM > LOW) and processes in order |
| No severity detection | Detects Gemini badges, Cursor HTML comments, and keyword-based severity |
| One commit per fix regardless of impact | Batch strategy: separate commits for functional fixes, single batch for cosmetic |
May use -f in_reply_to=... (broken) | Uses correct --input - JSON syntax for thread replies |
| Generic or no replies to threads | Standard templates: Fixed, Won't fix, By design, Deferred, Acknowledged |
| Triggers bot review loops on every push | Strategies to avoid loops: batch pushes, draft PR, skip keywords |
| Forgets to submit formal review | Prompts gh pr review with appropriate flag (approve/request-changes/comment) |
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/, andassets/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.
| Feature | This skill | Official skill-creator |
|---|---|---|
| Complete frontmatter reference (10 fields) | Yes | No (only 5 fields) |
| Invocation control matrix | Yes | No |
Dynamic context injection (!`cmd`) | Yes, with examples | No |
String substitutions ($ARGUMENTS, $1) | Yes | No |
Subagent execution (context: fork) | Yes, with example | No |
| Discovery hierarchy | Yes | No |
| Context budget (2%, 16k fallback) | Yes | No |
| Skills/commands unification | Yes | No |
| Frontmatter validation rules | Yes | No |
| 6 feature-specific examples | Yes | No |
Scaffolding script (init_skill.py) | No | Yes |
Packaging script (package_skill.py) | No | Yes |
Validation script (quick_validate.py) | No | Yes |
| Workflow patterns reference | No | Yes |
| Output patterns reference | No | Yes |
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; mo
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
plugins/decision-records/skills/decision-records/SKILL.md7.8 KBupstream ↗
--- name: decision-records description: Creates, supersedes and validates decision records (ADRs) against the convention a collection already follows, instead of imposing a published one. Use when the user wants to record a decision, write an ADR, supersede an existing decision, audit or lint a decisions folder, check that an ADR index is in sync, or asks "why did we decide X". Deduces the filename scheme, section set and status vocabulary from the records already there; ships a validator with an exit code, so the audit is a check and not an opinion. argument-hint: "[new | supersede <ref> | check [<dir>]]" allowed-tools: Bash(ls:*), Bash(find:*), Bash(cat:*), Bash(grep:*), Bash(bash:*), Read, Write, Edit --- # decision-records Decision records are cheap to write and expensive to trust. The expensive part is the collection: numbers that collide, an index that stopped matching the directory, a record that says it was superseded and does not say by what. This skill writes records and, mainly, **holds a collection to its own convention**. ## What this skill does not do - **It does not ship a template file into the target repo.** The skeleton is in this file. A `template.md` next to the records is a second home for the convention, and two homes diverge in silence: the template keeps a section the records dropped a year ago and nothing says which one is the convention. The most-installed prior art (`affaan-m/ECC`, `skills/architecture-decision-records`) creates one; this is a deliberate departure, not an oversight. - **It does not check for private tokens.** Hostnames, instance names, IP ranges and personal identity belong to the `privacy-guard` skill, whose denylist is gitignored on purpose. Duplicating that list here would put the same list in two places, which is the failure above with worse consequences. The `--portable` check covers only what breaks when a record is **copied**: absolute paths, and links that climb out of the collection. - **It does not rewrite an accepted record to change its mind.** See *Superseding*. ## Step 0, always: read the collection before writing anything Find the collection. The three defaults in the wild are all different, so look, do not assume: `doc/adr` (adr-tools), `docs/adr` (the ECC skill), `docs/decisions` (MADR 4.0.0). ```sh bash "${CLAUDE_PLUGIN_ROOT}/skills/decision-records/scripts/check-decisions.sh" <dir> ``` Its first block reports what the collection does: filename scheme, where the status lives, the status vocabulary in use, the sections most records carry, and the index. **That report is the convention.** Everything you write next matches it, including the parts you would have written differently. If the collection is empty or does not exist, ask once, and offer both schemes: | Scheme | Gains | Costs | |---|---|---| | `NNNN-slug.md` **(recommend this one)** | a short reference you can say out loud: "see 0007" | two parallel PRs both take the next number and both merge ([adr/madr#28](https://github.com/adr/madr/issues/28), open since 2020, no convention adopted); breaks on copy between repos and on reordering | | `YYYY-MM-DD-slug.md` | no collision between parallel PRs, survives a copy into another repo, sorts correctly | no short reference: you cite a record by its whole filename | Recommend the numbered scheme unless the repo takes decisions through parallel PRs, which is the case the date scheme was invented for (`log4brains` adopted it in that thread for exactly this reason). Nothing else about the record changes with the choice. ## Creating a record 1. **Draft, do not write.** Compose the record and show it in the conversation. 2. **Wait for explicit approval.** "Looks good", "yes, write it". Silence is not approval. If the user declines, discard it: write nothing, leave no file behind. 3. **Write** it to the collection, named for the deduced scheme, numbered `max + 1` when the scheme is numbered (never reuse a number, not even of a deleted record). 4. **Update the index** in the same turn, if the collection keeps one. A record written and not indexed is the defect the `INDEX` check exists to catch; do not create it and then report it. 5. **Re-run the validator.** It is the only thing that tells you the write landed inside the convention rather than beside it. The skeleton, for a collection that has none to deduce. Sections adapt to the collection's own set when there is one: ```markdown # NNNN. <decision in a short noun phrase> ## Status proposed ## Context What forced a decision now. The constraints, the pressure, what was true at the time. Not the solution. ## Decision What we do, in the present tense: "We use X". One or two sentences. ## Consequences What gets easier, what gets harder, what we now owe. Both directions, honestly: a record with only benefits documents an advert, not a decision. ``` Two rules about content, from Nygard's original and worth keeping: write **why**, because the what is already visible in the code; and record the alternative that was rejected and the reason, because the next person will otherwise re-propose it. ## Superseding An accepted record is a statement about a moment. **Never edit one to change its mind** — that destroys the only evidence of why the old decision made sense, and the record's whole value is that evidence. 1. Write a new record (the flow above), whose Status references the old one. 2. Change the **old** record's status to `superseded by <new ref>`, and nothing else in it. 3. Update the index for both. Use the reference form the collection already uses. The validator resolves markdown links (`[0009](0009-slug.md)`), `ADR-0009`, and a bare number, and reports one that resolves to nothing. A bare number is only resolvable where the filename scheme carries one; under a dated or free-form scheme records cite each other by filename, and the validator says it left those references unchecked rather than calling them all dangling. ## Validating ```sh check-decisions.sh [--require "A,B"] [--status "a,b"] [--portable] DIR # 0 clean, 1 violations, 2 usage error or nothing to check ``` Eight checks, each printing a stable code so the reason is readable and greppable: | Code | What it catches | |---|---| | `NAME` | a filename outside the scheme the other records use, or a collection that agrees on no scheme at all. Four schemes are recognised: `YYYY-MM-DD-slug.md`, `NNNN-slug.md`, `<prefix>-NNN-slug.md`, and free-form | | `SECTION` | a section missing from a record that more than half the collection carries | | `STATUS` | a record with no status, in a collection whose other records have one. Four forms are read: frontmatter `status:`, a `- Status:` bullet, `**Status**:`, a `## Status` section. When **no** record has one, that is not eight violations, it is one line in *checks that did not run* | | `DRIFT` | one status spelled two ways: `Accepted` beside `accepted` | | `SUPERSEDE` | a reference that resolves to nothing, or a status claiming supersession that names no replacement | | `DUPLICATE` | two records claiming one identifier, where the scheme carries one (`NNNN-slug.md`, `ADR-031-slug.md`); under a dated or free-form scheme the whole filename is the identifier and cannot collide | | `INDEX` | the index and the directory disagreeing, **in either direction** | | `PORTABLE` | with `--portable`: absolute paths, and links that climb out of the collection | Three deliberate properties: - **A check that cannot apply says so.** Every run ends with *checks that did not run* on stderr, naming each check and why. Without it a reader sees `OK: no violations` and has no way to know how many of the eight were in a position to say anything, and silence reads as a pass. Two shipped defects came from exactly that gap. - **Nothing is imposed.** The required sections are the ones most records already have, the filename scheme is the one most records already use. `--require` and `--status` are there forREADME.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/fvadicamo-dev-agent-skills-plugins-decision-records-skills-decision-records.md