blueprint-os 1.0.1 → 1.1.0

package/.agent/skills/brainstorming/SKILL.md

@@ -154,4 +154,4 @@ The `shaping-specs` skill will use the design document as its starting context,
 - Design document output: `specs/`
 - Next step: `.agent/skills/shaping-specs/SKILL.md`
 - Existing standards (Mode 2): `standards/README.md`
-- Superpowers brainstorming reference: `npx skills add obra/superpowers`
+- Superpowers brainstorming reference: `npx skills add obra/superpowers -a antigravity -y --copy`

package/.agent/skills/creating-skills/SKILL.md

@@ -16,7 +16,7 @@ description: Acquires or creates Blueprint OS skills. Searches skills.sh registr
 
 - [ ] Clarify the skill's purpose — what task does it solve, and what are its triggers?
 - [ ] Search skills.sh for an existing community skill (see Instructions > Discovering on skills.sh)
-- [ ] If found: install with `npx skills add <owner/repo>` and evaluate fit
+- [ ] If found: install with `npx skills add <owner/repo> -a antigravity -y --copy` and evaluate fit
 - [ ] If it covers the need as-is: done — update the Skills Index in `README.md`
 - [ ] If it partially fits: customize it (see Instructions > Customizing an installed skill)
 - [ ] If nothing suitable found: create from scratch (see Instructions > Creating from scratch)
@@ -32,7 +32,7 @@ Before building anything, search the [skills.sh registry](https://skills.sh) —
 **Search via agent:**
 
 ```bash
-npx skills add https://github.com/vercel-labs/skills --skill find-skills
+npx skills add https://github.com/vercel-labs/skills --skill find-skills -a antigravity -y --copy
 ```
 
 Then ask the `find-skills` skill to search for what you need.
@@ -42,18 +42,18 @@ Then ask the `find-skills` skill to search for what you need.
 **Install a skill:**
 
 ```bash
-npx skills add <owner/repo>
+npx skills add <owner/repo> -a antigravity -y --copy
 ```
 
 Example:
 
 ```bash
-npx skills add supabase/agent-skills
-npx skills add vercel-labs/agent-skills
-npx skills add anthropics/skills
+npx skills add supabase/agent-skills -a antigravity -y --copy
+npx skills add vercel-labs/agent-skills -a antigravity -y --copy
+npx skills add anthropics/skills -a antigravity -y --copy
 ```
 
-Installed skills land in `.agent/skills/` automatically — compatible with Blueprint OS out of the box.
+The `-a antigravity` flag installs to `.agent/skills/`, matching Blueprint OS. The `--copy` flag creates real files (not symlinks) so deleting `.agents` won't break the skill when Cursor is detected.
 
 ### Customizing an installed skill
 

package/.agent/skills/find-skills/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: find-skills
+description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
+---
+
+# Find Skills
+
+This skill helps you discover and install skills from the open agent skills ecosystem.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- Asks "how do I do X" where X might be a common task with an existing skill
+- Says "find a skill for X" or "is there a skill for X"
+- Asks "can you do X" where X is a specialized capability
+- Expresses interest in extending agent capabilities
+- Wants to search for tools, templates, or workflows
+- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
+
+## What is the Skills CLI?
+
+The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
+
+**Key commands:**
+
+- `npx skills find [query]` - Search for skills interactively or by keyword
+- `npx skills add <package>` - Install a skill from GitHub or other sources
+- `npx skills check` - Check for skill updates
+- `npx skills update` - Update all installed skills
+
+**Browse skills at:** https://skills.sh/
+
+## How to Help Users Find Skills
+
+### Step 1: Understand What They Need
+
+When a user asks for help with something, identify:
+
+1. The domain (e.g., React, testing, design, deployment)
+2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
+3. Whether this is a common enough task that a skill likely exists
+
+### Step 2: Search for Skills
+
+Run the find command with a relevant query:
+
+```bash
+npx skills find [query]
+```
+
+For example:
+
+- User asks "how do I make my React app faster?" → `npx skills find react performance`
+- User asks "can you help me with PR reviews?" → `npx skills find pr review`
+- User asks "I need to create a changelog" → `npx skills find changelog`
+
+The command will return results like:
+
+```
+Install with npx skills add <owner/repo@skill>
+
+vercel-labs/agent-skills@vercel-react-best-practices
+└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 3: Present Options to the User
+
+When you find relevant skills, present them to the user with:
+
+1. The skill name and what it does
+2. The install command they can run
+3. A link to learn more at skills.sh
+
+Example response:
+
+```
+I found a skill that might help! The "vercel-react-best-practices" skill provides
+React and Next.js performance optimization guidelines from Vercel Engineering.
+
+To install it:
+npx skills add vercel-labs/agent-skills@vercel-react-best-practices
+
+Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 4: Offer to Install
+
+If the user wants to proceed, you can install the skill for them:
+
+```bash
+npx skills add <owner/repo@skill> -g -y
+```
+
+The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
+
+## Common Skill Categories
+
+When searching, consider these common categories:
+
+| Category        | Example Queries                          |
+| --------------- | ---------------------------------------- |
+| Web Development | react, nextjs, typescript, css, tailwind |
+| Testing         | testing, jest, playwright, e2e           |
+| DevOps          | deploy, docker, kubernetes, ci-cd        |
+| Documentation   | docs, readme, changelog, api-docs        |
+| Code Quality    | review, lint, refactor, best-practices   |
+| Design          | ui, ux, design-system, accessibility     |
+| Productivity    | workflow, automation, git                |
+
+## Tips for Effective Searches
+
+1. **Use specific keywords**: "react testing" is better than just "testing"
+2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
+3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
+
+## When No Skills Are Found
+
+If no relevant skills exist:
+
+1. Acknowledge that no existing skill was found
+2. Offer to help with the task directly using your general capabilities
+3. Suggest the user could create their own skill with `npx skills init`
+
+Example:
+
+```
+I searched for skills related to "xyz" but didn't find any matches.
+I can still help you with this task directly! Would you like me to proceed?
+
+If this is something you do often, you could create your own skill:
+npx skills init my-xyz-skill
+```

package/README.md

@@ -79,7 +79,7 @@ From your project directory:
 npx blueprint-os init
 ```
 
-This copies `.agent/`, `standards/`, `references/`, and `adapters/` into your project. No dependency is added to `package.json`.
+This copies `.agent/`, `standards/`, `references/`, and `adapters/` into your project. No dependency is added to `package.json`. The `find-skills` skill is included so you can search the skills.sh registry without installing it separately.
 
 **Or copy manually:** Place the `.agent/` folder, `standards/` folder, and `references/` folder at the root of your project:
 
@@ -87,6 +87,9 @@ This copies `.agent/`, `standards/`, `references/`, and `adapters/` into your pr
 your-project/
 ├── .agent/
 │   └── skills/
+│       ├── find-skills/      ← pre-installed
+│       ├── brainstorming/
+│       └── ...
 ├── standards/
 ├── references/
 └── ... your code
@@ -124,8 +127,8 @@ your-project/
 **Adding a new skill:**
 
 ```
-1. Browse https://skills.sh or run: npx skills add https://github.com/vercel-labs/skills --skill find-skills
-2. If found: npx skills add <owner/repo>
+1. Use the pre-installed find-skills: "Read .agent/skills/find-skills/SKILL.md and find a skill for [task]" — or browse https://skills.sh
+2. If found: npx skills add <owner/repo> -a antigravity -y --copy
 3. If not found: ask your agent "Read .agent/skills/creating-skills/SKILL.md and create a skill for [task]"
 ```
 
@@ -137,6 +140,7 @@ Skills live in `.agent/skills/`. Each skill is a `SKILL.md` file the agent reads
 
 | Skill | Path | Purpose |
 |---|---|---|
+| Find Skills | `.agent/skills/find-skills/` | Search the skills.sh registry for community skills (pre-installed) |
 | Brainstorming | `.agent/skills/brainstorming/` | Explore problems, compare approaches, produce a design document |
 | Creating Skills | `.agent/skills/creating-skills/` | Find on skills.sh first, author from scratch as fallback |
 | Shaping Specs | `.agent/skills/shaping-specs/` | Formalize a chosen direction into an implementation spec |
@@ -146,7 +150,7 @@ Skills live in `.agent/skills/`. Each skill is a `SKILL.md` file the agent reads
 | Security Audit | `.agent/skills/security-audit/` | Audit auth, API, and sensitive data changes before merge |
 | Code Review | `.agent/skills/code-review/` | Final validation against spec and standards before merge |
 
-**Community skills** from [skills.sh](https://skills.sh) install directly into `.agent/skills/` and work with Blueprint OS out of the box. Run `npx skills add <owner/repo>` to install any skill from the registry.
+**Community skills** from [skills.sh](https://skills.sh) install into `.agent/skills/` when you use `-a antigravity -y --copy`. The `--copy` flag creates real files so deleting `.agents` (created when Cursor is detected) won't break the skill.
 
 ---
 
@@ -258,17 +262,16 @@ Agent loads `component-patterns.md`, `error-handling.md`, and any relevant refer
 
 You want the agent to follow a strict TDD workflow but Blueprint OS has no skill for it.
 
-**Step 1: Check skills.sh first**
+**Step 1: Use the pre-installed find-skills**
 ```
-npx skills add https://github.com/vercel-labs/skills --skill find-skills
+Read .agent/skills/find-skills/SKILL.md and find a skill for test-driven development
 ```
-Then: `Use the find-skills skill to search for a test-driven development skill`
 
 Found: `obra/superpowers` has `test-driven-development`.
 
 **Step 2: Install it**
 ```
-npx skills add obra/superpowers test-driven-development
+npx skills add obra/superpowers --skill test-driven-development -a antigravity -y --copy
 ```
 Lands in `.agent/skills/test-driven-development/SKILL.md` — immediately available.
 

package/adapters/antigravity.md

@@ -1,6 +1,6 @@
 # Using Blueprint OS in Antigravity
 
-Blueprint OS uses the `.agent/skills/` structure natively — the same format Antigravity expects. No extra setup required.
+Blueprint OS uses the `.agent/skills/` structure natively — the same format Antigravity expects. When installing from skills.sh, use `-a antigravity` so skills land here. No extra setup required.
 
 ---
 
@@ -133,7 +133,7 @@ Use the `creating-skills` skill — it searches skills.sh first, then creates fr
 Find or create a skill for [task]
 ```
 
-The agent will check [skills.sh](https://skills.sh) first (`npx skills add https://github.com/vercel-labs/skills --skill find-skills`), install a community skill if available, or create a new one following `.agent/skills/creating-skills/SKILL.md`.
+The agent will check [skills.sh](https://skills.sh) first (`npx skills add https://github.com/vercel-labs/skills --skill find-skills -a antigravity -y --copy`), install a community skill if available, or create a new one following `.agent/skills/creating-skills/SKILL.md`.
 
 ---
 

package/adapters/cursor.md

@@ -1,6 +1,6 @@
 # Using Blueprint OS in Cursor
 
-Cursor reads rules from `.cursor/rules/` and skills from a skills directory. Blueprint OS skills live in `.agent/skills/` as portable markdown files. This guide shows how to connect them.
+Cursor reads rules from `.cursor/rules/` and skills from a skills directory. Blueprint OS skills live in `.agent/skills/` (singular) as portable markdown files. Cursor's native skills path is `.agents/skills/` (plural) — Blueprint OS uses `.agent/` and connects via rules and `@` references. Do not rename `.agent` to `.agents`; keep the Blueprint OS layout. This guide shows how to connect them.
 
 ---
 
@@ -23,6 +23,7 @@ Blueprint OS skills are located in `.agent/skills/`. When the user invokes a ski
 
 ## Available skills
 
+- **Find skills** → `.agent/skills/find-skills/SKILL.md` (pre-installed)
 - **Brainstorming** → `.agent/skills/brainstorming/SKILL.md`
 - **Creating skills** → `.agent/skills/creating-skills/SKILL.md`
 - **Shaping specs** → `.agent/skills/shaping-specs/SKILL.md`
@@ -128,4 +129,4 @@ Run QA after implementation. Run SEC when changes touch auth, API, or sensitive
 - Reference designs and diagrams in `references/` with `@references/checkout-flow.mmd` or `@references/agent-workflow/superpowers-link.md`
 - Brainstorm documents and spec files saved to `specs/` are readable the same way
 - The `.agent/` folder is invisible to most file trees by default — open it explicitly if needed
-- For skills.sh integration, see [skills-sh.md](skills-sh.md)
+- For skills.sh integration, see [skills-sh.md](skills-sh.md). Use `-a antigravity -y --copy` when installing so skills land in `.agent/skills/` as real files. Without `--copy`, the CLI may symlink from `.agents/`, and deleting `.agents` breaks the skill.

package/adapters/skills-sh.md

@@ -1,16 +1,28 @@
 # Using skills.sh with Blueprint OS
 
-[skills.sh](https://skills.sh) is an open registry of reusable agent skills. Skills install directly into `.agent/skills/` — the same directory Blueprint OS uses — so they work together with no extra configuration.
+[skills.sh](https://skills.sh) is an open registry of reusable agent skills. Blueprint OS uses `.agent/skills/` (singular). The skills CLI installs to different paths per agent — use the Antigravity target so skills land in `.agent/skills/` and work with Blueprint OS.
+
+---
+
+## Paths: `.agent` vs `.agents`
+
+The skills CLI uses agent-specific paths. Cursor, Codex, and other "Universal" agents use `.agents/skills/` (plural). Antigravity uses `.agent/skills/` (singular). Blueprint OS uses `.agent/skills/` for all adapters — Cursor reads from there via rules and `@` references, not from `.agents`. Always target Antigravity when installing so skills land in the correct folder.
+
+---
+
+## Symlinks: use `--copy` for Cursor
+
+The CLI defaults to symlinks. One location holds the canonical copy; others point to it. If Cursor is detected, the canonical copy may live in `.agents/`. Deleting `.agents` then breaks the skill in `.agent/`. Use `--copy` so `.agent/skills/` gets real files. You can safely remove `.agents` if the CLI creates it.
 
 ---
 
 ## How it works
 
-```
-npx skills add <owner/repo>
+```bash
+npx skills add <owner/repo> -a antigravity -y --copy
 ```
 
-This command installs one or more skills from a GitHub repo into your project's `.agent/skills/` folder. Installed skills are immediately available to your agent as Blueprint OS skills.
+The `-a antigravity` flag installs to `.agent/skills/`, matching Blueprint OS. The `--copy` flag creates real files (not symlinks) so deleting `.agents` won't break the skill. The `-y` flag skips prompts. Installed skills are immediately available via `@.agent/skills/<skill-name>/SKILL.md`.
 
 Skills.sh supports Cursor, Antigravity, Claude Code, Codex, Cline, Windsurf, and more — the same tools Blueprint OS targets.
 
@@ -21,7 +33,7 @@ Skills.sh supports Cursor, Antigravity, Claude Code, Codex, Cline, Windsurf, and
 **Option 1 — Use the find-skills skill:**
 
 ```bash
-npx skills add https://github.com/vercel-labs/skills --skill find-skills
+npx skills add https://github.com/vercel-labs/skills --skill find-skills -a antigravity -y --copy
 ```
 
 This installs a meta-skill that can search the registry for you. Then ask your agent:
@@ -36,7 +48,7 @@ Visit [skills.sh](https://skills.sh) and search by keyword or browse by category
 
 **Option 3 — Search by GitHub org:**
 
-Many popular tool maintainers publish official skills:
+Many popular tool maintainers publish official skills. Append `-a antigravity -y` for Blueprint OS:
 
 | Publisher | Install command | What's inside |
 |---|---|---|
@@ -53,10 +65,10 @@ Many popular tool maintainers publish official skills:
 
 ```bash
 # Single repo (may contain multiple skills)
-npx skills add supabase/agent-skills
+npx skills add supabase/agent-skills -a antigravity -y --copy
 
 # Install a specific skill by name
-npx skills add obra/superpowers systematic-debugging
+npx skills add obra/superpowers --skill systematic-debugging -a antigravity -y --copy
 ```
 
 Skills land in `.agent/skills/<skill-name>/SKILL.md`. Open them to inspect what was installed.
@@ -105,7 +117,7 @@ If you've built a Blueprint OS skill that others would benefit from, you can pub
 
 1. Push your `.agent/skills/<skill-name>/` folder to a public GitHub repo
 2. Submit your skill at [skills.sh](https://skills.sh) (follow the site's submission process)
-3. Others can then install it with `npx skills add <your-github-username>/<repo>`
+3. Others can then install it with `npx skills add <your-github-username>/<repo> -a antigravity -y --copy`
 
 **Tip:** Structure your repo so each skill is its own folder at the root — that's the convention the `npx skills add` command expects.
 
@@ -117,18 +129,19 @@ These community skills complement Blueprint OS directly:
 
 | Skill | Install | Pairs with |
 |---|---|---|
-| `systematic-debugging` | `npx skills add obra/superpowers` | Any execution phase |
-| `writing-plans` | `npx skills add obra/superpowers` | `shaping-specs` |
-| `executing-plans` | `npx skills add obra/superpowers` | After `deploying-standards` |
-| `requesting-code-review` | `npx skills add obra/superpowers` | After execution |
-| `api-design-principles` | `npx skills add wshobson/agents` | `discovering-standards` for API projects |
-| `test-driven-development` | `npx skills add obra/superpowers` | Before writing new features |
+| `systematic-debugging` | `npx skills add obra/superpowers -a antigravity -y --copy` | Any execution phase |
+| `writing-plans` | `npx skills add obra/superpowers -a antigravity -y --copy` | `shaping-specs` |
+| `executing-plans` | `npx skills add obra/superpowers -a antigravity -y --copy` | After `deploying-standards` |
+| `requesting-code-review` | `npx skills add obra/superpowers -a antigravity -y --copy` | After execution |
+| `api-design-principles` | `npx skills add wshobson/agents -a antigravity -y --copy` | `discovering-standards` for API projects |
+| `test-driven-development` | `npx skills add obra/superpowers -a antigravity -y --copy` | Before writing new features |
 
 ---
 
 ## Notes
 
 - skills.sh skills use the same `SKILL.md` format as Blueprint OS — no conversion needed
+- Always use `-a antigravity -y --copy` when installing. `-a antigravity` puts skills in `.agent/skills/`. `--copy` creates real files (not symlinks) so deleting `.agents` won't break the skill. Without it, the CLI may symlink from `.agents/`, and removing `.agents` breaks `.agent/`
 - If `npx skills add` is not available, clone the repo and copy the skill folder manually into `.agent/skills/`
 - Community skills may not follow all Blueprint OS conventions — review before use
 - Pin to a specific commit if you need a stable, reproducible skill version

package/package.json

@@ -1,33 +1,33 @@
-{
-  "name": "blueprint-os",
-  "version": "1.0.1",
-  "description": "A portable, tool-agnostic AI agent workflow system built on skills and standards",
-  "bin": {
-    "blueprint-os": "./bin/blueprint-os.js"
-  },
-  "files": [
-    ".agent",
-    "standards",
-    "references",
-    "adapters",
-    "bin",
-    "lib"
-  ],
-  "keywords": [
-    "ai",
-    "agent",
-    "workflow",
-    "cursor",
-    "claude",
-    "standards",
-    "specs"
-  ],
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/gj1342/blueprint-os"
-  },
-  "engines": {
-    "node": ">=18"
-  }
-}
+{
+  "name": "blueprint-os",
+  "version": "1.1.0",
+  "description": "A portable, tool-agnostic AI agent workflow system built on skills and standards",
+  "bin": {
+    "blueprint-os": "./bin/blueprint-os.js"
+  },
+  "files": [
+    ".agent",
+    "standards",
+    "references",
+    "adapters",
+    "bin",
+    "lib"
+  ],
+  "keywords": [
+    "ai",
+    "agent",
+    "workflow",
+    "cursor",
+    "claude",
+    "standards",
+    "specs"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gj1342/blueprint-os"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}