CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

docs

Use this skill when contributing to InsForge's product documentation in this repository. This is for maintainers editing public docs in `docs/core-concepts`, agent docs in `.agents/docs`, SDK integration guides in `docs/sdks`, and OpenAPI specs in `openapi`.

Quality

81%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

75%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 tight, well-structured instruction skill with concrete path-mapped rules and an explicit validation checklist. The main improvement levers are removing the triple-repeated scope list, adding one concrete doc-style example, and making the dangling doc-author/INSFORGE.md reference resolvable within the bundle.

Suggestions

Collapse the redundant scope statements: the body's opening line ("Use this skill for `docs/core-concepts/`, `.agents/docs/`, `docs/sdks/`, and `openapi/`...") repeats both the frontmatter description and the Scope section — keep just the Scope section (conciseness).

Add a short before/after doc example (a sentence written in AI-tell style vs. the human-sounding rewrite) under Working Rule 2 so the style mandate is executable rather than descriptive (actionability).

Make the `doc-author` skill's `INSFORGE.md` overlay reference resolvable — either inline the key rules from that overlay into this bundle or reference a file that actually ships with the skill (progressive_disclosure).

Add an explicit feedback loop in Validation, e.g., "If a cross-check finds a mismatch, fix the doc or OpenAPI file and re-check before finishing" (workflow_clarity).

DimensionReasoningScore

Conciseness

The ~42-line body is lean and assumes Claude's competence (no concept explanations), but the opening line "Use this skill for `docs/core-concepts/`, `.agents/docs/`, `docs/sdks/`, and `openapi/` in the InsForge repository" repeats the frontmatter description and the "Scope" section verbatim — the same path list appears three times. Efficient with minor trimming opportunities, matching anchor 4 rather than the every-token-earns-its-place anchor 5.

4 / 5

Actionability

Guidance is concrete and executable for an instruction-only skill: exact placement rules ("prefer an `architecture.md` file inside the relevant `docs/core-concepts/<domain>/` folder"), explicit conditions ("update the relevant Markdown docs and the relevant OpenAPI YAML files in the same pass"), and per-surface mapping. It stops short of anchor 5 because there is no concrete example (e.g., a before/after snippet illustrating the mandated human-sounding style or a sample architecture.md section).

4 / 5

Workflow Clarity

A clear sequence is present — check current docs *before* implementation changes, update Markdown and OpenAPI *after*, with per-surface conditional branches — plus an explicit Validation section ("Re-read every documented command, path, route, and payload", "Cross-check OpenAPI YAML and Markdown docs against the implemented behavior"). Not a 5 because the failure path is implicit: there is no feedback loop saying what to do when a cross-check fails (fix and re-verify).

4 / 5

Progressive Disclosure

No bundle files exist and the under-50-line body is well organized into Scope / Working Rules / Validation, which would qualify for the simple-skill 5 — but the body dangles an unresolvable external reference ("See the `doc-author` skill's `INSFORGE.md` overlay, 'Sound human, not AI-generated'") that is not part of this bundle, a minor organization gap that drops it to anchor 4.

4 / 5

Total

16

/

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 well-scoped, third-person description with an explicit "Use when" trigger and concrete path-based targeting that makes conflict risk negligible. Its main weakness is that the capability statement is implicit — it says who and where, but not precisely what the skill does beyond generic "contributing/editing".

DimensionReasoningScore

Specificity

The description enumerates several concrete action/surface pairs — "editing public docs in `docs/core-concepts`, agent docs in `.agents/docs`, SDK integration guides in `docs/sdks`, and OpenAPI specs in `openapi`" — but the verbs themselves ("contributing", "editing") are generic, and the skill's actual capabilities (doc placement rules, style guidance, drift prevention) are never stated, so it falls short of the comprehensive anchor 5.

4 / 5

Completeness

The "when" is explicit and concrete ("Use this skill when contributing to InsForge's product documentation in this repository"), and a "what" is present, but the what is defined only via audience and surfaces ("This is for maintainers editing...") rather than stating what the skill actually does — matching anchor 4, not the fully explicit what+when of anchor 5.

4 / 5

Trigger Term Quality

Natural terms a user would say are present — "product documentation", "public docs", "SDK integration guides", "OpenAPI specs", "maintainers" — plus exact repo paths. It is not a 5 because there is no synonym breadth (e.g., "updating the doc site", "API spec", "guides"), but it is clearly above the partial-coverage anchor 3.

4 / 5

Distinctiveness Conflict Risk

Scoped tightly to "InsForge" with exact repo paths (`docs/core-concepts`, `.agents/docs`, `docs/sdks`, `openapi`) as triggers, giving it a clear niche with distinct trigger phrases and minimal overlap with other skills — a direct match for anchor 5.

5 / 5

Total

17

/

20

Passed

Validation

100%

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

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

InsForge/InsForge

Path

.agents/skills/insforge-dev/docs/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.