Amend update-documentation skill to monitor all other skills
This commit is contained in:
Claudio Ortolina
@@ -1,13 +1,23 @@
|
||||
---
|
||||
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, or docs/production-infrastructure.md stale. Also trigger when new modules, schemas, workers, LiveViews, routes, or external integrations have been added or removed.
|
||||
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.
|
||||
---
|
||||
|
||||
# Update Documentation
|
||||
|
||||
Updates `docs/architecture.md`, `docs/project-conventions.md`, and `docs/production-infrastructure.md` to reflect recent codebase changes.
|
||||
Updates `docs/architecture.md`, `docs/project-conventions.md`, `docs/production-infrastructure.md`,
|
||||
and all `.claude/skills/*/SKILL.md` files to reflect recent codebase changes.
|
||||
|
||||
## Workflow
|
||||
## Guards
|
||||
|
||||
**CRITICAL: NEVER modify content within `usage_rules` generated blocks.** These blocks
|
||||
are delimited by `<!-- usage-rules-skill-start -->` and `<!-- usage-rules-skill-end -->`.
|
||||
The only skill currently containing such blocks is `ui-framework/SKILL.md`. When
|
||||
editing any skill file, check for these markers first and treat the content between
|
||||
them as read-only. If a proposed change would land inside a usage_rules block, skip
|
||||
that change or restructure it to go outside the block.
|
||||
|
||||
## Workflow (Docs)
|
||||
|
||||
Steps 1–3 are independent per file — run them in parallel using subagents (one per
|
||||
doc file) to speed up analysis. Merge the results before presenting to the user in
|
||||
@@ -65,7 +75,57 @@ Show the user:
|
||||
|
||||
Only apply changes after explicit approval.
|
||||
|
||||
### 6. Apply and verify
|
||||
### 6. Apply and verify (Docs)
|
||||
|
||||
- Apply the approved edits
|
||||
- Commit with a message describing what was updated (e.g., "Update architecture docs" or "Update project conventions")
|
||||
|
||||
## Workflow (Skills)
|
||||
|
||||
Skills in `.claude/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.
|
||||
|
||||
### Which Skills to Check After Code Changes
|
||||
|
||||
| Code Change | Skills to Check |
|
||||
|-------------|-----------------|
|
||||
| New/removed Oban worker | `oban-worker/SKILL.md` — worker tables (On-Demand, Cron), queue assignments |
|
||||
| Queue configuration change | `oban-worker/SKILL.md` — Queues 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 |
|
||||
| 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 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 LiveView or LiveComponent | `architecture.md` — LiveViews / LiveComponents tables |
|
||||
| New/removed schema or context | `architecture.md` — Schemas / Contexts tables |
|
||||
| New/renamed module (any) | `architecture.md` — relevant section |
|
||||
| Route changes | `architecture.md` — Router Structure |
|
||||
| PubSub topic changes | `architecture.md` — PubSub Topics table |
|
||||
| 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` |
|
||||
| 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) |
|
||||
| Production infra change | `production-infrastructure.md`; `error-investigation/SKILL.md` if monitoring changes |
|
||||
| Dependency category added/removed | `update-dependencies/SKILL.md` — workflow steps |
|
||||
| Skill added or removed | This file — update the table above |
|
||||
|
||||
### Skill Update Workflow
|
||||
|
||||
1. **Identify stale content.** After code changes, check the table above for affected skills.
|
||||
Read the skill file and compare its reference tables, patterns, and conventions against
|
||||
the current codebase.
|
||||
|
||||
2. **Check for usage_rules blocks.** Before editing any skill, read it and identify
|
||||
`<!-- usage-rules-skill-start -->` / `<!-- usage-rules-skill-end -->` markers.
|
||||
Content between them is auto-generated and MUST NOT be modified.
|
||||
|
||||
3. **Prepare changes.** Apply the same principles as doc updates:
|
||||
- Follow the existing section structure and formatting
|
||||
- Add entries to existing tables; don't invent new structures
|
||||
- Match the style of surrounding content
|
||||
|
||||
4. **Get human approval.** Present proposed skill changes alongside doc changes.
|
||||
|
||||
5. **Apply and commit.** Use a commit message describing what was updated
|
||||
(e.g., "Update oban-worker skill for new cron workers").
|
||||
|
||||
Reference in New Issue
Block a user