Index of every page on this site: llms.txt
All skills
open-circle avatar

/repo-website-api-review

@fd386fe
by Open Circleopen-circle/formisch1.2k stars
40
Run it yourself

Review and verify API documentation routes on the Formisch website. Use when checking documentation accuracy, completeness, and consistency with source code.

  • 1 file
  • 4.9 KB
  • Updated 3 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/open-circle/formisch/repo-website-api-review

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈46 tokens for metadata: the name and description. ≈1.2k when used: this file.

Description uses 2.3% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈183 characters, or 2.3%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Reviewing API Documentation

This skill provides a systematic approach to reviewing API documentation routes for accuracy and consistency.

Review Process

Step 1: Compare with Source Code

For each documented API:

  1. Read the source file completely
  2. Compare function signatures - Must match exactly
  3. Verify types - Generics, parameters, return types
  4. Check JSDoc - Descriptions should match

Step 2: Check properties.ts

Verify each property:

  • Generic constraints match source code
  • Parameter types are accurate
  • Return type is correct
  • All href links are valid
  • No unused properties defined

Step 3: Check index.mdx

Verify content:

  • Front matter is complete (title, description, source, contributors)
  • Function signature matches source exactly
  • All generics documented
  • All parameters documented with correct headings (Parameters vs Properties)
  • Explanation references specific parameters/properties
  • Examples are realistic and follow conventions
  • Related section uses correct framework terminology

Step 4: Check Menu and Links

  • API listed in menu.md (alphabetical order)
  • All internal links work
  • Cross-package links use absolute paths
  • No broken links to types or functions

Common Issues to Find

Signature Mismatches

// Source code
export function validate(form: FormStore, config?: Config): void;

// ❌ Documentation shows different signature
const result = validate(form); // Missing config, wrong return

Missing Parameters

Documentation should include ALL parameters from source:

## Parameters

- `form` <Property {...properties.form} />
- `config` <Property {...properties.config} /> <!-- Don't forget optional params -->

Wrong Headings

API Type Heading
Functions ## Parameters
Components ## Properties

Outdated Examples

Examples must work with current API:

// ❌ Old API usage
const form = createForm(schema);

// ✅ Current API
const form = createForm({ schema });

Framework Terminology

Framework Related Section Heading
Solid ### Primitives
Qwik ### Hooks
Preact ### Hooks
React Native ### Hooks
HonoX ### Hooks
Angular ### Functions / ### Directives
Vue ### Composables
Svelte ### Runes

Type Links

// ❌ Wrong - using constraint type name
generics: [{ type: 'custom', name: 'RequiredPath' }];

// ✅ Correct - using parameter name
generics: [{ type: 'custom', name: 'TFieldPath' }];

Cross-Package Links

// ❌ Wrong - relative across packages
href: '../../../core/api/FormSchema/';

// ✅ Correct - absolute path
href: '/core/api/FormSchema/';

Verification Checklist

properties.ts

  • All generics have modifier: 'extends' (extends unknown when the source has no constraint)
  • Custom types have valid href links
  • Property order: name, href, generics
  • No unused properties
  • Types match source exactly

index.mdx

  • Title matches API name exactly (case-sensitive)
  • Description ends with period
  • Source path is correct
  • Function signature code block matches source
  • Correct heading (Parameters/Properties)
  • Explanation references specific params/props
  • Returns section present (unless void or component)
  • Examples section present (unless component/type)
  • Related section uses correct framework terminology
  • No Types in Related section

Menu Integration

  • API listed in appropriate menu.md
  • Alphabetical order maintained
  • Link path matches folder structure

Link Validation

  • All href in properties.ts resolve
  • ApiList links are valid
  • Cross-framework links use absolute paths
  • External links (Valibot) use full URLs

Review Output Format

Document issues found:

## Review: createForm

### Issues Found

1. **Signature mismatch** (L15)
   - Source shows `config: FormConfig<TSchema>`
   - Docs show `config: Config`

2. **Missing parameter** (Parameters section)
   - `initialInput` not documented

3. **Broken link** (properties.ts L23)
   - `href: '../FormConfig/'` - FormConfig not documented

### Recommendations

- Update properties.ts with correct FormConfig type
- Add initialInput to Parameters section
- Create FormConfig type documentation

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at fd386fe. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 4 days ago.

Activeupdated 3 weeks ago
metadata
{
  "author": "formisch",
  "version": "1.0"
}

README badge

README badge for open-circle/formisch/repo-website-api-review