ln-643-api-contract-auditor
Checks layer leakage in method signatures, missing DTOs, entity leakage to API, inconsistent error contracts. Use when auditing API contracts.
- Installs
- 379
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/levnikolaevich/claude-code-skills --skill ln-643-api-contract-auditor- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads ln-643-api-contract-auditor automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Paths: File paths (
references/,../ln-*) are relative to this skill directory.
API Contract Auditor (L3 Worker)
Type: L3 Worker
Specialized worker auditing API contracts, method signatures at service boundaries, and DTO usage patterns.
Purpose & Scope
- Audit API contracts at architecture level (service boundaries, layer separation)
- Check layer leakage, DTO patterns, error contract consistency
- Return structured analysis with 4 scores (compliance, completeness, quality, implementation)
Out of Scope:
- Code duplication (same DTO shape repeated, same mapping logic, same validation)
- Report only ARCHITECTURE BOUNDARY findings (wrong layer, missing contract)
Inputs
- pattern: "API Contracts" # Pattern name
- locations: string[] # Service/API directories
- adr_reference: string # Path to related ADR
- bestPractices: object # Best practices from MCP Ref/Context7
- output_dir: string # e.g., ".hex-skills/runtime-artifacts/runs/{run_id}/audit-report"
# Domain-aware (optional)
- domain_mode: "global" | "domain-aware" # Default: "global"
- current_domain: string # e.g., "users", "billing" (only if domain-aware)
- scan_path: string # e.g., "src/users/" (only if domain-aware)
Workflow
Phase 0: Load References
MANDATORY READ: Load references/detection_patterns.md and references/mcp_tool_preferences.md.
Detection policy: use two-layer detection (candidate scan, then context verification); load references/two_layer_detection.md only when the verification method is ambiguous.
Tool policy: You may run as an isolated subagent where host AGENTS.md is not in scope, so default to hex-line MCP first for file reads, search, and edits. Load references/mcp_integration_patterns.md only when MCP behavior is unclear.
Use hex-graph first when symbol or reference analysis materially improves contract findings. Use hex-line first for local code reads when available. If MCP is unavailable, unsupported, or not indexed, continue with built-in Read/Grep/Glob/Bash and state the fallback in the report.
Phase 1: Discover Service Boundaries
scan_root = scan_path IF domain_mode == "domain-aware" ELSE codebase_root
1. Find API layer: Glob("**/api/**/*.py", "**/routes/**/*.ts", "**/controllers/**/*.ts", root=scan_root)
2. Find service layer: Glob("**/services/**/*.py", "**/services/**/*.ts", root=scan_root)
3. Find domain layer: Glob("**/domain/**/*.py", "**/models/**/*.py", root=scan_root)
4. Map: which services are called by which API endpoints
Phase 2: Analyze Contracts (5 Rules)
MANDATORY READ: Load references/detection_patterns.md for language-specific Grep patterns per rule.
| # | Rule | Severity | What to Check |
|---|---|---|---|
| 1 | Layer Leakage | HIGH/MEDIUM | Service/domain accepts HTTP types (Request, parsed_body, headers) |
| 2 | Missing DTO | MEDIUM/LOW | 4+ params repeated in 2+ methods without grouping DTO |
| 3 | Entity Leakage | HIGH/MEDIUM | ORM entity returned from API without response DTO. Downgrade when: internal API with no external consumers -> LOW |
| 4 | Error Contracts | MEDIUM/LOW | Mixed error patterns (raise + return None) in same service |
| 5 | Redundant Overloads | LOW/MEDIUM | Method pairs with _with_/_and_ suffix differing by 1-2 params |
| 6 | Architectural Honesty | HIGH/MEDIUM | Read-named function (get_/find_/check_/validate_/is_/has_) body contains write side-effects. Exclusions per references/ai_ready_architecture.md |
Scope boundary: SKIP duplication findings. REPORT only ARCHITECTURE BOUNDARY findings.
Phase 3: Calculate 4 Scores
Compliance Score (0-100):
| Criterion | Points |
|---|---|
| No layer leakage (HTTP types in service) | +35 |
| Consistent error handling pattern | +25 |
| Follows project naming conventions | +10 |
| No hidden side-effects in read-named functions | +10 |
| No entity leakage to API | +20 |
Completeness Score (0-100):
| Criterion | Points |
|---|---|
| All service methods have typed params | +30 |
| All service methods have typed returns | +30 |
| DTOs defined for complex data | +20 |
| Error types documented/typed | +20 |
Quality Score (0-100):
| Criterion | Points |
|---|---|
| No boolean flag params in service methods | +15 |
| No opaque return types hiding write actions | +10 |
| No methods with >5 params without DTO | +25 |
| Consistent naming across module | +25 |
| No redundant overloads | +25 |
Implementation Score (0-100):
| Criterion | Points |
|---|---|
| DTOs/schemas exist and are used | +30 |
| Type annotations present | +25 |
| Validation at boundaries (Pydantic, Zod) | +25 |
| API response DTOs separate from domain | +20 |
Phase 3.5: Calculate Score
MANDATORY READ: Load references/audit_worker_core_contract.md and references/audit_scoring.md.
Primary score uses penalty formula (same as all workers):
penalty = (critical x 2.0) + (high x 1.0) + (medium x 0.5) + (low x 0.2)
score = max(0, 10 - penalty)
Diagnostic sub-scores (0-100 each) are calculated separately and reported in AUDIT-META for diagnostic purposes only.
Phase 4: Write Report
MANDATORY READ: Load references/templates/audit_worker_report_template.md.
Write JSON summary per references/audit_summary_contract.md. In managed mode the caller passes both runId and summaryArtifactPath; in standalone mode the worker generates its own run-scoped artifact path per shared contract.
# Build markdown report in memory with:
# - AUDIT-META (extended: score [penalty-based] + diagnostic score_compliance/completeness/quality/implementation)
# - Checks table (layer_leakage, missing_dto, entity_leakage, error_contracts, redundant_overloads)
# - Findings table (issues sorted by severity)
# - DATA-EXTENDED: issues array with principle + domain fields (for cross-domain aggregation)
IF domain_mode == "domain-aware":
Write to {output_dir}/643-api-contract-{current_domain}.md
ELSE:
Write to {output_dir}/643-api-contract.md
Phase 5: Return Summary
Report written: .hex-skills/runtime-artifacts/runs/{run_id}/audit-report/643-api-contract-users.md
Score: 6.75/10 (C:65 K:70 Q:55 I:80) | Issues: 4 (H:2 M:1 L:1)
Critical Rules
Apply the already-loaded references/audit_worker_core_contract.md.
- Architecture-level only: Focus on service boundaries, not internal implementation
- Read before score: Never score without reading actual service code
- Scope boundary: SKIP duplication findings
- Detection patterns: Use language-specific Grep from detection_patterns.md
- Domain-aware: When domain_mode="domain-aware", scan only scan_path, tag findings with domain
- Unique angle: Audit service/API boundary contracts only. Do not audit code duplication, package health, dependency topology, or runtime operations.
- Action required: Every finding uses
ADD_DTO,STOP_ENTITY_LEAK, orSTANDARDIZE_ERROR_CONTRACT.
Definition of Done
Apply the already-loaded references/audit_worker_core_contract.md.
- Service boundaries discovered (API, service, domain layers)
- Method signatures extracted and analyzed
- All 5 rules checked using detection_patterns.md
- Scope boundary applied (no duplication findings)
- 4 scores calculated with justification
- Issues identified with severity, location, suggestion, effort
- If domain-aware: findings tagged with domain field
- Report written to
{output_dir}/643-api-contract[-{domain}].md(atomic single Write call) - Summary written per contract
Reference Files
- Detection patterns:
references/detection_patterns.md - Scoring rules:
references/audit_scoring.md
Version: 2.0.0 Last Updated: 2026-02-08
FAQ
What does the ln-643-api-contract-auditor skill do?
Checks layer leakage in method signatures, missing DTOs, entity leakage to API, inconsistent error contracts. Use when auditing API contracts.
How do I install ln-643-api-contract-auditor?
Run npx skills add https://github.com/levnikolaevich/claude-code-skills --skill ln-643-api-contract-auditor in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/ln-643-api-contract-auditor/ (personal) or .claude/skills/ln-643-api-contract-auditor/ (project).
Which AI agents can use ln-643-api-contract-auditor?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is ln-643-api-contract-auditor safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains ln-643-api-contract-auditor?
It is published by levnikolaevich in levnikolaevich/claude-code-skills. It has 379 recorded installs.
More from levnikolaevich/claude-code-skills
ln-100-documents-pipeline
levnikolaevich/claude-code-skills
Creates complete project documentation system (project docs, reference, tasks, tests). Use when bootstrapping docs from scratch or regenerating all.
ln-620-codebase-auditor
levnikolaevich/claude-code-skills
Open the skill to read its SKILL.md instructions.
ln-775-api-docs-generator
levnikolaevich/claude-code-skills
Configures Swagger/OpenAPI documentation for backend APIs. Use when adding interactive API docs to a project.
ln-624-code-quality-auditor
levnikolaevich/claude-code-skills
Checks cyclomatic complexity, nesting, long methods, god classes, O(n2), N+1 queries, constants management. Use when auditing code quality.
ln-782-test-runner
levnikolaevich/claude-code-skills
Executes all test suites and reports results with coverage. Use when verifying that test infrastructure works after bootstrap.
ln-634-test-coverage-auditor
levnikolaevich/claude-code-skills
Open the skill to read its SKILL.md instructions.
Popular backend & apis skills
find-skills
vercel-labs/skills
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
entra-app-registration
microsoft/azure-skills
Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.
google-agents-cli-adk-code
google/agents-cli
This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).
embedded-captions
heygen-com/hyperframes
Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.
entra-agent-id
microsoft/azure-skills
Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).
neon
neondatabase/agent-skills
Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.