alps
Create, validate, and improve ALPS profiles. Generate from natural language descriptions, validate existing profiles, and get improvement suggestions.
npx skills add majiayu000/claude-skill-registry --skill alps-asd-app-state-diagram-claude-skills-alps-skill --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
Generates, validates, and improves ALPS profiles for RESTful API design. It supports creating profiles from natural language, validating existing profiles, and suggesting improvements. It also offers a website survey mode to crawl a site and produce an ALPS profile, then validates and generates an HTML diagram as part of a multi-step improvement loop. It prescribes a continuous-improvement workflow across sessions, including reading prior handover data, validating the profile and handover.json, generating HTML diagrams, and updating handover records.
How it works
- The skill responds to natural language requests to generate ALPS from text, such as:
- "Create an ALPS profile for a blog application"
- "Generate ALPS for an e-commerce cart system"
- "Design an ALPS profile for user authentication"
- It also supports ALPS surveyor mode via website crawling with prompts like:
- "Crawl https://example.com and generate ALPS profile"
- "Survey website structure and create ALPS"
- "Extract ALPS profile from existing website"
- The workflow includes:
- Efficient crawling using URL pattern classification to avoid redundant analysis
- Token optimization to analyze unique page types only once
- AI-powered extraction to infer states, transitions, and semantic fields
- Handover protocol: records progress in handover.json for continuity across sessions
- When asked to analyze or improve an existing profile, it follows a continuous-improvement loop that includes:
- Reading previous AI insights via asd --validate <file>
- Reading handover.json if present to capture prior session context
- Inheriting context from prior analysis and gaps
- Identifying missing features by exploring related docs or site
- Making improvements and validating via asd --validate <file>
- Generating HTML with asd <file> -o <file>.html
- Updating and validating handover.json via a JSON parse check
- Reporting completion with coverage and next steps
- Output conventions specify alps.json or alps.xml as the output file, placed under an app-named directory (e.g., ecommerce/alps.xml) unless an alps/ directory exists, in which case it uses that.
When to use it
- Use when you need to Generate ALPS from natural language descriptions.
- Use when you need to Generate ALPS from a website (survey/scan) to infer states and transitions.
- Use to Validate an existing ALPS profile and to Analyze or Improve an existing profile.
- Use for multi-session projects where handover.json tracking and iterative refinement are required (per ADR 0006).
What it can touch
- Tools and commands referenced: "asd" tool for validation and HTML generation, and the command line invocation patterns:
asd --validate <file>asd <file> -o <file>.html
- It expects to produce and update a handover.json file across sessions.
Caveats
- The description requires mandatory validation steps in each improvement session: validate the ALPS file and validate handover.json, and generate HTML.
- The workflow emphasizes continuity and knowledge transfer across AI sessions via handover.json per ADR 0006.
- It avoids including HTTP method or URL details in the ALPS content itself and focuses on semantic states, transitions, and descriptive documentation.
# ALPS Profile Assistant Generate, validate, and improve ALPS profiles for RESTful API design. ## Ideal ALPS Profile **Goal: An ALPS that someone unfamiliar with the app can read and understand.** ### What Makes a Good ALPS 1. **States = What the user sees** - `ProductList` - viewing a list of products - `ProductDetail` - viewing one product - `Cart` - viewing cart contents 2. **Transitions = What the user does** - `goProductDetail` - select a product - `doAddToCart` - add to cart 3. **Self-documenting** - `title` explains the purpose - `doc` describes behavior and side effects - No need to read code to understand 4. **No unreachable states** - Every state has an entry point - Orphan states indicate design mistakes 5. **Necessary and sufficient** - No over-abstraction - Describes semantics, not implementation - No HTTP methods or URLs ### What to Avoid - Mechanical CRUD listings without meaning - Implementation details leaking in - States without transitions (can't draw a diagram) - Excessive documentation nobody reads ## How to Use This skill responds to natural language requests: ### Generate ALPS from Natural Language - "Create an ALPS profile for a blog application" - "Generate
- Ideal ALPS Profile
- What Makes a Good ALPS
- What to Avoid
- How to Use
- Generate ALPS from Natural Language
- Generate ALPS from Website (NEW - alps-surveyor mode)
- Validate Existing Profile
- Analyze or Improve Existing Profile
- Continuous Improvement Loop - AI Inherits the Mission
- ALPS Structure Reference
- Three Layers of ALPS
- Naming Conventions
- Safe Transition Naming Rule
- Determining idempotent: PUT vs DELETE
node -e "JSON.parse(require('fs').readFileSync('handover.json', 'utf8')); console.log('✓ Valid JSON')"
asd merge base.json customer-domain.json
asd merge base.json admin-domain.json
asd profile.json -o profile.html
Session 1: Start large ALPS project
asd base.json --validate # Creates ai-insights in validation result
Create handover.json manually with initial task description
Session 2: Continue work
AI reads handover.json, adds customer domain
asd base.json --validate # Check for errorsWhat does the alps skill do?
Create, validate, and improve ALPS profiles. Generate from natural language descriptions, validate existing profiles, and get improvement suggestions.
How do I install it?
Run `npx skills add majiayu000/claude-skill-registry --skill alps-asd-app-state-diagram-claude-skills-alps-skill --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From majiayu000/claude-skill-registry, a repository with 534 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.