Add Apideck API skills for AI coding agents

.github/workflows/validate-skills.yml

@@ -0,0 +1,80 @@
+name: Validate Skills
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'skills/**'
+      - 'llms.txt'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'skills/**'
+      - 'llms.txt'
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Validate SKILL.md frontmatter
+        run: |
+          errors=0
+          for skill_dir in skills/apideck-*/; do
+            skill_name=$(basename "$skill_dir")
+            skill_file="$skill_dir/SKILL.md"
+
+            if [ ! -f "$skill_file" ]; then
+              echo "ERROR: $skill_dir missing SKILL.md"
+              errors=$((errors + 1))
+              continue
+            fi
+
+            # Check name field matches directory
+            name_field=$(sed -n '/^---$/,/^---$/p' "$skill_file" | grep '^name:' | head -1 | sed 's/name: *//')
+            if [ "$name_field" != "$skill_name" ]; then
+              echo "ERROR: $skill_file name '$name_field' does not match directory '$skill_name'"
+              errors=$((errors + 1))
+            fi
+
+            # Check required frontmatter fields
+            for field in name description license alwaysApply; do
+              if ! sed -n '/^---$/,/^---$/p' "$skill_file" | grep -q "^${field}:"; then
+                echo "ERROR: $skill_file missing required field: $field"
+                errors=$((errors + 1))
+              fi
+            done
+
+            # Check metadata.json exists
+            if [ ! -f "$skill_dir/metadata.json" ]; then
+              echo "WARN: $skill_dir missing metadata.json"
+            fi
+
+            # Check SKILL.md line count
+            lines=$(wc -l < "$skill_file")
+            if [ "$lines" -gt 500 ]; then
+              echo "WARN: $skill_file is $lines lines (recommended: under 500)"
+            fi
+
+            echo "OK: $skill_name ($lines lines)"
+          done
+
+          if [ $errors -gt 0 ]; then
+            echo ""
+            echo "FAILED: $errors error(s) found"
+            exit 1
+          fi
+
+          echo ""
+          echo "All skills validated successfully"
+
+      - name: Validate provider sync
+        run: |
+          node skills/sync.js --skills-only
+          if [ -n "$(git diff --name-only providers/)" ]; then
+            echo "WARN: Provider mirrors are out of sync. Run 'node skills/sync.js --skills-only' and commit."
+            git diff --stat providers/
+          else
+            echo "OK: Provider mirrors are in sync"
+          fi

.gitignore

@@ -0,0 +1,5 @@
+.DS_Store
+node_modules/
+.env
+*.local
+specs-summary.json

AGENTS.md

@@ -0,0 +1,100 @@
+# Agent Guidelines for Apideck API Skills
+
+This repository contains AI agent skills for the Apideck Unified API. Follow these guidelines when contributing or modifying skills.
+
+## Repository Structure
+
+```
+skills/{skill-name}/
+  SKILL.md              # Required: Agent instructions with YAML frontmatter
+  metadata.json         # Required: Version, references, organization metadata
+  references/           # Optional: Detailed reference docs (loaded on demand)
+  scripts/              # Optional: Executable scripts
+```
+
+Provider mirrors (auto-generated via `node skills/sync.js`):
+```
+providers/{claude,cursor}/plugin/
+  skills/               # Mirror of skills/ (do not edit directly)
+  commands/             # Slash commands
+  .{provider}-plugin/   # Plugin configuration
+```
+
+## Skill Authoring Rules
+
+### SKILL.md Requirements
+
+- **Frontmatter** must include: `name`, `description`, `license`, `alwaysApply`, `metadata` (with `author` and `version`)
+- **`name`** must be kebab-case, match the directory name, and start with `apideck-`
+- **`description`** must include trigger phrases — words/phrases that help agents decide when to activate the skill
+- **`alwaysApply`** should be `false` for all skills (loaded only when contextually relevant)
+- **SKILL.md body** should stay under 500 lines. Move detailed content to `references/` files
+- **Code examples** must use real Apideck SDK patterns with correct method signatures
+- **Doc links** should point to `https://developers.apideck.com/` for official docs
+
+### Progressive Disclosure (Context Efficiency)
+
+Skills are loaded in tiers to minimize context window usage:
+
+1. **Metadata** (~100 tokens): `name` and `description` from frontmatter — loaded at startup for ALL installed skills
+2. **Instructions** (< 5000 tokens): Full SKILL.md body — loaded when skill is activated
+3. **References** (as needed): Files in `references/` — loaded only when agent needs specific details
+
+Keep SKILL.md as a quick reference / index. Put detailed API endpoint docs, migration tables, and configuration references in separate files.
+
+### metadata.json Format
+
+```json
+{
+  "version": "1.0.0",
+  "organization": "Apideck",
+  "date": "February 2026",
+  "abstract": "Brief description of the skill's purpose",
+  "references": [
+    "https://developers.apideck.com",
+    "https://apideck.com"
+  ]
+}
+```
+
+### Important Conventions
+
+- All SDKs follow the same CRUD pattern: `client.{api}.{resource}.{operation}()`
+- Authentication always requires: `apiKey`, `appId`, `consumerId`
+- `serviceId` specifies the downstream connector (e.g., `salesforce`, `quickbooks`)
+- Base URL is always `https://unify.apideck.com`
+- OpenAPI specs are at `https://specs.apideck.com/{api-name}.yml`
+- API Explorer URL format: `https://developers.apideck.com/api-explorer?id={api}`
+- Never hardcode API keys in examples — use environment variables
+- Connector count is 200+
+
+## Sync Workflow
+
+After modifying skills, run the sync script to update provider directories:
+
+```bash
+node skills/sync.js --skills-only
+```
+
+This copies all skills and commands to `providers/claude/plugin/` and `providers/cursor/plugin/`.
+
+## Adding a New Skill
+
+1. Create `skills/apideck-{name}/SKILL.md` with proper frontmatter
+2. Create `skills/apideck-{name}/metadata.json`
+3. Add references in `skills/apideck-{name}/references/` if needed
+4. Run `node skills/sync.js --skills-only` to sync to providers
+5. Update `README.md` with the new skill
+6. Update `llms.txt` if the skill covers a new API or tool
+
+## Validation Checklist
+
+- [ ] `name` field matches directory name
+- [ ] `name` is kebab-case with `apideck-` prefix
+- [ ] `description` includes trigger phrases for agent matching
+- [ ] `alwaysApply: false` is set
+- [ ] `metadata.json` exists with version and references
+- [ ] SKILL.md is under 500 lines
+- [ ] Code examples use correct SDK patterns
+- [ ] No hardcoded API keys in examples
+- [ ] Provider mirrors are up to date (`node skills/sync.js --skills-only`)

CLAUDE.md

@@ -0,0 +1,100 @@
+# Agent Guidelines for Apideck API Skills
+
+This repository contains AI agent skills for the Apideck Unified API. Follow these guidelines when contributing or modifying skills.
+
+## Repository Structure
+
+```
+skills/{skill-name}/
+  SKILL.md              # Required: Agent instructions with YAML frontmatter
+  metadata.json         # Required: Version, references, organization metadata
+  references/           # Optional: Detailed reference docs (loaded on demand)
+  scripts/              # Optional: Executable scripts
+```
+
+Provider mirrors (auto-generated via `node skills/sync.js`):
+```
+providers/{claude,cursor}/plugin/
+  skills/               # Mirror of skills/ (do not edit directly)
+  commands/             # Slash commands
+  .{provider}-plugin/   # Plugin configuration
+```
+
+## Skill Authoring Rules
+
+### SKILL.md Requirements
+
+- **Frontmatter** must include: `name`, `description`, `license`, `alwaysApply`, `metadata` (with `author` and `version`)
+- **`name`** must be kebab-case, match the directory name, and start with `apideck-`
+- **`description`** must include trigger phrases — words/phrases that help agents decide when to activate the skill
+- **`alwaysApply`** should be `false` for all skills (loaded only when contextually relevant)
+- **SKILL.md body** should stay under 500 lines. Move detailed content to `references/` files
+- **Code examples** must use real Apideck SDK patterns with correct method signatures
+- **Doc links** should point to `https://developers.apideck.com/` for official docs
+
+### Progressive Disclosure (Context Efficiency)
+
+Skills are loaded in tiers to minimize context window usage:
+
+1. **Metadata** (~100 tokens): `name` and `description` from frontmatter — loaded at startup for ALL installed skills
+2. **Instructions** (< 5000 tokens): Full SKILL.md body — loaded when skill is activated
+3. **References** (as needed): Files in `references/` — loaded only when agent needs specific details
+
+Keep SKILL.md as a quick reference / index. Put detailed API endpoint docs, migration tables, and configuration references in separate files.
+
+### metadata.json Format
+
+```json
+{
+  "version": "1.0.0",
+  "organization": "Apideck",
+  "date": "February 2026",
+  "abstract": "Brief description of the skill's purpose",
+  "references": [
+    "https://developers.apideck.com",
+    "https://apideck.com"
+  ]
+}
+```
+
+### Important Conventions
+
+- All SDKs follow the same CRUD pattern: `client.{api}.{resource}.{operation}()`
+- Authentication always requires: `apiKey`, `appId`, `consumerId`
+- `serviceId` specifies the downstream connector (e.g., `salesforce`, `quickbooks`)
+- Base URL is always `https://unify.apideck.com`
+- OpenAPI specs are at `https://specs.apideck.com/{api-name}.yml`
+- API Explorer URL format: `https://developers.apideck.com/api-explorer?id={api}`
+- Never hardcode API keys in examples — use environment variables
+- Connector count is 200+
+
+## Sync Workflow
+
+After modifying skills, run the sync script to update provider directories:
+
+```bash
+node skills/sync.js --skills-only
+```
+
+This copies all skills and commands to `providers/claude/plugin/` and `providers/cursor/plugin/`.
+
+## Adding a New Skill
+
+1. Create `skills/apideck-{name}/SKILL.md` with proper frontmatter
+2. Create `skills/apideck-{name}/metadata.json`
+3. Add references in `skills/apideck-{name}/references/` if needed
+4. Run `node skills/sync.js --skills-only` to sync to providers
+5. Update `README.md` with the new skill
+6. Update `llms.txt` if the skill covers a new API or tool
+
+## Validation Checklist
+
+- [ ] `name` field matches directory name
+- [ ] `name` is kebab-case with `apideck-` prefix
+- [ ] `description` includes trigger phrases for agent matching
+- [ ] `alwaysApply: false` is set
+- [ ] `metadata.json` exists with version and references
+- [ ] SKILL.md is under 500 lines
+- [ ] Code examples use correct SDK patterns
+- [ ] No hardcoded API keys in examples
+- [ ] Provider mirrors are up to date (`node skills/sync.js --skills-only`)