Holded Skill

Operate Holded ERP through holdedcli to read and update data safely. Use when the user asks to read, search, create, update, or delete Holded entities (conta...

Security Scan

The skill's declared purpose (operate Holded via holdedcli), required binary, auth variable, and runtime instructions are consistent; exercise normal caution about installing a third‑party Homebrew tap and about the explicit --skip-validation workflow it recommends.

Purpose & Capability

Name/description, required binary ('holded'), primaryEnv (HOLDED_API_KEY), and the brew install for a holded CLI are coherent with a skill that drives the Holded API via the holdedcli tool. There are no unrelated credentials, binaries, or config paths requested.

Instruction Scope

SKILL.md stays within the Holded CLI domain: it instructs discovery (actions list/describe), uses holded actions run for reads/writes, and enforces explicit confirmation before writes. One notable behavior: it requires using --skip-validation and forcing an undocumented field ("isReceipt") for purchase receipts — this bypasses client-side validation and can lead to creating payloads that the CLI would otherwise reject. That is coherent with the skill's stated workaround but increases risk if misused, so the agent's mandatory confirmation protocol is appropriate.

Install Mechanism

Install spec uses a Homebrew formula from jaumecornado/tap (brew tap jaumecornado/tap; brew install holded). Homebrew is a common install mechanism, but this is a third‑party tap (not Homebrew/core). Installing from a personal tap carries more trust risk than an official release channel; verify the tap/author before installing.

Credentials

Only the Holded API key (HOLDED_API_KEY) is declared as the primary credential, which matches the skill's need to authenticate to Holded. The documentation mentions possible alternative credential sources (~/.config/holdedcli/config.yaml), but no extra or unrelated secrets are requested.

Persistence & Privilege

The skill does not request always:true and does not attempt to modify other skills or system-wide settings. It is instruction-only (no code files executed by the skill itself) and relies on the holded binary; normal agent autonomy settings apply.

Assessment

This skill appears to do what it claims, but check a few things before installing or enabling it: 1) Verify the Homebrew tap (jaumecornado/tap) and that you trust its author/source before running brew tap/install; third‑party taps can install arbitrary binaries. 2) Keep your HOLDED_API_KEY secret and only inject it when you trust the environment. 3) Understand that the skill recommends using --skip-validation and adding an undocumented field ("isReceipt") to create some purchase receipts — this bypasses client validation and can create records that may be invalid or unexpected if used incorrectly; rely on the mandatory confirmation flow and review payloads carefully. 4) The skill reads local holdedcli config (~/.config/holdedcli/config.yaml) as a credential source if present — be aware that local CLI config may be used. 5) Because the skill is instruction‑only, there are no embedded code files to audit, so your main exposure is the installed holded binary; validate that binary's provenance.

Use holdedcli to read and modify Holded data with a safe, repeatable workflow.

Operational Flow

1. Confirm technical prerequisites.
2. Discover available actions with holded actions list.
3. Inspect the selected action with holded actions describe <action> --json.
4. Classify the action as read or write.
5. If it is a write operation, ask for explicit confirmation before execution.
6. Run with --json and summarize IDs, HTTP status, and applied changes.

Prerequisites

• Verify that the binary exists: holded help
• Verify credentials: holded auth status or HOLDED_API_KEY
• Prefer structured output whenever possible: --json

Safety Rules

• ALWAYS check deductibility rules BEFORE creating any document. See "Accounting Rules for Spain" section below.
• Treat any POST, PUT, PATCH, or DELETE action as write.
• Treat any GET action (or HEAD when present) as read.
• Before any operation, always run holded actions describe <action> --json (after holded actions list) to validate accepted parameters.
• For purchase receipts, always enforce docType=purchase and include "isReceipt": true in the JSON body. Since holdedcli validates against Holded's schema (which doesn't include isReceipt), you must use --skip-validation flag.
• Ask for explicit user confirmation every time before any write action.
• Do not execute writes on ambiguous replies (ok, go ahead, continue) without clarification.
• Repeat the exact command before confirmation to avoid unintended changes.
• If the user does not confirm, stop and offer payload adjustments.

Mandatory Confirmation Protocol

Before any write action, show:

1. Holded action (action_id or operation_id).
2. Method and endpoint.
3. --path, --query, and body parameters (--body or --body-file).
4. The exact command to run.

Use this format:

This operation will modify data in Holded.
Action: <action_id> (<METHOD> <endpoint>)
Changes: <short summary>
Command: holded actions run ... --json
Do you confirm that I should run exactly this command? (reply with "yes" or "confirm")

Execute only after an explicit affirmative response.

Execution Pattern

Read Operations

1. Locate the action with holded actions list --json (use --filter).
2. Verify accepted path/query/body parameters with holded actions describe <action> --json.
3. Run holded actions run <action> ... --json.
4. Return a clear summary and relevant IDs for follow-up steps.

Write Operations

1. Locate and validate the action.
2. Run holded actions describe <action> --json to verify required/optional parameters.
3. Prepare the final payload.
4. If creating a purchase receipt/ticket, verify docType=purchase and "isReceipt": true, and use --skip-validation flag.
5. Request mandatory confirmation.
6. Run the command after confirmation.
7. Report result (status_code, affected ID, API response).

Base Commands

holded auth set --api-key "$HOLDED_API_KEY"
holded auth status
holded ping --json
holded actions list --json
holded actions list --filter contacts --json
holded actions describe invoice.get-contact --json
holded actions run invoice.get-contact --path contactId=<id> --json

For long payloads, prefer --body-file:

holded actions run invoice.update-contact \
  --path contactId=<id> \
  --body-file payload.json \
  --json

Purchase receipt rule (mandatory for purchase tickets):

holded actions describe invoice.create-document --json
holded actions run invoice.create-document \
  --path docType=purchase \
  --body '{"isReceipt": true, "date": 1770764400, "contactId": "<contactId>", "items": [{"name": "Description", "units": 1, "subtotal": 29.4, "tax": 0}]}' \
  --skip-validation \
  --json

Important notes:

• Use --skip-validation flag because holdedcli validates against Holded's schema which doesn't include isReceipt.
• Use subtotal in items (not price) - this is the field name Holded's API expects.
• Timestamps must be in seconds (Unix epoch) and in Europe/Madrid timezone.

Timestamp calculation (Python):

from datetime import datetime, timezone, timedelta
# For 11/02/2026 00:00 in Madrid:
dt = datetime(2026, 2, 11, 0, 0, 0, tzinfo=timezone(timedelta(hours=1)))
print(int(dt.timestamp()))  # 1770764400

Accounting Rules for Spain

⚠️ ALWAYS check these rules BEFORE creating any expense document:

Expense Type	IVA Deductible	Expense Deductible	Account
Restaurants/Meals	❌ No	✅ Yes (with justification)	629
Displacement	❌ No	✅ Yes	629
Fuel	⚠️ Mixed	✅ Yes	625/622
Office supplies	✅ Yes	✅ Yes	600/602
Insurance	⚠️ Mixed	✅ Yes	625

Before creating any document, ALWAYS verify:

1. Is the expense tax deductible?
2. Is the IVA deductible? (usually NO for restaurants, displacement)
3. If in doubt, ASK before creating the document.

Common mistake to avoid: Never set tax: 10 or tax: 21 for restaurant expenses - IVA is NOT deductible for meals unless it's a business event with proper justification.

Error Handling

• If MISSING_API_KEY appears, configure API key through --api-key, HOLDED_API_KEY, or holded auth set.
• If ACTION_NOT_FOUND appears, list the catalog and search with --filter.
• If INVALID_BODY appears, validate JSON before execution.
• If API_ERROR appears, report status_code and the API snippet.

References

• Read {baseDir}/references/holdedcli-reference.md for quick commands and criteria.
• Use dynamic action discovery and parameter inspection via:
  • holded actions list --json
  • holded actions describe <action> --json