Skip to content

Commit a1c53f5

Browse files
jeffreyguentherjeffreyguenther
committed
chore(agents): Add lifecycle skills
- commit: conventional commits with type(scope) format, atomic splitting - pull-request: structured PRs with what/why sections - define-feature: requirements gathering and task decomposition - build-feature: end-to-end feature workflow (branch, TDD, commit, PR)
1 parent c65a7c3 commit a1c53f5

4 files changed

Lines changed: 363 additions & 0 deletions

File tree

‎.claude/skills/build-feature/SKILL.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
name: build-feature
3+
description: Work a feature end to end. Use when the user invokes /build-feature or asks to build, implement, or work on a feature. Covers the full lifecycle from branch creation through implementation, commits, and PR.
4+
---
5+
6+
# Feature
7+
8+
Work a feature through its full lifecycle: branch, plan, implement, commit, PR.
9+
10+
## Workflow
11+
12+
1. Clarify the feature requirements — ask the user if anything is ambiguous
13+
2. Create a feature branch off `main`
14+
3. Plan the implementation approach
15+
4. Implement in small, focused iterations
16+
5. Invoke the `/commit` skill after each logical unit of work — do not commit manually
17+
6. Run `pnpm build` before each commit to check for TypeScript errors
18+
7. Create a PR using `/pull-request` conventions when the feature is complete
19+
20+
## Branch Naming
21+
22+
```
23+
type/short-description
24+
```
25+
26+
- Use the commit type as prefix: `feat/`, `fix/`, `refactor/`, etc.
27+
- Use kebab-case for the description
28+
- Keep it short and descriptive
29+
30+
Examples:
31+
```
32+
feat/listing-support
33+
fix/deploy-theme-rename
34+
refactor/extract-settings-patterns
35+
```
36+
37+
## Planning
38+
39+
Before writing code:
40+
41+
1. Explore the relevant parts of the codebase to understand existing patterns
42+
2. Identify which files need to change and what new files are needed
43+
3. Present the plan to the user for approval before implementing
44+
4. If the approach is unclear, ask the user — don't guess
45+
46+
## Implementation
47+
48+
Use test-driven development:
49+
50+
1. Write a failing test for the next piece of functionality
51+
2. Run `pnpm test` to confirm it fails
52+
3. Write the minimum code to make it pass
53+
4. Refactor if needed
54+
5. Commit the test and implementation together
55+
56+
Additional guidelines:
57+
58+
- Follow existing code patterns and conventions in the project
59+
- Run `pnpm build` frequently to catch type errors early
60+
- Ask the user for direction when making design decisions with multiple valid approaches
61+
62+
## Committing
63+
64+
Invoke the `/commit` skill for every commit — do not write commit messages manually. Build bottom-up: implement the building blocks first as isolated commits, then compose them.
65+
66+
Example commit sequence for a feature:
67+
1. Add utility function with tests
68+
2. Add service layer with tests
69+
3. Add command that wires it together
70+
4. Update docs
71+
72+
Each commit should be a self-contained unit — a module and its tests, a service and its tests, a command and its flags. Don't batch unrelated changes into a single commit.
73+
74+
## Completing
75+
76+
When the feature is done:
77+
78+
1. Verify all tests pass with `pnpm test`
79+
2. Verify build is clean with `pnpm build`
80+
3. Invoke the `/pull-request` skill to create the PR — do not create PRs manually
81+
4. Share the PR URL with the user

‎.claude/skills/commit/SKILL.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
name: commit
3+
description: Create git commits following project conventions. Use when the user invokes /commit or asks to commit changes. Stages files and writes conventional commit messages with type(scope) format.
4+
---
5+
6+
# Commit
7+
8+
These rules override the default git commit instructions.
9+
10+
Create a git commit following project conventions.
11+
12+
## Workflow
13+
14+
1. Run `git diff --staged` and `git status`
15+
2. Plan the commits — split all changes into the smallest meaningful commits:
16+
- A module and its test = one commit
17+
- A utility and its test = one commit
18+
- An untested module = one commit per file
19+
- Never combine independent modules, unrelated changes, or different scopes
20+
3. Order commits from foundation to integration:
21+
utilities → services → commands → config/docs
22+
4. For each commit, in order:
23+
a. Stage files with `git add <file1> <file2> ...`
24+
b. Run `pnpm build` to check for TypeScript errors
25+
c. If the reason for the change isn't clear, ask the user
26+
d. Write a message following the format below
27+
e. Run `git commit`
28+
f. Repeat for the next commit
29+
30+
**When in doubt, split.** More small commits are always better than fewer large ones.
31+
The commit log should read as the progressive assembly of a feature.
32+
33+
## Commit Format
34+
35+
```
36+
type(scope): subject
37+
38+
body (optional)
39+
40+
Co-authored-by: name <email> (only if human contributors specified)
41+
```
42+
43+
### Types
44+
45+
- `feat` - New feature
46+
- `fix` - Bug fix
47+
- `docs` - Documentation only
48+
- `refactor` - Code change that neither fixes a bug nor adds a feature
49+
- `test` - Adding or updating tests
50+
- `chore` - Maintenance tasks, dependencies, config
51+
52+
### Scopes
53+
54+
- `bucket` - Bucket commands, services, or utilities
55+
- `theme` - Theme commands, services, or utilities
56+
- `deploy` - Deployment strategies and related code
57+
- `shopify` - Shopify CLI integration utilities
58+
- `docs` - Standalone documentation
59+
- `agents` - AGENTS.md, CLAUDE.md, skills, AI tooling
60+
61+
### Subject Line
62+
- Maximum 50 characters
63+
- Imperative mood ("Add feature" not "Added feature")
64+
- Capitalize the first word after the scope
65+
- No trailing period
66+
67+
### Body (when needed)
68+
- Separate from subject with a blank line
69+
- Wrap at 72 characters
70+
- Explain *what* and *why*, not *how*
71+
72+
### Co-authored-by
73+
- Only include when a human contributor is explicitly mentioned
74+
- Never list the AI agent as a co-author
75+
- Format: `Co-authored-by: Name <email@example.com>`
76+
77+
## Examples
78+
79+
```
80+
fix(deploy): Correct blue/green theme swap logic
81+
```
82+
83+
```
84+
feat(bucket): Add markets.json to settings patterns
85+
86+
Include config/markets.json in bucket save/restore operations
87+
so market configuration is tracked alongside other settings.
88+
```
89+
90+
```
91+
chore(agents): Add commit skill
92+
```

‎.claude/skills/define-feature/SKILL.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
name: define-feature
3+
description: Define and scope a feature before building it. Use when the user invokes /define-feature or wants to plan, scope, or define a feature. Gathers requirements through conversation, then decomposes into small, verifiable tasks.
4+
---
5+
6+
# Define Feature
7+
8+
Gather requirements from the user until confident you can work autonomously, then decompose the feature into small, verifiable tasks.
9+
10+
## Principles
11+
12+
1. **All work must be verifiable.** Every task needs a concrete way to confirm it's done — a test, a behavior to observe, a command to run.
13+
2. **Smaller is better.** Break work into the smallest tasks that are independently meaningful. If a task feels big, it's probably multiple tasks.
14+
15+
## Workflow
16+
17+
### Phase 1: Gather context
18+
19+
Ask the user questions until you have enough to work autonomously. Don't ask everything at once — start with the most important gaps and follow up.
20+
21+
Areas to cover:
22+
23+
- **What** the feature does from the user's perspective
24+
- **Why** it's needed — the problem it solves
25+
- **Where** it fits in the existing system
26+
- **Boundaries** — what's explicitly out of scope
27+
- **Edge cases** the user already knows about
28+
29+
When you think you have enough, summarize the feature back to the user in your own words and get explicit confirmation before moving on. If the user corrects or adds anything, update your understanding and confirm again.
30+
31+
### Phase 2: Explore the codebase
32+
33+
Before decomposing, explore the relevant parts of the codebase to understand:
34+
35+
- Existing patterns to follow
36+
- Modules and files that will be affected
37+
- Related functionality already in place
38+
39+
### Phase 3: Decompose into tasks
40+
41+
Break the feature into ordered tasks. Each task must have:
42+
43+
- **Description**: What to do
44+
- **Test cases**: A list of specific, concrete checks that prove the task works. Each test case should be a plain-language statement of an input condition and its expected outcome. Cover the happy path, edge cases, and boundary conditions. Aim for the level of detail where an implementer can translate each line directly into a test assertion.
45+
46+
Tasks should follow the bottom-up pattern: building blocks first, then composition.
47+
48+
If the feature is too large to be a single body of work, say so. Propose splitting it into separate features, each with its own task list.
49+
50+
Present the task list to the user for approval. Adjust until they're satisfied.
51+
52+
### Phase 4: Create issues
53+
54+
Once approved, create GitHub issues using `gh`:
55+
56+
- Create a parent issue for the feature with the summary from Phase 1
57+
- Create sub-issues for each task, including the description and test cases
58+
- The issues are then ready for `/build-feature`
59+
60+
## What makes a good task
61+
62+
Good — description plus granular test cases:
63+
64+
> **Add `config/markets.json` to settings patterns**
65+
>
66+
> Test cases:
67+
> - `getSettingsPatterns()` includes `config/markets.json`
68+
> - `CLI_SETTINGS_FLAGS` includes `config/markets.json`
69+
> - `cliSettingFlags()` generates `--only config/markets.json` in output
70+
> - Bucket save copies `config/markets.json` from theme to bucket
71+
72+
> **Add `--listing` flag to deploy command**
73+
>
74+
> Test cases:
75+
> - Flag accepts a string value for the preset name
76+
> - Flag is passed through to the underlying push call
77+
> - Deploy works without the flag (backward compatible)
78+
79+
Too big:
80+
- "Add multi-environment support"
81+
- "Refactor all theme commands"
82+
83+
Too small:
84+
- "Create the test file"
85+
- "Add the import statement"

‎.claude/skills/pull-request/SKILL.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
name: pull-request
3+
description: Create pull requests using `gh` that tell the story of a change. Use when the user invokes /pull-request or asks to create a PR. Summarizes the what and why.
4+
---
5+
6+
# Pull Request
7+
8+
Create a pull request that tells the story of the change.
9+
10+
## Workflow
11+
12+
1. Run `git status` to check for uncommitted changes
13+
2. If there are uncommitted changes, use the **commit skill** to commit them first —
14+
follow all its rules for granularity, ordering, and formatting
15+
3. Run `git log main..HEAD --oneline` and `git diff main...HEAD` to review the full branch
16+
4. If the reason for the change isn't clear from the diff and commit history, ask the user for context
17+
5. Determine the PR title and write the body
18+
6. Push the branch and create the PR with `gh pr create`
19+
20+
## PR Title
21+
22+
Use the same format as commit messages:
23+
24+
```
25+
type(scope): subject
26+
```
27+
28+
- Same types and scopes as commits (feat, fix, refactor, etc.)
29+
- Maximum 50 characters
30+
- Imperative mood, capitalized, no trailing period
31+
32+
## PR Body
33+
34+
Tell the story of the change: what it does and why it was made. Keep it concise — the diff has the details.
35+
36+
Do not hard-wrap PR body text. Write normal flowing prose — let GitHub handle line wrapping.
37+
38+
```markdown
39+
## What
40+
41+
Brief description of the change (2-4 sentences). Focus on what the user or system experiences differently.
42+
43+
## Why
44+
45+
Motivation for the change. Link to issues, user feedback, or business context as applicable.
46+
```
47+
48+
## Creating the PR
49+
50+
```bash
51+
gh pr create --title "type(scope): subject" --body "$(cat <<'EOF'
52+
## What
53+
54+
...
55+
56+
## Why
57+
58+
...
59+
EOF
60+
)"
61+
```
62+
63+
- Always create PRs against `main` unless told otherwise
64+
- Push the branch first if it hasn't been pushed yet: `git push -u origin HEAD`
65+
66+
## Reformatting an existing PR
67+
68+
When asked to reformat, clean up, or "match our PR format" on an existing PR:
69+
70+
1. Run `git log main..HEAD --oneline` to see the current commits
71+
2. Run `git diff main...HEAD` to understand the full changeset
72+
3. Reset all commits back to staged changes: `git reset --soft main`
73+
4. Use the **commit skill** to re-commit everything from scratch —
74+
proper granularity, proper ordering, proper messages
75+
5. Update the PR title and body to match the format above
76+
6. Force push: `git push --force-with-lease`
77+
7. Update the PR with `gh pr edit` if the title or body changed
78+
79+
## Examples
80+
81+
Simple PR:
82+
```
83+
fix(deploy): Validate theme ID before swap
84+
85+
## What
86+
87+
Adds validation that both blue and green theme IDs exist before starting a blue/green deploy. Previously, an invalid ID would fail mid-deploy leaving the store in an inconsistent state.
88+
89+
## Why
90+
91+
Users reported failed deploys when a theme was deleted but the .env still referenced the old ID.
92+
```
93+
94+
Dependency bump PR:
95+
```
96+
chore: Bump Shopify CLI packages to 3.92.1
97+
98+
## What
99+
100+
Updates @shopify/cli and @shopify/cli-kit from 3.80.7 to 3.92.1, along with oclif packages. Replaces removed `renderText` API with `outputInfo`.
101+
102+
## Why
103+
104+
Staying current with Shopify CLI to pick up bug fixes and new features. The previous version was 12 minor releases behind.
105+
```

0 commit comments

Comments
 (0)