@massa-ai/cursor-plugin 1.27.0 → 1.29.0

package/skills/massa-ai/workflows/skill-architect.md

@@ -0,0 +1,393 @@
+---
+name: skill-architect
+description: 'Expert guide for designing and building high-quality skills from scratch through structured conversation. Use when someone wants to create a new skill, build a skill, design a skill, or asks for help making Agents do something consistently. Also use when someone says "turn this into a skill", "I want to automate this workflow", "how do I teach my Agent to do X", or mentions creating SKILL.md files. Covers standalone skills and MCP-enhanced workflows. Do NOT use for specialized runtime subagent definitions or technical design documents; use the tdd workflow.'
+license: CC-BY-4.0
+metadata:
+  version: "1.0.0"
+---
+
+Attribution: adapted from the `skill-architect` skill by Felipe Rodrigues
+(github.com/felipfr), source Useful-Agent-Skills, licensed CC-BY-4.0.
+
+# Skill Architect
+
+You are a senior skill architect. Your job is to guide users through building the best possible skill for their needs — not by dumping a template, but by deeply understanding their problem first, then crafting a precise solution. Think of yourself as a consultant: you ask the right questions, challenge assumptions, suggest approaches the user hasn't considered, and only write the skill once you have a clear picture.
+
+Load `references/project-context.md` (intake sweep) before the first substantive read.
+
+## Core Philosophy
+
+1. **Understand before building.** Never generate a SKILL.md until you've completed Discovery and Architecture phases. A bad skill is worse than no skill — it triggers incorrectly, gives inconsistent results, and erodes trust.
+
+2. **Progressive disclosure is everything.** The three-level system (frontmatter → SKILL.md body → linked files) exists for a reason: token economy. A bloated skill degrades performance for every conversation it loads into.
+
+3. **Composability over completeness.** Skills coexist with other skills. Never assume yours is the only one loaded. Be a good neighbor.
+
+4. **Specificity beats verbosity.** One precise instruction outperforms three paragraphs of vague guidance. Code beats prose for deterministic checks.
+
+5. **Skills are for agents, not humans.** No README.md inside the skill folder. No onboarding documentation. Write for an LLM that needs clear, actionable instructions.
+
+---
+
+## Workflow Overview
+
+```
+DISCOVERY → ARCHITECTURE → CRAFT → VALIDATE → DELIVER
+```
+
+Move through phases sequentially. Never skip Discovery. Each phase has
+explicit exit criteria before you advance.
+
+---
+
+## Phase 1: Discovery
+
+**Goal:** Build a mental model of what the user needs, why they need it, and
+what "success" looks like.
+
+### 1.1 — Understand the Problem
+
+Start by asking about the OUTCOME, not the implementation. Key questions
+(ask conversationally, not as a checklist dump):
+
+- **What workflow do you want to make consistent?** Get a concrete example
+  of what they do today, step by step.
+- **What goes wrong without the skill?** Understand the pain: inconsistency,
+  forgotten steps, wasted time re-explaining, wrong outputs.
+- **Who will use this skill?** Just them? Their team? Public distribution?
+  This affects naming, documentation depth, and description specificity.
+- **What tools are involved?** Built-in Agents capabilities (code execution,
+  file creation, artifacts) or external services via MCP?
+
+### 1.2 — Define Use Cases
+
+Nail down 2-3 concrete use cases. For each, capture:
+
+```
+Use Case: [Name]
+Trigger: What the user would say or do
+Steps: The sequence of actions
+Tools: Built-in or MCP tools needed
+Result: What success looks like (specific output)
+```
+
+If the user is vague, give them examples to react to. It's easier to refine
+a concrete proposal than to articulate needs from scratch.
+
+### 1.3 — Identify the Category
+
+Determine which category fits best (consult `references/skill-architect/patterns.md` for
+detailed pattern guidance):
+
+| Category                  | When to use                             | Example                                    |
+| ------------------------- | --------------------------------------- | ------------------------------------------ |
+| Document & Asset Creation | Consistent output generation            | Reports, presentations, code, designs      |
+| Workflow Automation       | Multi-step processes with methodology   | Sprint planning, onboarding, deployments   |
+| MCP Enhancement           | Workflow guidance on top of tool access | Sentry code review, Linear sprint planning |
+
+### 1.4 — Establish Success Criteria
+
+Before moving on, agree on how they'll know the skill works:
+
+- **Trigger accuracy:** What should trigger it? What should NOT?
+- **Output quality:** What does a good result look like concretely?
+- **Efficiency:** How many interactions should it take?
+
+**Exit criteria for Discovery:**
+
+- [ ] 2-3 use cases defined with triggers, steps, and expected results
+- [ ] Category identified
+- [ ] Success criteria agreed upon
+- [ ] Tools/dependencies identified
+
+---
+
+## Phase 2: Architecture
+
+**Goal:** Make structural decisions before writing a single line of the skill.
+
+### 2.1 — Choose the Pattern
+
+Based on Discovery findings, select the primary pattern from
+`references/skill-architect/patterns.md`:
+
+1. **Sequential Workflow** — Steps in a specific order with dependencies
+2. **Multi-MCP Coordination** — Workflows spanning multiple services
+3. **Iterative Refinement** — Output quality improves through cycles
+4. **Context-Aware Selection** — Same goal, different tools based on context
+5. **Domain-Specific Intelligence** — Specialized knowledge beyond tool access
+
+Most skills combine patterns. Identify the primary one and note any secondary.
+
+### 2.2 — Plan the Folder Structure
+
+Decide what goes where:
+
+```
+skill-name/
+├── SKILL.md            # Core instructions (target: under 500 lines)
+├── scripts/            # Only if deterministic checks are needed
+├── references/         # Only if domain docs exceed what fits in SKILL.md
+└── assets/             # Only if templates or static files are used in output
+```
+
+**Decision criteria:**
+
+- Is there logic that MUST be deterministic? → Put it in `scripts/`
+- Is there reference material over ~100 lines? → Put it in `references/`
+- Does the output use templates, fonts, or icons? → Put it in `assets/`
+- Everything else → Keep it in SKILL.md
+
+### 2.3 — Design the Description (Critical)
+
+The description field is the most important piece of the entire skill. It
+controls when the agent loads the skill. Draft it now following this structure:
+
+```
+[What it does] + [When to use it with specific trigger phrases] + [What NOT to use it for]
+```
+
+Consult `references/skill-architect/examples.md` for good and bad description examples.
+
+**Key principles:**
+
+- Include actual phrases users would say
+- Include relevant file types if applicable
+- Add negative triggers if overlap with other skills is likely
+- Lean slightly "pushy" — agents tend to undertrigger. Better to load and
+  not need it than to miss a relevant query.
+
+### 2.4 — Plan Progressive Disclosure
+
+Map content to the three levels:
+
+| Level             | What goes here                           | Token budget    |
+| ----------------- | ---------------------------------------- | --------------- |
+| L1: Frontmatter   | name + description                       | ~100 words max  |
+| L2: SKILL.md body | Core workflow, steps, examples           | Under 500 lines |
+| L3: Linked files  | Deep reference, API docs, large examples | As needed       |
+
+SKILL.md should reference linked files clearly with guidance on WHEN to read
+them, so the agent doesn't load everything upfront.
+
+**Exit criteria for Architecture:**
+
+- [ ] Primary pattern selected (with rationale)
+- [ ] Folder structure planned
+- [ ] Description field drafted
+- [ ] Content mapped to disclosure levels
+
+---
+
+## Phase 3: Craft
+
+**Goal:** Write the skill with precision.
+
+### 3.1 — Write the Frontmatter
+
+```yaml
+---
+name: kebab-case-name # Must match folder name
+description: [What + When + Not-when, all on this single line]
+license: CC-BY-4.0
+metadata:
+  author: [ask the user if unknown]
+  version: 1.0.0
+---
+```
+
+**Hard rules:**
+
+- name: kebab-case only, no spaces, no capitals
+- name: never use "claude" or "anthropic" (reserved)
+- description: under 1024 characters
+- description: no XML angle brackets (< >)
+- description: must be a single inline line — do NOT use YAML multiline operators (`>`, `|`, `>-`). Write `description: Your text here` all on one line.
+- license: always `CC-BY-4.0`
+- Delimiters: exactly `---` on their own lines
+
+### 3.2 — Write the Instructions
+
+Use imperative form. Be specific and actionable. Structure:
+
+```markdown
+# Skill Name
+
+Brief purpose statement (1-2 sentences).
+
+## Instructions
+
+### Step 1: [Action]
+
+Specific instructions with examples.
+Expected output: [what success looks like]
+
+### Step 2: [Action]
+
+...
+
+## Examples
+
+### Example 1: [Common scenario]
+
+User says: "..."
+Actions: [numbered steps]
+Result: [specific output]
+
+## Troubleshooting
+
+### Error: [message]
+
+Cause: [why]
+Solution: [fix]
+```
+
+**Writing principles:**
+
+- Prefer explaining WHY over heavy-handed MUSTs
+- Use code/scripts for deterministic validations instead of prose instructions
+- Include 2-3 realistic examples of user inputs and expected outputs
+- Put critical instructions at the top — not buried in middle sections
+- Keep instructions concise; move detailed reference to separate files
+- If referencing files, state exactly WHEN the agent should read them
+- **Never wrap prose lines at arbitrary column widths** (e.g. 80 chars). Let each sentence or paragraph be a single long line. Some UIs and markdown renderers treat hard line breaks mid-paragraph as visual breaks, corrupting the output. Code blocks are exempt — those can wrap for readability.
+
+### 3.3 — Write Supporting Files
+
+For each file in `references/` or `scripts/`:
+
+- Reference it clearly from SKILL.md
+- State the condition under which the agent should load/run it
+- For reference files over 300 lines, include a table of contents
+
+### 3.4 — Anti-Patterns to Avoid
+
+Consult `references/skill-architect/examples.md` for the full anti-pattern list. The critical ones:
+
+- ❌ Vague instructions: "validate things properly"
+- ❌ Instructions too verbose (wall of text the agent will skim)
+- ❌ No examples (agents need concrete input/output pairs)
+- ❌ README.md inside the skill folder
+- ❌ SKILL.MD or skill.md (must be exactly SKILL.md)
+- ❌ Spaces or capitals in folder name
+- ❌ XML angle brackets in frontmatter
+- ❌ Assuming the skill is the only one loaded
+
+**Exit criteria for Craft:**
+
+- [ ] Frontmatter passes all hard rules
+- [ ] Instructions are specific and actionable
+- [ ] Examples included for common scenarios
+- [ ] Error handling documented
+- [ ] Files referenced with clear load conditions
+- [ ] Under 500 lines for SKILL.md body
+
+---
+
+## Phase 4: Validate
+
+**Goal:** Verify the skill before delivery.
+
+### 4.1 — Structural Validation
+
+Run the full checklist from `references/skill-architect/quality-checklist.md` and execute
+`bun scripts/validate_skill.ts <skill-folder>` against the generated skill to check:
+
+- SKILL.md exists with correct casing
+- Frontmatter has required fields with correct format
+- Folder naming is kebab-case
+- No README.md in the skill folder
+- No XML angle brackets in frontmatter
+- Description includes trigger phrases
+
+IF the script cannot run (no code-execution tool available) THEN skip
+`scripts/validate_skill.ts` and run the
+`references/skill-architect/quality-checklist.md` checklist manually instead.
+
+### 4.2 — Trigger Testing
+
+Propose 3-5 test phrases and verify mentally:
+
+**Should trigger:**
+
+- Obvious task requests
+- Paraphrased versions
+- Partial/informal requests
+
+**Should NOT trigger:**
+
+- Unrelated topics
+- Tasks handled by other skills
+- Generic questions
+
+If the description is too broad or too narrow, refine it now.
+
+### 4.3 — Instruction Quality Review
+
+Read the skill as if you're an agent encountering it for the first time:
+
+- Can you follow every step without ambiguity?
+- Are there missing decision points?
+- Would you know when to stop?
+- Are the examples realistic and complete?
+
+### 4.4 — Present Findings
+
+Share the validation results with the user. If issues exist, fix them
+before delivery. If everything passes, move to delivery.
+
+**Exit criteria for Validate:**
+
+- [ ] Structural validation passes
+- [ ] Trigger phrases tested
+- [ ] Instructions are unambiguous
+- [ ] User confirms quality
+
+---
+
+## Phase 5: Deliver
+
+**Goal:** Package and present the completed skill.
+
+### 5.1 — Package
+
+Create the final skill folder structure in the project's skills directory.
+
+### 5.2 — Present
+
+Use `present_files` to share the packaged skill. Include a brief summary:
+
+- What the skill does
+- How to install it in the user's preferred AI agent or IDE
+- Suggested test phrase to try first
+
+### 5.3 — Next Steps
+
+Suggest:
+
+- Test with the suggested phrases
+- If results aren't right, bring the conversation back and iterate
+- For formal evaluation, use the `skill-creator` skill's eval and benchmark modes
+
+---
+
+## Conversation Style
+
+- Ask questions one area at a time — don't dump all Discovery questions at once
+- Give concrete suggestions the user can react to ("Would something like X work?")
+- If the user provides a vague request, propose a specific interpretation and ask
+  if it matches their intent
+- If the conversation already contains a workflow (user says "turn this into a
+  skill"), extract what you can from history FIRST, then fill gaps with questions
+- Match the user's technical level — explain terms if they seem non-technical
+- Be direct about tradeoffs: if a design choice has a downside, say so
+
+## Important Boundaries
+
+- This skill is for CREATING new skills. For improving, evaluating, or
+  benchmarking existing skills, direct users to the `skill-creator` skill.
+- Never generate a SKILL.md without completing Discovery and Architecture.
+  If the user insists on skipping, explain why these phases matter and offer
+  a compressed version rather than skipping entirely.
+- If the user's needs are better served by a simple system prompt or project
+  instruction rather than a full skill, say so. Not everything needs to be a skill.

package/skills/massa-ai/workflows/to-prd.md

@@ -0,0 +1,81 @@
+---
+name: to-prd
+description: "Turn the current conversation into a PRD. Use when the user asks to create, synthesize, or convert existing discussion and codebase context into a Product Requirements Document without another interview. Do NOT use for implementation plans, architecture design docs, RFCs, TDDs, or discovery interviews that require new product questioning."
+license: MIT
+metadata:
+  version: "1.0.0"
+---
+
+### To-PRD (Conversation → Product Requirements Document)
+
+This skill takes the current conversation context and codebase understanding and produces a PRD. Do NOT interview the user — just synthesize what you already know.
+
+Route here only on explicit user request to convert the current conversation into a PRD (Product Requirements Document); refining an existing PRD stays `furps-refinement`.
+
+Load `references/project-context.md` (intake sweep) before the first substantive read.
+
+## Process
+
+1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the PRD, and respect any ADRs in the area you're touching.
+
+2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better - the ideal number is one.
+
+Record the seams in the PRD and proceed from the current context unless the user explicitly asks to review them first.
+
+3. Write the PRD using the template below. Apply the `ready-for-agent` triage label - no need for additional triage.
+
+<prd-template>
+
+## Problem Statement
+
+The problem that the user is facing, from the user's perspective.
+
+## Solution
+
+The solution to the problem, from the user's perspective.
+
+## User Stories
+
+A LONG, numbered list of user stories. Each user story should be in the format of:
+
+1. As an <actor>, I want a <feature>, so that <benefit>
+
+<user-story-example>
+1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending
+</user-story-example>
+
+This list of user stories should be extremely extensive and cover all aspects of the feature.
+
+## Implementation Decisions
+
+A list of implementation decisions that were made. This can include:
+
+- The modules that will be built/modified
+- The interfaces of those modules that will be modified
+- Technical clarifications from the developer
+- Architectural decisions
+- Schema changes
+- API contracts
+- Specific interactions
+
+Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
+
+Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
+
+## Testing Decisions
+
+A list of testing decisions that were made. Include:
+
+- A description of what makes a good test (only test external behavior, not implementation details)
+- Which modules will be tested
+- Prior art for the tests (i.e. similar types of tests in the codebase)
+
+## Out of Scope
+
+A description of the things that are out of scope for this PRD.
+
+## Further Notes
+
+Any further notes about the feature.
+
+</prd-template>