blueprint-os 1.0.2 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agent/skills/brainstorming/SKILL.md +157 -157
- package/.agent/skills/creating-skills/SKILL.md +7 -7
- package/.agent/skills/deploying-standards/SKILL.md +85 -85
- package/.agent/skills/discovering-standards/SKILL.md +107 -107
- package/.agent/skills/find-skills/SKILL.md +133 -0
- package/README.md +11 -8
- package/adapters/antigravity.md +2 -2
- package/adapters/cursor.md +3 -2
- package/adapters/skills-sh.md +28 -15
- package/package.json +33 -33
- package/references/agent-workflow/Skills.md +155 -155
- package/references/agent-workflow/blast.md +155 -155
- package/standards/README.md +123 -123
|
@@ -1,107 +1,107 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: discovering-standards
|
|
3
|
-
description: Extracts coding patterns, conventions, and architectural decisions from an existing codebase and saves them as standards files. Use when the user asks to document standards, capture patterns, extract conventions, or onboard an AI agent to an existing project.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Discovering Standards
|
|
7
|
-
|
|
8
|
-
## When to use this skill
|
|
9
|
-
|
|
10
|
-
- User asks to "document my standards", "capture my conventions", or "extract patterns from my code"
|
|
11
|
-
- Onboarding Blueprint OS to an existing project for the first time
|
|
12
|
-
- A recurring pattern has emerged that should be formalized
|
|
13
|
-
- Tribal knowledge exists in the code but not in writing
|
|
14
|
-
- Before brainstorming a new feature in an existing codebase — discover constraints first, then brainstorm within them
|
|
15
|
-
|
|
16
|
-
## Workflow
|
|
17
|
-
|
|
18
|
-
- [ ] Identify which area to document (ask user if unclear)
|
|
19
|
-
- [ ] Scan relevant files in that area
|
|
20
|
-
- [ ] Identify recurring patterns, naming conventions, and architectural decisions
|
|
21
|
-
- [ ] Draft a standards file and confirm with the user
|
|
22
|
-
- [ ] Save to `standards/<category>.md`
|
|
23
|
-
- [ ] Update `standards/README.md` index if the file is new
|
|
24
|
-
|
|
25
|
-
## Instructions
|
|
26
|
-
|
|
27
|
-
### Discovery areas
|
|
28
|
-
|
|
29
|
-
Approach one area at a time. Common areas to document:
|
|
30
|
-
|
|
31
|
-
- **Tech stack** — languages, frameworks, libraries, versions
|
|
32
|
-
- **Folder structure** — how the project is organized and why
|
|
33
|
-
- **Naming conventions** — files, variables, components, routes, database columns
|
|
34
|
-
- **Component patterns** — how UI components are structured and composed
|
|
35
|
-
- **API design** — endpoint naming, request/response shapes, error handling
|
|
36
|
-
- **Data models** — schema conventions, relationships, field naming
|
|
37
|
-
- **Testing approach** — test file location, naming, tooling, coverage expectations
|
|
38
|
-
- **Error handling** — how errors surface, are logged, and returned to clients
|
|
39
|
-
- **State management** — how application state is structured and updated
|
|
40
|
-
- **Authentication** — how auth is implemented and enforced
|
|
41
|
-
|
|
42
|
-
### Extraction process
|
|
43
|
-
|
|
44
|
-
For each area:
|
|
45
|
-
|
|
46
|
-
1. Read 3–5 representative files
|
|
47
|
-
2. Identify what is consistent across them (naming, structure, patterns)
|
|
48
|
-
3. Note any exceptions — are they intentional or accidental?
|
|
49
|
-
4. Write only what the agent needs to replicate the pattern, not what is obvious
|
|
50
|
-
|
|
51
|
-
### Standards file format
|
|
52
|
-
|
|
53
|
-
Save to `standards/<category>.md`:
|
|
54
|
-
|
|
55
|
-
```markdown
|
|
56
|
-
# [Category] Standards
|
|
57
|
-
|
|
58
|
-
**Last updated:** [YYYY-MM-DD]
|
|
59
|
-
|
|
60
|
-
## Overview
|
|
61
|
-
[One paragraph: what this standard covers and why it exists]
|
|
62
|
-
|
|
63
|
-
## Conventions
|
|
64
|
-
|
|
65
|
-
### [Convention name]
|
|
66
|
-
[Description of the pattern]
|
|
67
|
-
|
|
68
|
-
**Example:**
|
|
69
|
-
[code example or file path showing the pattern]
|
|
70
|
-
|
|
71
|
-
**Avoid:**
|
|
72
|
-
[counter-example if useful]
|
|
73
|
-
|
|
74
|
-
## Exceptions
|
|
75
|
-
[Known deviations and why they exist]
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
### What to capture vs. skip
|
|
79
|
-
|
|
80
|
-
**Capture:**
|
|
81
|
-
- Decisions that aren't obvious from reading a single file
|
|
82
|
-
- Patterns that repeat across the codebase
|
|
83
|
-
- Choices that differ from common defaults (e.g., "we use tabs, not spaces")
|
|
84
|
-
- Architectural boundaries (e.g., "services never import from controllers")
|
|
85
|
-
|
|
86
|
-
**Skip:**
|
|
87
|
-
- Things the language or framework enforces automatically
|
|
88
|
-
- One-off implementations with no pattern
|
|
89
|
-
- Preferences with no clear rationale
|
|
90
|
-
|
|
91
|
-
### File naming
|
|
92
|
-
|
|
93
|
-
Use lowercase, hyphen-separated names that match the category:
|
|
94
|
-
|
|
95
|
-
```
|
|
96
|
-
standards/tech-stack.md
|
|
97
|
-
standards/naming-conventions.md
|
|
98
|
-
standards/api-design.md
|
|
99
|
-
standards/component-patterns.md
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
## Resources
|
|
103
|
-
|
|
104
|
-
- Standards directory: `standards/`
|
|
105
|
-
- Standards guide: `standards/README.md`
|
|
106
|
-
- Next step for new feature work: `.agent/skills/brainstorming/SKILL.md` (brainstorm within discovered constraints)
|
|
107
|
-
- Next step before implementation: `.agent/skills/deploying-standards/SKILL.md`
|
|
1
|
+
---
|
|
2
|
+
name: discovering-standards
|
|
3
|
+
description: Extracts coding patterns, conventions, and architectural decisions from an existing codebase and saves them as standards files. Use when the user asks to document standards, capture patterns, extract conventions, or onboard an AI agent to an existing project.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Discovering Standards
|
|
7
|
+
|
|
8
|
+
## When to use this skill
|
|
9
|
+
|
|
10
|
+
- User asks to "document my standards", "capture my conventions", or "extract patterns from my code"
|
|
11
|
+
- Onboarding Blueprint OS to an existing project for the first time
|
|
12
|
+
- A recurring pattern has emerged that should be formalized
|
|
13
|
+
- Tribal knowledge exists in the code but not in writing
|
|
14
|
+
- Before brainstorming a new feature in an existing codebase — discover constraints first, then brainstorm within them
|
|
15
|
+
|
|
16
|
+
## Workflow
|
|
17
|
+
|
|
18
|
+
- [ ] Identify which area to document (ask user if unclear)
|
|
19
|
+
- [ ] Scan relevant files in that area
|
|
20
|
+
- [ ] Identify recurring patterns, naming conventions, and architectural decisions
|
|
21
|
+
- [ ] Draft a standards file and confirm with the user
|
|
22
|
+
- [ ] Save to `standards/<category>.md`
|
|
23
|
+
- [ ] Update `standards/README.md` index if the file is new
|
|
24
|
+
|
|
25
|
+
## Instructions
|
|
26
|
+
|
|
27
|
+
### Discovery areas
|
|
28
|
+
|
|
29
|
+
Approach one area at a time. Common areas to document:
|
|
30
|
+
|
|
31
|
+
- **Tech stack** — languages, frameworks, libraries, versions
|
|
32
|
+
- **Folder structure** — how the project is organized and why
|
|
33
|
+
- **Naming conventions** — files, variables, components, routes, database columns
|
|
34
|
+
- **Component patterns** — how UI components are structured and composed
|
|
35
|
+
- **API design** — endpoint naming, request/response shapes, error handling
|
|
36
|
+
- **Data models** — schema conventions, relationships, field naming
|
|
37
|
+
- **Testing approach** — test file location, naming, tooling, coverage expectations
|
|
38
|
+
- **Error handling** — how errors surface, are logged, and returned to clients
|
|
39
|
+
- **State management** — how application state is structured and updated
|
|
40
|
+
- **Authentication** — how auth is implemented and enforced
|
|
41
|
+
|
|
42
|
+
### Extraction process
|
|
43
|
+
|
|
44
|
+
For each area:
|
|
45
|
+
|
|
46
|
+
1. Read 3–5 representative files
|
|
47
|
+
2. Identify what is consistent across them (naming, structure, patterns)
|
|
48
|
+
3. Note any exceptions — are they intentional or accidental?
|
|
49
|
+
4. Write only what the agent needs to replicate the pattern, not what is obvious
|
|
50
|
+
|
|
51
|
+
### Standards file format
|
|
52
|
+
|
|
53
|
+
Save to `standards/<category>.md`:
|
|
54
|
+
|
|
55
|
+
```markdown
|
|
56
|
+
# [Category] Standards
|
|
57
|
+
|
|
58
|
+
**Last updated:** [YYYY-MM-DD]
|
|
59
|
+
|
|
60
|
+
## Overview
|
|
61
|
+
[One paragraph: what this standard covers and why it exists]
|
|
62
|
+
|
|
63
|
+
## Conventions
|
|
64
|
+
|
|
65
|
+
### [Convention name]
|
|
66
|
+
[Description of the pattern]
|
|
67
|
+
|
|
68
|
+
**Example:**
|
|
69
|
+
[code example or file path showing the pattern]
|
|
70
|
+
|
|
71
|
+
**Avoid:**
|
|
72
|
+
[counter-example if useful]
|
|
73
|
+
|
|
74
|
+
## Exceptions
|
|
75
|
+
[Known deviations and why they exist]
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
### What to capture vs. skip
|
|
79
|
+
|
|
80
|
+
**Capture:**
|
|
81
|
+
- Decisions that aren't obvious from reading a single file
|
|
82
|
+
- Patterns that repeat across the codebase
|
|
83
|
+
- Choices that differ from common defaults (e.g., "we use tabs, not spaces")
|
|
84
|
+
- Architectural boundaries (e.g., "services never import from controllers")
|
|
85
|
+
|
|
86
|
+
**Skip:**
|
|
87
|
+
- Things the language or framework enforces automatically
|
|
88
|
+
- One-off implementations with no pattern
|
|
89
|
+
- Preferences with no clear rationale
|
|
90
|
+
|
|
91
|
+
### File naming
|
|
92
|
+
|
|
93
|
+
Use lowercase, hyphen-separated names that match the category:
|
|
94
|
+
|
|
95
|
+
```
|
|
96
|
+
standards/tech-stack.md
|
|
97
|
+
standards/naming-conventions.md
|
|
98
|
+
standards/api-design.md
|
|
99
|
+
standards/component-patterns.md
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## Resources
|
|
103
|
+
|
|
104
|
+
- Standards directory: `standards/`
|
|
105
|
+
- Standards guide: `standards/README.md`
|
|
106
|
+
- Next step for new feature work: `.agent/skills/brainstorming/SKILL.md` (brainstorm within discovered constraints)
|
|
107
|
+
- Next step before implementation: `.agent/skills/deploying-standards/SKILL.md`
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: find-skills
|
|
3
|
+
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.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Find Skills
|
|
7
|
+
|
|
8
|
+
This skill helps you discover and install skills from the open agent skills ecosystem.
|
|
9
|
+
|
|
10
|
+
## When to Use This Skill
|
|
11
|
+
|
|
12
|
+
Use this skill when the user:
|
|
13
|
+
|
|
14
|
+
- Asks "how do I do X" where X might be a common task with an existing skill
|
|
15
|
+
- Says "find a skill for X" or "is there a skill for X"
|
|
16
|
+
- Asks "can you do X" where X is a specialized capability
|
|
17
|
+
- Expresses interest in extending agent capabilities
|
|
18
|
+
- Wants to search for tools, templates, or workflows
|
|
19
|
+
- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
|
|
20
|
+
|
|
21
|
+
## What is the Skills CLI?
|
|
22
|
+
|
|
23
|
+
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.
|
|
24
|
+
|
|
25
|
+
**Key commands:**
|
|
26
|
+
|
|
27
|
+
- `npx skills find [query]` - Search for skills interactively or by keyword
|
|
28
|
+
- `npx skills add <package>` - Install a skill from GitHub or other sources
|
|
29
|
+
- `npx skills check` - Check for skill updates
|
|
30
|
+
- `npx skills update` - Update all installed skills
|
|
31
|
+
|
|
32
|
+
**Browse skills at:** https://skills.sh/
|
|
33
|
+
|
|
34
|
+
## How to Help Users Find Skills
|
|
35
|
+
|
|
36
|
+
### Step 1: Understand What They Need
|
|
37
|
+
|
|
38
|
+
When a user asks for help with something, identify:
|
|
39
|
+
|
|
40
|
+
1. The domain (e.g., React, testing, design, deployment)
|
|
41
|
+
2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
|
|
42
|
+
3. Whether this is a common enough task that a skill likely exists
|
|
43
|
+
|
|
44
|
+
### Step 2: Search for Skills
|
|
45
|
+
|
|
46
|
+
Run the find command with a relevant query:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
npx skills find [query]
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
For example:
|
|
53
|
+
|
|
54
|
+
- User asks "how do I make my React app faster?" → `npx skills find react performance`
|
|
55
|
+
- User asks "can you help me with PR reviews?" → `npx skills find pr review`
|
|
56
|
+
- User asks "I need to create a changelog" → `npx skills find changelog`
|
|
57
|
+
|
|
58
|
+
The command will return results like:
|
|
59
|
+
|
|
60
|
+
```
|
|
61
|
+
Install with npx skills add <owner/repo@skill>
|
|
62
|
+
|
|
63
|
+
vercel-labs/agent-skills@vercel-react-best-practices
|
|
64
|
+
└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### Step 3: Present Options to the User
|
|
68
|
+
|
|
69
|
+
When you find relevant skills, present them to the user with:
|
|
70
|
+
|
|
71
|
+
1. The skill name and what it does
|
|
72
|
+
2. The install command they can run
|
|
73
|
+
3. A link to learn more at skills.sh
|
|
74
|
+
|
|
75
|
+
Example response:
|
|
76
|
+
|
|
77
|
+
```
|
|
78
|
+
I found a skill that might help! The "vercel-react-best-practices" skill provides
|
|
79
|
+
React and Next.js performance optimization guidelines from Vercel Engineering.
|
|
80
|
+
|
|
81
|
+
To install it:
|
|
82
|
+
npx skills add vercel-labs/agent-skills@vercel-react-best-practices
|
|
83
|
+
|
|
84
|
+
Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
### Step 4: Offer to Install
|
|
88
|
+
|
|
89
|
+
If the user wants to proceed, you can install the skill for them:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
npx skills add <owner/repo@skill> -g -y
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
|
|
96
|
+
|
|
97
|
+
## Common Skill Categories
|
|
98
|
+
|
|
99
|
+
When searching, consider these common categories:
|
|
100
|
+
|
|
101
|
+
| Category | Example Queries |
|
|
102
|
+
| --------------- | ---------------------------------------- |
|
|
103
|
+
| Web Development | react, nextjs, typescript, css, tailwind |
|
|
104
|
+
| Testing | testing, jest, playwright, e2e |
|
|
105
|
+
| DevOps | deploy, docker, kubernetes, ci-cd |
|
|
106
|
+
| Documentation | docs, readme, changelog, api-docs |
|
|
107
|
+
| Code Quality | review, lint, refactor, best-practices |
|
|
108
|
+
| Design | ui, ux, design-system, accessibility |
|
|
109
|
+
| Productivity | workflow, automation, git |
|
|
110
|
+
|
|
111
|
+
## Tips for Effective Searches
|
|
112
|
+
|
|
113
|
+
1. **Use specific keywords**: "react testing" is better than just "testing"
|
|
114
|
+
2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
|
|
115
|
+
3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
|
|
116
|
+
|
|
117
|
+
## When No Skills Are Found
|
|
118
|
+
|
|
119
|
+
If no relevant skills exist:
|
|
120
|
+
|
|
121
|
+
1. Acknowledge that no existing skill was found
|
|
122
|
+
2. Offer to help with the task directly using your general capabilities
|
|
123
|
+
3. Suggest the user could create their own skill with `npx skills init`
|
|
124
|
+
|
|
125
|
+
Example:
|
|
126
|
+
|
|
127
|
+
```
|
|
128
|
+
I searched for skills related to "xyz" but didn't find any matches.
|
|
129
|
+
I can still help you with this task directly! Would you like me to proceed?
|
|
130
|
+
|
|
131
|
+
If this is something you do often, you could create your own skill:
|
|
132
|
+
npx skills init my-xyz-skill
|
|
133
|
+
```
|
package/README.md
CHANGED
|
@@ -79,7 +79,7 @@ From your project directory:
|
|
|
79
79
|
npx blueprint-os init
|
|
80
80
|
```
|
|
81
81
|
|
|
82
|
-
This copies `.agent/`, `standards/`, `references/`, and `adapters/` into your project. No dependency is added to `package.json`.
|
|
82
|
+
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.
|
|
83
83
|
|
|
84
84
|
**Or copy manually:** Place the `.agent/` folder, `standards/` folder, and `references/` folder at the root of your project:
|
|
85
85
|
|
|
@@ -87,6 +87,9 @@ This copies `.agent/`, `standards/`, `references/`, and `adapters/` into your pr
|
|
|
87
87
|
your-project/
|
|
88
88
|
├── .agent/
|
|
89
89
|
│ └── skills/
|
|
90
|
+
│ ├── find-skills/ ← pre-installed
|
|
91
|
+
│ ├── brainstorming/
|
|
92
|
+
│ └── ...
|
|
90
93
|
├── standards/
|
|
91
94
|
├── references/
|
|
92
95
|
└── ... your code
|
|
@@ -124,8 +127,8 @@ your-project/
|
|
|
124
127
|
**Adding a new skill:**
|
|
125
128
|
|
|
126
129
|
```
|
|
127
|
-
1.
|
|
128
|
-
2. If found: npx skills add <owner/repo>
|
|
130
|
+
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
|
|
131
|
+
2. If found: npx skills add <owner/repo> -a antigravity -y --copy
|
|
129
132
|
3. If not found: ask your agent "Read .agent/skills/creating-skills/SKILL.md and create a skill for [task]"
|
|
130
133
|
```
|
|
131
134
|
|
|
@@ -137,6 +140,7 @@ Skills live in `.agent/skills/`. Each skill is a `SKILL.md` file the agent reads
|
|
|
137
140
|
|
|
138
141
|
| Skill | Path | Purpose |
|
|
139
142
|
|---|---|---|
|
|
143
|
+
| Find Skills | `.agent/skills/find-skills/` | Search the skills.sh registry for community skills (pre-installed) |
|
|
140
144
|
| Brainstorming | `.agent/skills/brainstorming/` | Explore problems, compare approaches, produce a design document |
|
|
141
145
|
| Creating Skills | `.agent/skills/creating-skills/` | Find on skills.sh first, author from scratch as fallback |
|
|
142
146
|
| 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
|
|
|
146
150
|
| Security Audit | `.agent/skills/security-audit/` | Audit auth, API, and sensitive data changes before merge |
|
|
147
151
|
| Code Review | `.agent/skills/code-review/` | Final validation against spec and standards before merge |
|
|
148
152
|
|
|
149
|
-
**Community skills** from [skills.sh](https://skills.sh) install
|
|
153
|
+
**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.
|
|
150
154
|
|
|
151
155
|
---
|
|
152
156
|
|
|
@@ -258,17 +262,16 @@ Agent loads `component-patterns.md`, `error-handling.md`, and any relevant refer
|
|
|
258
262
|
|
|
259
263
|
You want the agent to follow a strict TDD workflow but Blueprint OS has no skill for it.
|
|
260
264
|
|
|
261
|
-
**Step 1:
|
|
265
|
+
**Step 1: Use the pre-installed find-skills**
|
|
262
266
|
```
|
|
263
|
-
|
|
267
|
+
Read .agent/skills/find-skills/SKILL.md and find a skill for test-driven development
|
|
264
268
|
```
|
|
265
|
-
Then: `Use the find-skills skill to search for a test-driven development skill`
|
|
266
269
|
|
|
267
270
|
Found: `obra/superpowers` has `test-driven-development`.
|
|
268
271
|
|
|
269
272
|
**Step 2: Install it**
|
|
270
273
|
```
|
|
271
|
-
npx skills add obra/superpowers test-driven-development
|
|
274
|
+
npx skills add obra/superpowers --skill test-driven-development -a antigravity -y --copy
|
|
272
275
|
```
|
|
273
276
|
Lands in `.agent/skills/test-driven-development/SKILL.md` — immediately available.
|
|
274
277
|
|
package/adapters/antigravity.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Using Blueprint OS in Antigravity
|
|
2
2
|
|
|
3
|
-
Blueprint OS uses the `.agent/skills/` structure natively — the same format Antigravity expects. No extra setup required.
|
|
3
|
+
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.
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
@@ -133,7 +133,7 @@ Use the `creating-skills` skill — it searches skills.sh first, then creates fr
|
|
|
133
133
|
Find or create a skill for [task]
|
|
134
134
|
```
|
|
135
135
|
|
|
136
|
-
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`.
|
|
136
|
+
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`.
|
|
137
137
|
|
|
138
138
|
---
|
|
139
139
|
|
package/adapters/cursor.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Using Blueprint OS in Cursor
|
|
2
2
|
|
|
3
|
-
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.
|
|
3
|
+
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.
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
@@ -23,6 +23,7 @@ Blueprint OS skills are located in `.agent/skills/`. When the user invokes a ski
|
|
|
23
23
|
|
|
24
24
|
## Available skills
|
|
25
25
|
|
|
26
|
+
- **Find skills** → `.agent/skills/find-skills/SKILL.md` (pre-installed)
|
|
26
27
|
- **Brainstorming** → `.agent/skills/brainstorming/SKILL.md`
|
|
27
28
|
- **Creating skills** → `.agent/skills/creating-skills/SKILL.md`
|
|
28
29
|
- **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
|
|
|
128
129
|
- Reference designs and diagrams in `references/` with `@references/checkout-flow.mmd` or `@references/agent-workflow/superpowers-link.md`
|
|
129
130
|
- Brainstorm documents and spec files saved to `specs/` are readable the same way
|
|
130
131
|
- The `.agent/` folder is invisible to most file trees by default — open it explicitly if needed
|
|
131
|
-
- For skills.sh integration, see [skills-sh.md](skills-sh.md)
|
|
132
|
+
- 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
CHANGED
|
@@ -1,16 +1,28 @@
|
|
|
1
1
|
# Using skills.sh with Blueprint OS
|
|
2
2
|
|
|
3
|
-
[skills.sh](https://skills.sh) is an open registry of reusable agent skills.
|
|
3
|
+
[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.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Paths: `.agent` vs `.agents`
|
|
8
|
+
|
|
9
|
+
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.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Symlinks: use `--copy` for Cursor
|
|
14
|
+
|
|
15
|
+
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.
|
|
4
16
|
|
|
5
17
|
---
|
|
6
18
|
|
|
7
19
|
## How it works
|
|
8
20
|
|
|
9
|
-
```
|
|
10
|
-
npx skills add <owner/repo>
|
|
21
|
+
```bash
|
|
22
|
+
npx skills add <owner/repo> -a antigravity -y --copy
|
|
11
23
|
```
|
|
12
24
|
|
|
13
|
-
|
|
25
|
+
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`.
|
|
14
26
|
|
|
15
27
|
Skills.sh supports Cursor, Antigravity, Claude Code, Codex, Cline, Windsurf, and more — the same tools Blueprint OS targets.
|
|
16
28
|
|
|
@@ -21,7 +33,7 @@ Skills.sh supports Cursor, Antigravity, Claude Code, Codex, Cline, Windsurf, and
|
|
|
21
33
|
**Option 1 — Use the find-skills skill:**
|
|
22
34
|
|
|
23
35
|
```bash
|
|
24
|
-
npx skills add https://github.com/vercel-labs/skills --skill find-skills
|
|
36
|
+
npx skills add https://github.com/vercel-labs/skills --skill find-skills -a antigravity -y --copy
|
|
25
37
|
```
|
|
26
38
|
|
|
27
39
|
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
|
|
|
36
48
|
|
|
37
49
|
**Option 3 — Search by GitHub org:**
|
|
38
50
|
|
|
39
|
-
Many popular tool maintainers publish official skills:
|
|
51
|
+
Many popular tool maintainers publish official skills. Append `-a antigravity -y` for Blueprint OS:
|
|
40
52
|
|
|
41
53
|
| Publisher | Install command | What's inside |
|
|
42
54
|
|---|---|---|
|
|
@@ -53,10 +65,10 @@ Many popular tool maintainers publish official skills:
|
|
|
53
65
|
|
|
54
66
|
```bash
|
|
55
67
|
# Single repo (may contain multiple skills)
|
|
56
|
-
npx skills add supabase/agent-skills
|
|
68
|
+
npx skills add supabase/agent-skills -a antigravity -y --copy
|
|
57
69
|
|
|
58
70
|
# Install a specific skill by name
|
|
59
|
-
npx skills add obra/superpowers systematic-debugging
|
|
71
|
+
npx skills add obra/superpowers --skill systematic-debugging -a antigravity -y --copy
|
|
60
72
|
```
|
|
61
73
|
|
|
62
74
|
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
|
|
|
105
117
|
|
|
106
118
|
1. Push your `.agent/skills/<skill-name>/` folder to a public GitHub repo
|
|
107
119
|
2. Submit your skill at [skills.sh](https://skills.sh) (follow the site's submission process)
|
|
108
|
-
3. Others can then install it with `npx skills add <your-github-username>/<repo
|
|
120
|
+
3. Others can then install it with `npx skills add <your-github-username>/<repo> -a antigravity -y --copy`
|
|
109
121
|
|
|
110
122
|
**Tip:** Structure your repo so each skill is its own folder at the root — that's the convention the `npx skills add` command expects.
|
|
111
123
|
|
|
@@ -117,18 +129,19 @@ These community skills complement Blueprint OS directly:
|
|
|
117
129
|
|
|
118
130
|
| Skill | Install | Pairs with |
|
|
119
131
|
|---|---|---|
|
|
120
|
-
| `systematic-debugging` | `npx skills add obra/superpowers` | Any execution phase |
|
|
121
|
-
| `writing-plans` | `npx skills add obra/superpowers` | `shaping-specs` |
|
|
122
|
-
| `executing-plans` | `npx skills add obra/superpowers` | After `deploying-standards` |
|
|
123
|
-
| `requesting-code-review` | `npx skills add obra/superpowers` | After execution |
|
|
124
|
-
| `api-design-principles` | `npx skills add wshobson/agents` | `discovering-standards` for API projects |
|
|
125
|
-
| `test-driven-development` | `npx skills add obra/superpowers` | Before writing new features |
|
|
132
|
+
| `systematic-debugging` | `npx skills add obra/superpowers -a antigravity -y --copy` | Any execution phase |
|
|
133
|
+
| `writing-plans` | `npx skills add obra/superpowers -a antigravity -y --copy` | `shaping-specs` |
|
|
134
|
+
| `executing-plans` | `npx skills add obra/superpowers -a antigravity -y --copy` | After `deploying-standards` |
|
|
135
|
+
| `requesting-code-review` | `npx skills add obra/superpowers -a antigravity -y --copy` | After execution |
|
|
136
|
+
| `api-design-principles` | `npx skills add wshobson/agents -a antigravity -y --copy` | `discovering-standards` for API projects |
|
|
137
|
+
| `test-driven-development` | `npx skills add obra/superpowers -a antigravity -y --copy` | Before writing new features |
|
|
126
138
|
|
|
127
139
|
---
|
|
128
140
|
|
|
129
141
|
## Notes
|
|
130
142
|
|
|
131
143
|
- skills.sh skills use the same `SKILL.md` format as Blueprint OS — no conversion needed
|
|
144
|
+
- 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/`
|
|
132
145
|
- If `npx skills add` is not available, clone the repo and copy the skill folder manually into `.agent/skills/`
|
|
133
146
|
- Community skills may not follow all Blueprint OS conventions — review before use
|
|
134
147
|
- Pin to a specific commit if you need a stable, reproducible skill version
|
package/package.json
CHANGED
|
@@ -1,33 +1,33 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "blueprint-os",
|
|
3
|
-
"version": "1.0
|
|
4
|
-
"description": "A portable, tool-agnostic AI agent workflow system built on skills and standards",
|
|
5
|
-
"bin": {
|
|
6
|
-
"blueprint-os": "./bin/blueprint-os.js"
|
|
7
|
-
},
|
|
8
|
-
"files": [
|
|
9
|
-
".agent",
|
|
10
|
-
"standards",
|
|
11
|
-
"references",
|
|
12
|
-
"adapters",
|
|
13
|
-
"bin",
|
|
14
|
-
"lib"
|
|
15
|
-
],
|
|
16
|
-
"keywords": [
|
|
17
|
-
"ai",
|
|
18
|
-
"agent",
|
|
19
|
-
"workflow",
|
|
20
|
-
"cursor",
|
|
21
|
-
"claude",
|
|
22
|
-
"standards",
|
|
23
|
-
"specs"
|
|
24
|
-
],
|
|
25
|
-
"license": "MIT",
|
|
26
|
-
"repository": {
|
|
27
|
-
"type": "git",
|
|
28
|
-
"url": "https://github.com/gj1342/blueprint-os"
|
|
29
|
-
},
|
|
30
|
-
"engines": {
|
|
31
|
-
"node": ">=18"
|
|
32
|
-
}
|
|
33
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "blueprint-os",
|
|
3
|
+
"version": "1.1.0",
|
|
4
|
+
"description": "A portable, tool-agnostic AI agent workflow system built on skills and standards",
|
|
5
|
+
"bin": {
|
|
6
|
+
"blueprint-os": "./bin/blueprint-os.js"
|
|
7
|
+
},
|
|
8
|
+
"files": [
|
|
9
|
+
".agent",
|
|
10
|
+
"standards",
|
|
11
|
+
"references",
|
|
12
|
+
"adapters",
|
|
13
|
+
"bin",
|
|
14
|
+
"lib"
|
|
15
|
+
],
|
|
16
|
+
"keywords": [
|
|
17
|
+
"ai",
|
|
18
|
+
"agent",
|
|
19
|
+
"workflow",
|
|
20
|
+
"cursor",
|
|
21
|
+
"claude",
|
|
22
|
+
"standards",
|
|
23
|
+
"specs"
|
|
24
|
+
],
|
|
25
|
+
"license": "MIT",
|
|
26
|
+
"repository": {
|
|
27
|
+
"type": "git",
|
|
28
|
+
"url": "https://github.com/gj1342/blueprint-os"
|
|
29
|
+
},
|
|
30
|
+
"engines": {
|
|
31
|
+
"node": ">=18"
|
|
32
|
+
}
|
|
33
|
+
}
|