mcp-oauth-remote-gateway

Manual OAuth for remote MCP servers on headless gateways.

Quality

69%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./optional-skills/mcp/mcp-oauth-remote-gateway/SKILL.md

Quality

Content

73%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.

The body is an exceptionally actionable, well-sequenced runbook with strong validation and feedback loops, and its bundle references are real and well-signaled. Its main weakness is conciseness: the explanatory intro and the inlined 17-pitfall list add tokens that partly restate what Claude can infer or could live in a reference.

Suggestions

Tighten the 'Overview' and 'Why the Built-in OAuth Flow Fails' sections to the non-obvious facts (the dashboard-front-door ordering, the 127.0.0.1 callback failure) and drop generic loopback explanation Claude already knows.

Consider moving the 17-pitfall list (or its tail) into a references/pitfalls.md, keeping only the highest-frequency pitfalls inline, to lift progressive_disclosure and reduce inline length.

Make the step 10 initialize snippet a complete copy-pasteable httpx block (or point explicitly to the diagnose script as the canonical runner) to close the actionability gap to 5.

Dimension	Reasoning	Score
Conciseness	The body is dense and mostly high-signal (concrete commands, exact file schemas, hard-won pitfalls), but the 'Overview' and 'Why the Built-in OAuth Flow Fails' sections re-explain loopback/127.0.0.1 resolution that Claude can infer, fitting 'mostly efficient but includes some unnecessary explanation.'	3 / 5
Actionability	Steps 3-9 give executable curl/JSON/Python with exact PKCE recipes and token-file schemas, but step 10's initialize snippet is comment-pseudocode rather than copy-paste runnable (the runnable form lives in diagnose-oauth-mcp.py), leaving 'minor gaps' short of 5.	4 / 5
Workflow Clarity	An explicit 11-step sequence is anchored by a validation checkpoint (step 10 smoke-test the token BEFORE reload) and reinforced by feedback loops — the pitfall 7/9/10 decision tree and the diagnose script's branch logic — matching 'clear sequence with explicit validation steps; feedback loops for error recovery.'	5 / 5
Progressive Disclosure	Structure is good: overview + 'When to Use' + inline workflow, with two well-signaled one-level-deep references (scripts/diagnose-oauth-mcp.py, references/stripe-mcp-oauth-revocation.md, both real files) enumerated in 'Quick Reference Files'; it stops short of 5 because all 17 pitfalls live inline in the body rather than being split out.	4 / 5
	Total	16 / 20 Passed

Description

65%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.

The description is concise, third-person, and clearly distinguishes a narrow niche, but it omits any explicit 'Use when...' trigger guidance, which caps completeness. Adding a concrete trigger clause would raise it from good to exemplary.

Suggestions

Append a 'Use when...' clause naming concrete triggers, e.g. 'Use when adding a remote/headless MCP server that requires OAuth 2.1 + PKCE and the built-in browser flow cannot reach the gateway.'

Optionally surface 1-2 more concrete actions (e.g. 'registers a PKCE client, exchanges the code, writes Hermes-format token files') to lift specificity toward 5.

Include a natural synonym or file/protocol marker (e.g. 'OAuth 2.1', 'PKCE', 'RFC 7591') to broaden trigger-term coverage.

Dimension	Reasoning	Score
Specificity	"Manual OAuth" names one concrete action and "remote MCP servers"/"headless gateways" name the domain, but the description stops short of listing multiple specific actions, fitting the '1-2 concrete actions' anchor rather than the 'several specific actions' anchor at 4.	3 / 5
Completeness	It clearly states what the skill does ("Manual OAuth for remote MCP servers on headless gateways") but provides no explicit "Use when..." trigger clause, which per the rubric caps completeness at 3.	3 / 5
Trigger Term Quality	"OAuth", "remote MCP servers", and "headless gateways" are natural phrases a user would say, giving good keyword coverage; it falls short of 5 because it lacks synonyms or file extensions, and exceeds 3 which expects only a single generic keyword.	4 / 5
Distinctiveness Conflict Risk	The niche is sharply defined — manual OAuth specifically for remote/headless MCP gateways — with triggers unlikely to fire for any other skill, matching the 'clear niche with distinct triggers; minimal conflict risk' anchor.	5 / 5
	Total	15 / 20 Passed

Validation

81%

Warnings & errors only

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

Validation — 13 / 16 Passed

Validation for skill structure

Criteria	Description	Result
metadata_version	'metadata.version' is missing	Warning
metadata_field	'metadata' should map string keys to string values	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	13 / 16 Passed

Repository: NousResearch/hermes-agent
Path: optional-skills/mcp/mcp-oauth-remote-gateway/SKILL.md
Commit: 6680afb

Reviewed: about 3 hours ago

Table of Contents

Discovery Implementation Validation

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.