重要前提
安装AI Skills的关键前提是:必须科学上网,且开启TUN模式,这一点至关重要,直接决定安装能否顺利完成,在此郑重提醒三遍:科学上网,科学上网,科学上网。查看完整安装教程 →
netbox-integration-best-practices by netboxlabs/netbox-best-practices
npx skills add https://github.com/netboxlabs/netbox-best-practices --skill netbox-integration-best-practices本技能提供使用 NetBox REST 和 GraphQL API 构建集成和自动化的最佳实践指导。
范围: 本技能涵盖 API 集成模式。它不涵盖插件开发、自定义脚本或 NetBox 管理。
| 功能 | 所需版本 |
|---|---|
| REST API | 所有版本 |
| GraphQL API | 2.9+ |
| v2 令牌 | 4.5+(使用这些!) |
| v1 令牌弃用 | 4.7+(在此之前迁移) |
主要目标: NetBox 4.4+,对于 v2 令牌功能需要 4.5+。
在以下情况下应用这些实践:
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| 级别 |
|---|
| 描述 |
|---|
| 行动 |
|---|
| 关键 | 安全漏洞、数据丢失、严重性能问题 | 必须立即修复 |
| 高 | 显著的性能/可靠性影响 | 应尽快修复 |
| 中 | 显著的改进、最佳实践 | 计划解决 |
| 低 | 较小的改进、可选 | 方便时考虑 |
Bearer nbt_<key>.<token>?limit=100(最大 1000)?exclude=config_context(对性能有重大影响)pip install netboxlabs-diode-sdk需要 netbox-branching 插件。
X-NetBox-Branch: {schema_id}(8 字符 ID,非名称){"commit": false} 以进行验证| 规则 | 影响 | 描述 |
|---|---|---|
| auth-use-v2-tokens | 关键 | 在 NetBox 4.5+ 上使用 v2 令牌 |
| auth-provisioning-endpoint | 中 | 使用配置端点进行自动化令牌创建 |
| 规则 | 影响 | 描述 |
|---|---|---|
| rest-list-endpoint-bulk-ops | 关键 | 使用列表端点进行批量操作 |
| rest-pagination-required | 高 | 始终对列表请求进行分页 |
| rest-patch-vs-put | 高 | 使用 PATCH 进行部分更新 |
| rest-brief-mode | 高 | 对列表使用 ?brief=True |
| rest-field-selection | 高 | 使用 ?fields= 选择字段 |
| rest-exclude-config-context | 高 | 从设备列表中排除 config_context |
| rest-avoid-search-filter-at-scale | 高 | 避免在大数据集上使用 q= |
| rest-filtering-expressions | 中 | 使用查找表达式 |
| rest-custom-field-filters | 中 | 按自定义字段过滤 |
| rest-nested-serializers | 低 | 理解嵌套序列化器 |
| rest-ordering-results | 低 | 使用排序参数 |
| rest-options-discovery | 低 | 使用 OPTIONS 进行发现 |
| 规则 | 影响 | 描述 |
|---|---|---|
| graphql-use-query-optimizer | 关键 | 使用查询优化器 |
| graphql-always-paginate | 关键 | 对每个列表查询进行分页 |
| graphql-pagination-at-each-level | 高 | 对嵌套列表进行分页 |
| graphql-select-only-needed | 高 | 仅请求需要的字段 |
| graphql-calibrate-optimizer | 高 | 针对生产环境进行校准 |
| graphql-max-depth | 高 | 保持深度 ≤3 |
| graphql-prefer-filters | 中 | 在服务器端过滤 |
| graphql-vs-rest-decision | 中 | 选择合适的 API |
| graphql-complexity-budgets | 低 | 建立复杂度预算 |
| 规则 | 影响 | 描述 |
|---|---|---|
| perf-exclude-config-context | 高 | 排除 config_context |
| perf-brief-mode-lists | 高 | 对列表使用简要模式 |
| 规则 | 影响 | 描述 |
|---|---|---|
| data-dependency-order | 关键 | 按依赖顺序创建对象 |
| data-site-hierarchy | 中 | 理解站点层次结构 |
| data-ipam-hierarchy | 中 | 理解 IPAM 层次结构 |
| data-custom-fields | 中 | 正确使用自定义字段 |
| data-tags-usage | 中 | 使用标签进行分类 |
| data-tenant-isolation | 中 | 使用租户进行隔离 |
| data-natural-keys | 中 | 使用自然键 |
| 规则 | 影响 | 描述 |
|---|---|---|
| integ-diode-ingestion | 高 | 对高容量数据摄取使用 Diode |
| integ-pynetbox-client | 高 | 在 Python 中使用 pynetbox |
| integ-branch-api-workflow | 高 | 完成分支生命周期(插件) |
| integ-branch-context-header | 高 | 使用 X-NetBox-Branch 头进行分支上下文(插件) |
| integ-branch-async-operations | 中 | 用于 sync/merge/revert 的 Job 轮询(插件) |
| integ-webhook-configuration | 中 | 配置 Webhook |
| integ-change-tracking | 低 | 查询对象变更 |
| 文档 | 用途 |
|---|---|
| HUMAN.md | 面向工程师的人类可读指南 |
| netbox-integration-guidelines.md | 全面的技术参考 |
每周安装次数
65
代码仓库
GitHub 星标数
22
首次出现
2026年1月25日
安全审计
安装于
gemini-cli54
codex53
github-copilot52
opencode52
amp50
kimi-cli50
This skill provides best practices guidance for building integrations and automations with NetBox REST and GraphQL APIs.
Scope: This skill covers API integration patterns. It does NOT cover plugin development, custom scripts, or NetBox administration.
| Feature | Version Required |
|---|---|
| REST API | All versions |
| GraphQL API | 2.9+ |
| v2 Tokens | 4.5+ (use these!) |
| v1 Token Deprecation | 4.7+ (migrate before this) |
Primary target: NetBox 4.4+ with 4.5+ for v2 token features.
Apply these practices when:
| Level | Description | Action |
|---|---|---|
| CRITICAL | Security vulnerabilities, data loss, severe performance | Must fix immediately |
| HIGH | Significant performance/reliability impact | Should fix soon |
| MEDIUM | Notable improvements, best practices | Plan to address |
| LOW | Minor improvements, optional | Consider when convenient |
Bearer nbt_<key>.<token>?limit=100 (max 1000)?exclude=config_context (major performance impact)pip install netboxlabs-diode-sdk for PythonRequires netbox-branching plugin.
X-NetBox-Branch: {schema_id} (8-char ID, not name){"commit": false} for validation| Rule | Impact | Description |
|---|---|---|
| auth-use-v2-tokens | CRITICAL | Use v2 tokens on NetBox 4.5+ |
| auth-provisioning-endpoint | MEDIUM | Use provisioning endpoint for automated token creation |
| Rule | Impact | Description |
|---|---|---|
| rest-list-endpoint-bulk-ops | CRITICAL | Use list endpoints for bulk operations |
| rest-pagination-required | HIGH | Always paginate list requests |
| rest-patch-vs-put | HIGH | Use PATCH for partial updates |
| rest-brief-mode | HIGH | Use ?brief=True for lists |
| rest-field-selection | HIGH | Use ?fields= to select fields |
| Rule | Impact | Description |
|---|---|---|
| graphql-use-query-optimizer | CRITICAL | Use query optimizer |
| graphql-always-paginate | CRITICAL | Paginate every list query |
| graphql-pagination-at-each-level | HIGH | Paginate nested lists |
| graphql-select-only-needed | HIGH | Request only needed fields |
| graphql-calibrate-optimizer | HIGH | Calibrate against production |
| Rule | Impact | Description |
|---|---|---|
| perf-exclude-config-context | HIGH | Exclude config_context |
| perf-brief-mode-lists | HIGH | Use brief mode for lists |
| Rule | Impact | Description |
|---|---|---|
| data-dependency-order | CRITICAL | Create objects in dependency order |
| data-site-hierarchy | MEDIUM | Understand site hierarchy |
| data-ipam-hierarchy | MEDIUM | Understand IPAM hierarchy |
| data-custom-fields | MEDIUM | Use custom fields properly |
| data-tags-usage | MEDIUM | Use tags for classification |
| Rule | Impact | Description |
|---|---|---|
| integ-diode-ingestion | HIGH | Use Diode for high-volume data ingestion |
| integ-pynetbox-client | HIGH | Use pynetbox for Python |
| integ-branch-api-workflow | HIGH | Complete branching lifecycle (plugin) |
| integ-branch-context-header | HIGH | Branch context with X-NetBox-Branch header (plugin) |
| integ-branch-async-operations | MEDIUM |
| Document | Purpose |
|---|---|
| HUMAN.md | Human-readable guide for engineers |
| netbox-integration-guidelines.md | Comprehensive technical reference |
Weekly Installs
65
Repository
GitHub Stars
22
First Seen
Jan 25, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
gemini-cli54
codex53
github-copilot52
opencode52
amp50
kimi-cli50
| rest-exclude-config-context | HIGH | Exclude config_context from device lists |
| rest-avoid-search-filter-at-scale | HIGH | Avoid q= with large datasets |
| rest-filtering-expressions | MEDIUM | Use lookup expressions |
| rest-custom-field-filters | MEDIUM | Filter by custom fields |
| rest-nested-serializers | LOW | Understand nested serializers |
| rest-ordering-results | LOW | Use ordering parameter |
| rest-options-discovery | LOW | Use OPTIONS for discovery |
| graphql-max-depth | HIGH | Keep depth ≤3 |
| graphql-prefer-filters | MEDIUM | Filter server-side |
| graphql-vs-rest-decision | MEDIUM | Choose appropriate API |
| graphql-complexity-budgets | LOW | Establish complexity budgets |
| data-tenant-isolation | MEDIUM | Use tenants for separation |
| data-natural-keys | MEDIUM | Use natural keys |
| Job polling for sync/merge/revert (plugin) |
| integ-webhook-configuration | MEDIUM | Configure webhooks |
| integ-change-tracking | LOW | Query object changes |