CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

postman-development

Skill completa para desenvolvimento e documentação de APIs usando Postman, incluindo automação, CI/CD, e geração a partir de OpenAPI.

Quality

63%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Medium

Suggest reviewing before use

Fix and improve this skill with Tessl

tessl review fix ./skills/documentation/postman/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

46%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 highly actionable, with concrete, mostly executable scripts, templates, and CI configuration, and its multi-step OpenAPI-to-Newman flow is clearly sequenced. However, it is severely bloated by triple-duplicated snippets and restated sections, and it behaves as a monolith — inlining templates and scripts that should live in bundle files it references but doesn't actually ship.

Suggestions

Extract the duplicated JWT pre-request script (currently present three times: lines ~117-160, ~771-805, and ~988-1019) into a single scripts/ or references/ file and reference it once.

Move the full collection template JSON, the GitHub Actions workflow YAML, and the shell scripts into actual bundle files (scripts/, assets/) so the "Arquivo:" labels point at real files, keeping SKILL.md as a concise overview.

Add explicit validation checkpoints to the OpenAPI-to-Postman flow (e.g., verify the converted collection's structure and confirm environment variables/secrets are set) before the Newman run, and fix the `openapi-to-postmanv2` CLI invocation to the actual binary name `openapi2postmanv2`.

Delete or merge the "Automação Avançada" section, which restates the "Geração a partir de OpenAPI" flow almost point-for-point.

DimensionReasoningScore

Conciseness

The ~1060-line body duplicates content systematically: the JWT auto-refresh pre-request script appears nearly verbatim three times ("Snippet obrigatório para todas as collections com JWT", the collection template's "exec" array, and "Pre-request Snippet (JWT Auto-refresh)"), the token-saving test script appears three times, and "Automação Avançada" restates the "Geração a partir de OpenAPI" section. This matches anchor 2 ('noticeably verbose; several unnecessary explanations or padded sections') rather than 3, where padding would be occasional rather than systemic.

2 / 5

Actionability

Mostly executable, copy-paste-ready guidance: complete pre-request/test scripts, a run_newman.sh with exit-code propagation, a full GitHub Actions workflow, and a collection template JSON. It stops short of anchor 5 due to minor gaps — the converter is invoked as `openapi-to-postmanv2` when the package's CLI binary is `openapi2postmanv2`, the CI `jq` string interpolation is fragile with special characters, and the "adicionar manualmente (ou via script)" injection step is underspecified.

4 / 5

Workflow Clarity

The OpenAPI-to-Postman flow is clearly sequenced (numbered steps plus the "Resumo do Fluxo" diagram) and there is an error-recovery loop ("Após correção, refazer TODOS os testes do início ao fim"), but the batch Newman/conversion workflow has no explicit validation checkpoints — nothing verifies the converted collection or that environment secrets are set before running. This fits anchor 3 ('steps listed but validation gaps; checkpoints missing or implicit') better than anchor 4.

3 / 5

Progressive Disclosure

No bundle files exist (no references/, scripts/, or assets/ directories), yet ~1060 lines of full JSON templates, CI YAML, and shell scripts are inlined in SKILL.md — and the body labels inline code as "Arquivo: `scripts/run_newman.sh`" and points to `core/templates/postman-collection/`, which are not present in the bundle. This matches anchor 2 ('content that clearly belongs in separate files is inlined'); the good section headers keep it from being worse, but the monolithic size and dangling file references keep it below anchor 3.

2 / 5

Total

11

/

20

Passed

Description

66%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 solid, domain-anchored description that states concrete capability areas in third person, though somewhat broad in phrasing. Its main weakness is the missing 'when to use' guidance, and the natural trigger keywords (newman, collection, api testing) live only in the separate `triggers` frontmatter field rather than in the description text.

Suggestions

Append an explicit trigger clause, e.g. "Use when documenting or testing REST APIs, creating Postman collections, running Newman, or converting OpenAPI specs to collections."

Fold the strongest natural keywords from the `triggers` field (newman, collection, api testing) into the description sentence so the description itself carries them.

Replace the broad phrase "desenvolvimento ... de APIs" with concrete actions (e.g., "cria collections, escreve pre-request/test scripts, configura pipelines") to lift specificity from 4 toward 5.

DimensionReasoningScore

Specificity

The description names the domain ("APIs usando Postman") and several concrete capability areas — "documentação", "automação, CI/CD", "geração a partir de OpenAPI" — matching anchor 4 ('several specific actions; minor gaps'). It falls short of anchor 5 because these are broad noun-phrases rather than a comprehensive list of discrete concrete actions, and above anchor 3 because it covers more than 1-2 actions.

4 / 5

Completeness

The 'what' is clear ("desenvolvimento e documentação de APIs usando Postman, incluindo automação, CI/CD, e geração a partir de OpenAPI"), but there is no "Use when..." clause or equivalent explicit trigger guidance in the description, which per the judging guidelines caps completeness at 3. It is not 2 because the 'what' half is concrete and well-stated.

3 / 5

Trigger Term Quality

"Postman", "APIs", "CI/CD", and "OpenAPI" are natural terms users would say, but common phrases like "newman", "collection", and "api testing" are missing from the description itself (they only appear in the separate frontmatter `triggers` field). This fits anchor 4 ('good keyword coverage; a few natural terms missing') rather than anchor 5's comprehensive synonym/extension coverage.

4 / 5

Distinctiveness Conflict Risk

The description is anchored to the distinct tool Postman, giving it a clear niche, but broad terms like "desenvolvimento de APIs", "automação", and "CI/CD" create minor overlap risk with general API-development or CI/CD skills — anchor 4 ('mostly distinct; minor overlap risk'). Not 5 because the description alone doesn't carry operationally distinct trigger phrases.

4 / 5

Total

15

/

20

Passed

Validation

81%

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

CriteriaDescriptionResult

skill_md_line_count

SKILL.md is long (1066 lines); consider splitting into references/ and linking

Warning

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

referenced_paths_exist

Referenced path issues: 1 missing

Warning

Total

13

/

16

Passed

Repository

fernandezbaptiste/cursor-multiagent-system

Path

skills/documentation/postman/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.