CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

authentication-portal-api

Build or troubleshoot portal JSON/native login clients, refresh, Documents, profile and admin APIs, and public JWKS. Use for HTTP contracts; portal Caddyfile wiring belongs to configuration-authentication.

Quality

77%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./.codex/skills/authentication-portal-api/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

67%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A dense, highly actionable API-contract reference with well-signaled one-level-deep references and a clear troubleshooting feedback section. Its main weakness is token efficiency: the body inlines deep wire-format detail that the reference bundle already (or should) carry, creating duplication with references/browser-refresh.md.

Suggestions

Trim the "Portal Refresh Transports" section to the core contract (transports, opt-in, status codes) and delegate continuation, recovery, and 503/uncertainty semantics to references/browser-refresh.md, which already covers them.

Move low-frequency wire details — Ed25519 JWK field formats, PS256 profile key ordering — into a dedicated reference file, keeping the body to availability rules, routing boundaries, and test coverage pointers.

Add one complete end-to-end login plus refresh request/response example (inline or as a pointer into references/native-client.md) so the challenge sequence is immediately executable without reassembling fields from prose.

DimensionReasoningScore

Conciseness

There is no generic-concept padding and nearly every sentence encodes project-specific contract rules, but the 281-line body uses long qualification-dense prose and the "Portal Refresh Transports" section restates the request contract that references/browser-refresh.md already details ("POST {} as JSON to <base>/api/refresh_token ... exact configured HTTPS Origin, and X-Authcrunch-Refresh: 1"). Mostly efficient but could be tightened — anchor 3 rather than 4, where trimming would be minor.

3 / 5

Actionability

Concrete, executable guidance throughout: exact dispatch signals ("Accept: application/json", "format=json"), a numbered challenge sequence with explicit field names (sandbox_id, sandbox_secret, challenge_kind), exact request bodies ("{"refresh_token":"<credential>"}"), and precise status semantics (401/403/503). Not 5 because the body lacks a complete end-to-end request/response example that would make the login-then-rotate flow copy-paste ready.

4 / 5

Workflow Clarity

The login challenge is a clear numbered 1-5 sequence with explicit loop handling ("The portal may rotate sandbox_secret and return another challenge") and safety rules ("Do not reuse an old sandbox_secret"), and the Troubleshooting section provides symptom-to-check recovery loops. Not 5 because the refresh workflows are distributed across prose with some implicit checkpoints rather than an explicit validated sequence.

4 / 5

Progressive Disclosure

All 8 bundle reference files exist and each is signaled with a purpose clause (e.g., "For encrypted file operations ... read [Documents API](references/documents.md)"), and references are one level deep. Not 5 because substantial deep detail is inlined in the body (Ed25519 JWK field formats, full refresh transport semantics) that duplicates or clearly belongs in the reference files, matching anchor 4's 'minor organization gaps'.

4 / 5

Total

15

/

20

Passed

Description

78%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong, specific description that names its capability areas, includes an explicit 'Use for' clause, and actively routes boundary cases to sibling skills. Main improvement opportunities are adding omitted surfaces (/beacon, /whoami, connected accounts) and more natural trigger synonyms such as 'authentication' or 'token'.

DimensionReasoningScore

Specificity

"Build or troubleshoot portal JSON/native login clients, refresh, Documents, profile and admin APIs, and public JWKS" enumerates several concrete capability areas with only minimal generic language. It falls short of 5 because the action verbs are limited to build/troubleshoot and surfaces the body actually covers (/beacon, /whoami, capabilities, connected accounts) are omitted — minor gaps in coverage matching anchor 4.

4 / 5

Completeness

Both what ("Build or troubleshoot portal JSON/native login clients, refresh, Documents, profile and admin APIs, and public JWKS") and when ("Use for HTTP contracts") are explicitly stated, plus a boundary exclusion. Not 5 because the when-clause is terse and abstract ("HTTP contracts") rather than concrete trigger phrases; not 3 because the 'Use for...' clause is present and explicit.

4 / 5

Trigger Term Quality

Natural terms users would say include "login", "refresh", "Documents", "admin APIs", and "public JWKS". A few common variations are missing ("authentication", "token", "JWT", "session"), which fits anchor 4 (good coverage, a few natural terms missing) rather than 5's comprehensive synonym coverage.

4 / 5

Distinctiveness Conflict Risk

The description carves a clear niche (this portal's HTTP client contracts) and explicitly disambiguates its nearest sibling: "portal Caddyfile wiring belongs to configuration-authentication". Minimal conflict risk despite a repo with many closely related configuration skills, matching anchor 5.

5 / 5

Total

17

/

20

Passed

Validation

93%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

relative_links

Relative link issues: 12 suspicious

Warning

Total

15

/

16

Passed

Repository

greenpau/caddy-security

Path

.codex/skills/authentication-portal-api/SKILL.md

Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.