Move skills to .agents/skills
This commit is contained in:
Claudio Ortolina
+28
-26
@@ -1,12 +1,12 @@
|
|||||||
---
|
---
|
||||||
name: update-documentation
|
name: update-documentation
|
||||||
description: Use when the user asks to update project documentation, or after significant code changes that may have made docs/architecture.md, docs/project-conventions.md, docs/production-infrastructure.md, or any .claude/skills/*/SKILL.md file stale. Also trigger when new modules, schemas, workers, LiveViews, routes, external integrations have been added or removed, when queues or rate limits change, when testing conventions evolve, or when new commit rules are established.
|
description: Use when the user asks to update project documentation, or after significant code changes that may have made docs/architecture.md, docs/project-conventions.md, docs/production-infrastructure.md, or any .agents/skills/*/SKILL.md file stale. Also trigger when new modules, schemas, workers, LiveViews, routes, external integrations have been added or removed, when queues or rate limits change, when testing conventions evolve, or when new commit rules are established.
|
||||||
---
|
---
|
||||||
|
|
||||||
# Update Documentation
|
# Update Documentation
|
||||||
|
|
||||||
Updates `docs/architecture.md`, `docs/project-conventions.md`, `docs/production-infrastructure.md`,
|
Updates `docs/architecture.md`, `docs/project-conventions.md`, `docs/production-infrastructure.md`,
|
||||||
and all `.claude/skills/*/SKILL.md` files to reflect recent codebase changes.
|
and all `.agents/skills/*/SKILL.md` files to reflect recent codebase changes.
|
||||||
|
|
||||||
## Guards
|
## Guards
|
||||||
|
|
||||||
@@ -50,11 +50,12 @@ For each commit, check if it introduced changes relevant to the documentation fi
|
|||||||
Use `git show --stat <hash>` and `git show <hash>` to understand each commit.
|
Use `git show --stat <hash>` and `git show <hash>` to understand each commit.
|
||||||
|
|
||||||
**Skip these — they do not need documentation updates:**
|
**Skip these — they do not need documentation updates:**
|
||||||
|
|
||||||
- Bug fixes and minor tweaks that don't change structure
|
- Bug fixes and minor tweaks that don't change structure
|
||||||
- Dependency version bumps (unless they change a major integration)
|
- Dependency version bumps (unless they change a major integration)
|
||||||
- Refactors that rename internals without changing the public API or module structure
|
- Refactors that rename internals without changing the public API or module structure
|
||||||
- Test-only changes
|
- Test-only changes
|
||||||
- Skill or CLAUDE.md changes
|
- Skill or AGENTS.md changes
|
||||||
|
|
||||||
### 4. Prepare the update
|
### 4. Prepare the update
|
||||||
|
|
||||||
@@ -69,6 +70,7 @@ Use `git show --stat <hash>` and `git show <hash>` to understand each commit.
|
|||||||
### 5. Get human approval
|
### 5. Get human approval
|
||||||
|
|
||||||
Show the user:
|
Show the user:
|
||||||
|
|
||||||
- Which commits drove the changes
|
- Which commits drove the changes
|
||||||
- What sections are being added, modified, or removed
|
- What sections are being added, modified, or removed
|
||||||
- The exact content of each edit
|
- The exact content of each edit
|
||||||
@@ -82,33 +84,33 @@ Only apply changes after explicit approval.
|
|||||||
|
|
||||||
## Workflow (Skills)
|
## Workflow (Skills)
|
||||||
|
|
||||||
Skills in `.claude/skills/*/SKILL.md` contain hardcoded reference tables and conventions
|
Skills in `.agents/skills/*/SKILL.md` contain hardcoded reference tables and conventions
|
||||||
that must stay in sync with the codebase. When code changes render a skill stale, update it.
|
that must stay in sync with the codebase. When code changes render a skill stale, update it.
|
||||||
|
|
||||||
### Which Skills to Check After Code Changes
|
### Which Skills to Check After Code Changes
|
||||||
|
|
||||||
| Code Change | Skills to Check |
|
| Code Change | Skills to Check |
|
||||||
|-------------|-----------------|
|
| ---------------------------------- | ------------------------------------------------------------------------------------ |
|
||||||
| New/removed Oban worker | `oban-worker/SKILL.md` — worker tables (On-Demand, Cron), queue assignments |
|
| New/removed Oban worker | `oban-worker/SKILL.md` — worker tables (On-Demand, Cron), queue assignments |
|
||||||
| Queue configuration change | `oban-worker/SKILL.md` — Queues table |
|
| Queue configuration change | `oban-worker/SKILL.md` — Queues table |
|
||||||
| New/removed Oban plugin | `oban-worker/SKILL.md` — Plugins table |
|
| New/removed Oban plugin | `oban-worker/SKILL.md` — Plugins table |
|
||||||
| New/removed API integration | `external-api-integration/SKILL.md` — Rate limit intervals, fixture modules list |
|
| New/removed API integration | `external-api-integration/SKILL.md` — Rate limit intervals, fixture modules list |
|
||||||
| Rate limit interval change | `external-api-integration/SKILL.md` — Intervals table, `architecture.md` |
|
| Rate limit interval change | `external-api-integration/SKILL.md` — Intervals table, `architecture.md` |
|
||||||
| New/removed API fixture module | `external-api-integration/SKILL.md` — Available API Fixture Modules table |
|
| New/removed API fixture module | `external-api-integration/SKILL.md` — Available API Fixture Modules table |
|
||||||
| New test fixture module | `testing/SKILL.md` — Available fixture modules table |
|
| New test fixture module | `testing/SKILL.md` — Available fixture modules table |
|
||||||
| New SQL pattern becomes convention | `sqlite-optimization/SKILL.md` — add to patterns/anti-patterns |
|
| New SQL pattern becomes convention | `sqlite-optimization/SKILL.md` — add to patterns/anti-patterns |
|
||||||
| New LiveView or LiveComponent | `architecture.md` — LiveViews / LiveComponents tables |
|
| New LiveView or LiveComponent | `architecture.md` — LiveViews / LiveComponents tables |
|
||||||
| New/removed schema or context | `architecture.md` — Schemas / Contexts tables |
|
| New/removed schema or context | `architecture.md` — Schemas / Contexts tables |
|
||||||
| New/renamed module (any) | `architecture.md` — relevant section |
|
| New/renamed module (any) | `architecture.md` — relevant section |
|
||||||
| Route changes | `architecture.md` — Router Structure |
|
| Route changes | `architecture.md` — Router Structure |
|
||||||
| PubSub topic changes | `architecture.md` — PubSub Topics table |
|
| PubSub topic changes | `architecture.md` — PubSub Topics table |
|
||||||
| New/removed JS hook or event | `architecture.md` — JS Hooks / JS Event Listeners tables |
|
| New/removed JS hook or event | `architecture.md` — JS Hooks / JS Event Listeners tables |
|
||||||
| Testing convention change | `testing/SKILL.md` — relevant section; `project-conventions.md` |
|
| Testing convention change | `testing/SKILL.md` — relevant section; `project-conventions.md` |
|
||||||
| Commit convention change | `git-commit/SKILL.md` — relevant section; `project-conventions.md` |
|
| Commit convention change | `git-commit/SKILL.md` — relevant section; `project-conventions.md` |
|
||||||
| UI convention change | `ui-framework/SKILL.md` — relevant section (outside usage_rules blocks) |
|
| UI convention change | `ui-framework/SKILL.md` — relevant section (outside usage_rules blocks) |
|
||||||
| Production infra change | `production-infrastructure.md`; `error-investigation/SKILL.md` if monitoring changes |
|
| Production infra change | `production-infrastructure.md`; `error-investigation/SKILL.md` if monitoring changes |
|
||||||
| Dependency category added/removed | `update-dependencies/SKILL.md` — workflow steps |
|
| Dependency category added/removed | `update-dependencies/SKILL.md` — workflow steps |
|
||||||
| Skill added or removed | This file — update the table above |
|
| Skill added or removed | This file — update the table above |
|
||||||
|
|
||||||
### Skill Update Workflow
|
### Skill Update Workflow
|
||||||
|
|
||||||
+3
-2
@@ -1,4 +1,5 @@
|
|||||||
{
|
{
|
||||||
"skills": ["../.claude/skills"],
|
"packages": [
|
||||||
"packages": ["npm:pi-mcp-adapter"]
|
"npm:pi-mcp-adapter"
|
||||||
|
]
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -1,10 +1,10 @@
|
|||||||
# Project Conventions
|
# Project Conventions
|
||||||
|
|
||||||
Rules extracted from commit history that are specific to this project and not already covered by `CLAUDE.md` usage rules.
|
Rules extracted from commit history that are specific to this project and not already covered by `AGENTS.md` usage rules.
|
||||||
|
|
||||||
## Commit Messages
|
## Commit Messages
|
||||||
|
|
||||||
→ See `.claude/skills/git-commit/SKILL.md` for full conventions, checklist, and examples.
|
→ See `.agents/skills/git-commit/SKILL.md` for full conventions, checklist, and examples.
|
||||||
|
|
||||||
Key rules: imperative present tense, single-line under 60 characters, task ID prefix when the work maps to a Backlog.md task, "Update dependencies" for mix and "Update npm dependencies" for npm, never "Co-Authored-By".
|
Key rules: imperative present tense, single-line under 60 characters, task ID prefix when the work maps to a Backlog.md task, "Update dependencies" for mix and "Update npm dependencies" for npm, never "Co-Authored-By".
|
||||||
|
|
||||||
@@ -41,25 +41,25 @@ Key rules: imperative present tense, single-line under 60 characters, task ID pr
|
|||||||
|
|
||||||
## Template / UI
|
## Template / UI
|
||||||
|
|
||||||
→ See `.claude/skills/ui-framework/SKILL.md` for full conventions, component patterns, and Fluxon reference.
|
→ See `.agents/skills/ui-framework/SKILL.md` for full conventions, component patterns, and Fluxon reference.
|
||||||
|
|
||||||
Key rules: Gettext wraps ALL user-facing strings, dark mode always paired (`text-zinc-900 dark:text-zinc-100`), wishlisted items dimmed (`opacity-60`), icons use `icon` class, artist names use MusicBrainz `joinphrase`, charts use CSS Grid (not SVG).
|
Key rules: Gettext wraps ALL user-facing strings, dark mode always paired (`text-zinc-900 dark:text-zinc-100`), wishlisted items dimmed (`opacity-60`), icons use `icon` class, artist names use MusicBrainz `joinphrase`, charts use CSS Grid (not SVG).
|
||||||
|
|
||||||
## Routes / Navigation
|
## Routes / Navigation
|
||||||
|
|
||||||
→ See `.claude/skills/ui-framework/SKILL.md` for full route patterns.
|
→ See `.agents/skills/ui-framework/SKILL.md` for full route patterns.
|
||||||
|
|
||||||
Key rules: three routes per resource with show modals, modals close via `JS.patch`, search state in URL query params, empty params filtered from URLs, conditional links based on `purchased_at`, `/dev/` namespace for developer tooling only.
|
Key rules: three routes per resource with show modals, modals close via `JS.patch`, search state in URL query params, empty params filtered from URLs, conditional links based on `purchased_at`, `/dev/` namespace for developer tooling only.
|
||||||
|
|
||||||
## Database
|
## Database
|
||||||
|
|
||||||
→ See `.claude/skills/sqlite-optimization/SKILL.md` for full query patterns, index rules, FTS5 conventions, and migration requirements.
|
→ See `.agents/skills/sqlite-optimization/SKILL.md` for full query patterns, index rules, FTS5 conventions, and migration requirements.
|
||||||
|
|
||||||
Key rules: `json_extract()` must match expression index text exactly, subquery materialization via `limit: -1`, correlated scalar subqueries beat `LEFT JOIN` for small-LIMIT enrichment, every migration provides both `up` and `down` SQL, config-driven constants in `config/config.exs`.
|
Key rules: `json_extract()` must match expression index text exactly, subquery materialization via `limit: -1`, correlated scalar subqueries beat `LEFT JOIN` for small-LIMIT enrichment, every migration provides both `up` and `down` SQL, config-driven constants in `config/config.exs`.
|
||||||
|
|
||||||
## Error Handling
|
## Error Handling
|
||||||
|
|
||||||
→ See `.claude/skills/error-investigation/SKILL.md` for production error triage, `.claude/skills/external-api-integration/SKILL.md` for ErrorResponse/ErrorHandler patterns, and `.claude/skills/oban-worker/SKILL.md` for worker return values.
|
→ See `.agents/skills/error-investigation/SKILL.md` for production error triage, `.agents/skills/external-api-integration/SKILL.md` for ErrorResponse/ErrorHandler patterns, and `.agents/skills/oban-worker/SKILL.md` for worker return values.
|
||||||
|
|
||||||
- **Toast notifications:** `put_toast/3` (arity 3) in LiveViews, `put_toast!/2` (arity 2) in LiveComponents. `:info` for success, `:error` for failures.
|
- **Toast notifications:** `put_toast/3` (arity 3) in LiveViews, `put_toast!/2` (arity 2) in LiveComponents. `:info` for success, `:error` for failures.
|
||||||
- **User-facing error reasons use `ErrorMessages.friendly_message/1`** — never `inspect(reason)`. Call sites keep their contextual prefix and append `": " <> ErrorMessages.friendly_message(reason)`. `Logger.error` calls keep `inspect` for debugging.
|
- **User-facing error reasons use `ErrorMessages.friendly_message/1`** — never `inspect(reason)`. Call sites keep their contextual prefix and append `": " <> ErrorMessages.friendly_message(reason)`. `Logger.error` calls keep `inspect` for debugging.
|
||||||
@@ -69,7 +69,7 @@ Key rules: `json_extract()` must match expression index text exactly, subquery m
|
|||||||
|
|
||||||
## Testing
|
## Testing
|
||||||
|
|
||||||
→ See `.claude/skills/testing/SKILL.md` for full conventions, fixture modules, and SQLite/Swoosh/Worker test patterns.
|
→ See `.agents/skills/testing/SKILL.md` for full conventions, fixture modules, and SQLite/Swoosh/Worker test patterns.
|
||||||
|
|
||||||
Key rules: feature setup stays in test modules that need it, fixture modules use `System.unique_integer([:positive])`, assert specific values not just shapes, error assertions match specific error types, worker tests must `assert_enqueued`, no boilerplate-only tests.
|
Key rules: feature setup stays in test modules that need it, fixture modules use `System.unique_integer([:positive])`, assert specific values not just shapes, error assertions match specific error types, worker tests must `assert_enqueued`, no boilerplate-only tests.
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user