Skip to content

Commit ae8f09e

Browse files
authored
Add migrate-integration and document-api-integration skills (#5442)
* Add migrate-integration and document-api-integration skills - New skill: migrate-integration - guides migration of reconcile/ integrations to qontract-api architecture (6 phases: discovery, utils, server-side, external endpoints, client-side, tests+docs) - New skill: document-api-integration - converted from command to skill for auto-triggering support - Simplified document-api-integration command to delegate to skill - New command: /migrate-integration as shortcut for the skill * remove slash cmds
1 parent 5dc7e80 commit ae8f09e

File tree

3 files changed

+512
-182
lines changed

3 files changed

+512
-182
lines changed

.claude/commands/document-api-integration.md

Lines changed: 0 additions & 182 deletions
This file was deleted.
Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
name: document-api-integration
3+
description: Generate comprehensive documentation for a qontract-api integration. Use this skill when a new integration has been created or migrated to qontract-api and needs documentation, or when someone asks to document an integration. Triggers on requests mentioning integration documentation, documenting API integrations, or after completing a migration with /migrate-integration.
4+
---
5+
6+
# Document qontract-api Integration
7+
8+
Analyze an existing qontract-api integration and generate documentation following the standard template at `docs/integrations/template.md`.
9+
10+
## Input
11+
12+
Integration name (e.g., "slack-usergroups"). If not provided, ask for it.
13+
14+
Validate the integration exists at `qontract_api/qontract_api/integrations/<name>/` before proceeding.
15+
16+
## Workflow
17+
18+
1. **Read the template** from `docs/integrations/template.md`
19+
20+
2. **Analyze the integration** by reading:
21+
- `qontract_api/qontract_api/integrations/<name>/models.py` - Request/Response/Action models
22+
- `qontract_api/qontract_api/integrations/<name>/service.py` - Business logic
23+
- `qontract_api/qontract_api/integrations/<name>/router.py` - API endpoints
24+
- `qontract_api/qontract_api/integrations/<name>/tasks.py` - Celery tasks
25+
- Other files in the integration directory (factory, client, etc.)
26+
- `reconcile/<name>_api.py` or `reconcile/<name>_api/` - Client integration
27+
- Related ADRs referenced in docstrings/comments
28+
29+
3. **Extract information** for each template section:
30+
- **Features**: What it does, actions it can perform, resources it manages
31+
- **API Endpoints**: POST/GET paths, parameters, responses
32+
- **Models**: Pydantic structure, key fields, validation rules (dry_run default=True)
33+
- **Actions**: All action types from discriminated union models
34+
- **Architecture**: Client-side vs server-side responsibilities
35+
- **Limits/Constraints**: Safety features, rate limits, cache TTLs, managed resources
36+
- **Required Components**: Vault secrets, external APIs, environment variables
37+
38+
4. **Generate documentation** using the template structure exactly. Fill all sections. Mark non-applicable sections as "[Not applicable for this integration]".
39+
40+
5. **Show summary** to user before writing:
41+
- API path, features count, action types, external APIs, requirements
42+
43+
6. **Write files** after confirmation:
44+
- Create `docs/integrations/<name>.md`
45+
- Update `docs/integrations/README.md` with link in alphabetical order
46+
47+
## Guidelines
48+
49+
- Follow the template structure from `docs/integrations/template.md` exactly
50+
- Extract information from actual code, not assumptions
51+
- Reference relevant ADRs
52+
- Include practical usage examples (curl commands, CLI)
53+
- Emphasize dry_run defaults and safety features
54+
- Set Last Updated date to today

0 commit comments

Comments
 (0)