docs: declare credentials and environment variables in calcom-api skill

[PeerRich]

What does this PR do?

Addresses a ClawHub.ai "Suspicious, medium confidence" warning on the calcom-api skill. The warning flagged that the skill's documentation references API keys, OAuth client secrets, and webhook secrets throughout its reference files, but the SKILL.md never formally declares these credentials — making it unclear to automated scanners (and users) what secrets the skill actually expects.

This PR adds:

1. Machine-readable env declarations in the YAML frontmatter metadata block (for tooling like ClawHub)
2. A human-readable "Required Credentials" table in the markdown body (for developers)

Declares four environment variables:

Variable	Required	Purpose
CAL_API_KEY	Yes	Bearer token for all API requests
CAL_CLIENT_ID	No	OAuth client ID for platform integrations
CAL_SECRET_KEY	No	OAuth client secret for platform integrations
CAL_WEBHOOK_SECRET	No	Webhook signature verification secret

Mandatory Tasks (DO NOT REMOVE)

• I have self-reviewed the code (A decent size PR without self-review might be rejected).
• I have updated the developer docs in /docs if this PR makes changes that would require a documentation change. N/A — this is a docs-only change to the skill file itself.
• I confirm automated tests are in place that prove my fix is effective or that my feature works. N/A — documentation-only change.

How should this be tested?

No functional testing required — this is a metadata/documentation change only.

• Verify the YAML frontmatter parses correctly (the env block under metadata is valid YAML).
• Verify the markdown table renders correctly on GitHub.

Human Review Checklist

• Env var naming: The webhook reference doc (references/webhooks.md line 192) uses process.env.WEBHOOK_SECRET, but this PR declares it as CAL_WEBHOOK_SECRET (with CAL_ prefix for namespacing). Confirm the preferred convention.
• Credential completeness: Verify no other credentials referenced in the references/ docs are missing from this declaration.
• Frontmatter format: The env block under metadata uses a description/required structure. Confirm this aligns with what ClawHub tooling expects.

Checklist

• My code follows the style guidelines of this project
• My changes generate no new warnings

---

Link to Devin run: https://app.devin.ai/sessions/cb9ab8890b984c4e86fefb17260859bd
Requested by: @PeerRich

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR that start with 'DevinAI' or '@devin'.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[cubic-dev-ai]

No issues found across 1 file

[paragon-review]

Paragon: tests updated

1 new test generated for this PR.

New Tests

• calcom-api skill definition — Tests that validate the SKILL.md frontmatter metadata and env var definitions

Details

New Tests

• calcom-api skill definition (unit)