Skip to content

Commit 5d70b30

Browse files
TheRealAgentKTheRealAgentK
authored
feat(skills): add building-integration skill (#38)
* feat(skills): add building-integration skill for local build/validation pipeline * docs(skills): add preflight checks for missing dependencies and tooling * docs: add all skills to README files * fix(skills): add pip fallback for dependency install step
1 parent 7bb6003 commit 5d70b30

3 files changed

Lines changed: 200 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,10 @@ The [`skills/`](skills/) directory contains agent skills for AI coding assistant
6262

6363
| Skill | Description |
6464
|-------|-------------|
65+
| [`building-integration`](skills/building-integration/) | Runs the local build and validation pipeline (structure, lint, format, security, tests) |
6566
| [`upgrading-sdk-v2`](skills/upgrading-sdk-v2/) | Upgrades an integration from SDK 1.x to 2.0.0 — covers source code, tests, requirements, and config |
67+
| [`writing-unit-tests`](skills/writing-unit-tests/) | Writes pytest unit tests using mock_context + FetchResponse |
68+
| [`writing-integration-tests`](skills/writing-integration-tests/) | Writes pytest e2e tests that call real APIs using the live_context fixture |
6669

6770
To use a skill, copy or symlink it into your workspace's `.agents/skills/` directory or your global `~/.config/agents/skills/` directory. See [`skills/README.md`](skills/README.md) for setup instructions.
6871

‎skills/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ Agent skills for AI coding assistants (Amp, Claude Code, etc.) that automate com
66

77
| Skill | Description |
88
|-------|-------------|
9+
| [`building-integration/`](building-integration/) | Runs the local build and validation pipeline (structure, lint, format, security, tests) |
910
| [`upgrading-sdk-v2/`](upgrading-sdk-v2/) | Upgrades an integration from SDK 1.x to 2.0.0 |
1011
| [`writing-unit-tests/`](writing-unit-tests/) | Writes pytest unit tests for an integration using mock_context + FetchResponse |
1112
| [`writing-integration-tests/`](writing-integration-tests/) | Writes pytest e2e integration tests that call real APIs using the live_context fixture |

‎skills/building-integration/SKILL.md‎

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
---
2+
name: building-integration
3+
description: "Runs the local build and validation pipeline for an Autohive integration — structure validation, code quality checks, linting, formatting, security scanning, and unit tests. Use when asked to build, validate, check, or verify an integration before pushing."
4+
---
5+
6+
# Building & Validating an Integration Locally
7+
8+
Run the same checks CI runs, locally, before pushing.
9+
10+
## Preflight Checks
11+
12+
Run these checks **before** starting the build pipeline. Fix any that fail.
13+
14+
### 1. Tooling repo
15+
16+
The tooling repo must be cloned alongside the integrations repo:
17+
18+
```
19+
parent-dir/
20+
├── autohive-integrations/ ← you are here
21+
└── autohive-integrations-tooling/ ← must exist
22+
```
23+
24+
Check: `ls ../autohive-integrations-tooling/scripts/validate_integration.py`
25+
26+
If missing, clone it:
27+
28+
```bash
29+
git clone https://github.com/autohive-ai/autohive-integrations-tooling.git ../autohive-integrations-tooling
30+
```
31+
32+
### 2. Python 3.13+
33+
34+
Check: `python3 --version` (must be 3.13+)
35+
36+
If not available, install with uv:
37+
38+
```bash
39+
uv python install 3.13
40+
```
41+
42+
Or use your system package manager / pyenv.
43+
44+
### 3. Virtual environment
45+
46+
Check: `ls .venv/bin/python`
47+
48+
If missing, create it:
49+
50+
```bash
51+
uv venv --python 3.13 .venv
52+
```
53+
54+
Or without uv:
55+
56+
```bash
57+
python3.13 -m venv .venv
58+
```
59+
60+
Always activate before running any commands:
61+
62+
```bash
63+
source .venv/bin/activate
64+
```
65+
66+
### 4. Package installer
67+
68+
Check: `which uv` or `which pip`
69+
70+
uv is preferred. If neither is available, install uv:
71+
72+
```bash
73+
curl -LsSf https://astral.sh/uv/install.sh | sh
74+
```
75+
76+
### 5. Test dependencies
77+
78+
Check: `python -c "import pytest"` (from within the activated venv)
79+
80+
If missing, install:
81+
82+
```bash
83+
uv pip install -r requirements-test.txt
84+
```
85+
86+
Or with pip:
87+
88+
```bash
89+
pip install -r requirements-test.txt
90+
```
91+
92+
### 6. Ruff
93+
94+
Check: `ruff --version` (from within the activated venv)
95+
96+
If missing, install:
97+
98+
```bash
99+
uv pip install ruff
100+
```
101+
102+
Note: `check_code.py` auto-installs ruff when it runs, but you need it locally for the manual auto-fix commands in Step 5.
103+
104+
## Build Pipeline
105+
106+
Run these steps in order from the integrations repo root. Replace `<name>` with the integration folder name (e.g., `clickup`).
107+
108+
### Step 1 — Install integration dependencies
109+
110+
```bash
111+
source .venv/bin/activate
112+
uv pip install -r <name>/requirements.txt
113+
# Or with pip: pip install -r <name>/requirements.txt
114+
```
115+
116+
### Step 2 — Structure validation
117+
118+
```bash
119+
python ../autohive-integrations-tooling/scripts/validate_integration.py <name>
120+
```
121+
122+
Checks: folder naming, required files (`config.json`, `requirements.txt`, `README.md`, icon, tests/`), config.json schema, auth config, action definitions, SDK version pinning, test structure.
123+
124+
Exit codes: `0` = passed, `1` = errors found, `2` = processing error.
125+
126+
### Step 3 — Code quality checks
127+
128+
```bash
129+
python ../autohive-integrations-tooling/scripts/check_code.py <name>
130+
```
131+
132+
Runs (in order): dependency install, Python syntax, import resolution, JSON validity, ruff lint, ruff format, bandit security scan, pip-audit, config-code sync, fetch pattern check.
133+
134+
Exit codes: `0` = passed, `1` = failures found.
135+
136+
### Step 4 — Unit tests
137+
138+
```bash
139+
pytest <name>/ -v
140+
```
141+
142+
Only runs tests in `test_*_unit.py` files (configured in `pyproject.toml`).
143+
144+
### Step 5 — Auto-fix lint and formatting issues
145+
146+
If steps 2–4 report ruff errors, auto-fix with:
147+
148+
```bash
149+
ruff check --fix --config ../autohive-integrations-tooling/ruff.toml <name>
150+
ruff format --config ../autohive-integrations-tooling/ruff.toml <name>
151+
```
152+
153+
Then re-run steps 2–4 to confirm.
154+
155+
## Ruff Configuration
156+
157+
CI uses the `ruff.toml` from the tooling repo — always pass `--config ../autohive-integrations-tooling/ruff.toml` to match CI behavior.
158+
159+
Key settings:
160+
- `target-version = "py313"`
161+
- `line-length = 120`
162+
- Rules: `E` (pycodestyle errors), `F` (Pyflakes), `W` (pycodestyle warnings)
163+
- `__init__.py`: `F401` ignored (re-exports)
164+
- `**/tests/context.py`: `F401`, `E402` ignored
165+
166+
## Workflow Summary
167+
168+
1. Install deps → `uv pip install -r <name>/requirements.txt` (or `pip install -r <name>/requirements.txt`)
169+
2. Validate structure → `python ../autohive-integrations-tooling/scripts/validate_integration.py <name>`
170+
3. Check code → `python ../autohive-integrations-tooling/scripts/check_code.py <name>`
171+
4. Run tests → `pytest <name>/ -v`
172+
5. Fix issues → `ruff check --fix ...` / `ruff format ...`
173+
6. Re-run until all pass
174+
175+
## Interpreting Output
176+
177+
### validate_integration.py
178+
- `❌` = Error — must fix before PR
179+
- `⚠️` = Warning — review but won't block CI
180+
- Final summary shows total errors/warnings across all integrations
181+
182+
### check_code.py
183+
- Each check prints `✅` or `❌` with details
184+
- All checks run even if one fails (no short-circuit)
185+
- Final line: `✅ CODE CHECK PASSED` or `❌ CODE CHECK FAILED`
186+
187+
### Common Failures and Fixes
188+
189+
| Failure | Fix |
190+
|---|---|
191+
| Ruff lint errors | `ruff check --fix --config ../autohive-integrations-tooling/ruff.toml <name>` |
192+
| Ruff format errors | `ruff format --config ../autohive-integrations-tooling/ruff.toml <name>` |
193+
| Bandit security issue | Add `# nosec B105` for test credential strings; fix real issues |
194+
| Config-code sync | Ensure actions in `config.json` match handlers in source code |
195+
| Missing test files | Create `tests/test_<name>_unit.py` (see `writing-unit-tests` skill) |
196+
| Import errors | Check `requirements.txt` has all dependencies; check `__init__.py` exports |

0 commit comments

Comments
 (0)