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

{
  "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:

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)