| name | project-conventions |
| description | Project-specific conventions layered on top of the generic skills: ticket workflow, module structure, design tokens, test utilities, and PR etiquette. Use when working inside a repository to detect and honor its conventions before applying generic guidance, or as a template to encode a team's conventions. Other skills (swift, swiftui, testing, code-review) defer to this skill when present.
|
| allowed-tools | ["Read","Glob","Grep","Bash"] |
Project Conventions
This skill is a template plus detection workflow. Generic skills in this
harness defer to it: project conventions always take precedence over generic
guidance.
It ships with no company- or product-specific content. Either rely on Part 1
(dynamic detection) as-is, or fill in Part 2 with your team's conventions and
keep the skill in your user/project scope.
Part 1: Convention Detection (works in any repo)
When starting work in a repository, detect conventions instead of assuming:
Ticket convention
git log --oneline -30
- If commit subjects or branch names carry ticket IDs (pattern like
[A-Z][A-Z0-9]+-[0-9]+, e.g. ABC-123), the repository follows a ticket
convention. Honor it: include the ticket ID in branch names, commit
messages, and PR titles, matching the observed placement/format exactly.
- Find the current ticket from the branch name (
git branch --show-current)
or ask the user. Never invent ticket numbers.
- If no convention is observed, do not introduce one.
Code conventions
- Read root instruction files in priority order:
CLAUDE.md, AGENTS.md,
CONTRIBUTING.md, .github/copilot-instructions.md.
- Check linter/formatter configs (
.swiftlint.yml, .swiftformat,
detekt.yml, .editorconfig) — these are enforced rules, not suggestions.
- Mirror surrounding code: test factory naming, mock strategy, module
layering, design-token usage. Three existing examples beat any generic rule.
PR etiquette (generic defaults; project rules override)
- One ticket/concern per PR — flag and split mixed concerns
- Self-review the diff before requesting review
- Screenshots or recordings for UI changes
- File follow-up tickets for deferred work — never silently degrade
- Regression tests reference the ticket they guard against
Part 2: Team Template (fill in, keep placeholders out of output)
Replace every <placeholder> below for your team, or delete sections that
don't apply. While placeholders remain, treat the section as "not
configured" and fall back to Part 1 detection.
Identity & activation
- Applies when: git remote matches
<git-remote-pattern> or repo name is
<repo-name>
- Platform:
<ios|android|both|other>
Module architecture
- Layering:
<e.g., Feature → Domain → Core; UI never depends on Features>
- New code lives in:
<e.g., SPM package per feature / Gradle module>
- Canonical domain terms:
<e.g., the issue-tracking entity is named X everywhere — never synonyms>
Design system
- Tokens:
<typography/color/spacing token API, e.g. .font(.appTheme.body)>
- Required components:
<e.g., use the design-system Button, never raw Button>
- Review gate:
<e.g., compare against design specs before PR>
Testing utilities
- Factory:
<e.g., makeSUT(...) with defaulted dependencies>
- Doubles:
<e.g., spies record call arguments in arrays; count-based assertions>
- Mock generation:
<e.g., macro or hand-written under Tests/.../Mocks/>
- Async coordination:
<e.g., confirmation API; no sleep/timeouts>
Localization
<e.g., strings land in the same PR; placeholders over concatenation; removal cleans all languages>
Off-limits without explicit request
<e.g., signing/provisioning, CI lanes, dependency-pinning files, generated code>
Related Skills
| Need | Skill |
|---|
| Generic testing standards | testing |
| Generic review standards | code-review |
| PR/ticket documentation formats | work-docs |
