Conventions

Conventions — ai-agent-skills

---

Commit Messages

Format: type(scope): subject

• Subject: imperative mood, lowercase, no trailing period, ≤72 characters
• Scope: the skill name (vault-scribe, handoff) or a repo area (release, ci, readme)
• Body: optional — explain why, not what; wrap at 72 chars
• Footer: Closes #N or Fixes #N for GitHub issues; BREAKING CHANGE: for breaking changes

Types

| Type | When | |------------|---------------------------------------------------------| | feat | New skill or new capability in an existing skill | | fix | Bug fix in a skill's behaviour or instructions | | chore | Release commits, tooling, config — no production change | | docs | README, CHANGELOG, CONTRIBUTING only | | refactor | Skill restructure with no behaviour change | | test | Eval additions or changes |

Release commit — always exactly:

chore(release): cut vX.Y.Z release

Examples

feat(handoff): add RESUME workflow and proactive suggestion trigger

fix(vault-scribe): prevent incompatible TOC directives

Closes #1

---

Branch Names

Pattern: type/issue-number-short-description

feature/14-add-handoff-skill
fix/23-vault-scribe-toc
chore/release-v1-1-0

• feature/ for new skills or new capabilities
• fix/ for bug fixes
• chore/ for release and tooling work
• Always include the issue number when one exists
• 2–4 words, hyphenated, no version dots (use dashes)

---

Pull Requests

Title: same format as a commit — type(scope): subject

Body:

## Summary
- 
- 

## Issue
Closes #N

## Test plan
- [ ] Skill activates on expected triggers
- [ ] Output matches documented format
- [ ] No regressions in adjacent skills

• 2–4 summary bullets
• Always link the issue
• Test plan as checkboxes

---

CHANGELOG Entries (Keep a Changelog 1.1.0)

### Added
- **skill-name** — What was added and why it matters. ([#N](url))

### Changed
- **skill-name** — What changed and the user-visible impact.

### Fixed
- **skill-name** — What was broken and what was fixed. ([#N](url))

• Bold skill name, em dash, plain English, issue link at end
• ### Added for new skills, ### Changed for updates, ### Fixed for bugs
• One bullet per logical change

---

Versioning

Semver from conventional commits since last tag:

| Commit | Bump | |--------------------------------------------|-------| | BREAKING CHANGE or type!: | major | | feat | minor | | fix, chore, docs, refactor, test | patch |

New skill = feat = minor bump. Tag format: vX.Y.Z (annotated tag).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: psenger
• Source: psenger/ai-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.