OpenParable
Skip to content
← Back to skills

Repo Website API Review

Testing & Quality
repo-website-api-review

Repo Website API Review is an Agent Skill for testing & quality published in the open-circle/formisch repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/open-circle/formisch/blob/HEAD/.agents/skills/repo-website-api-review/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/repo-website-api-review, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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 TypeHeading
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

FrameworkRelated Section Heading
Solid### Primitives
Qwik### Hooks
Preact### Hooks
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'
  • 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