A comprehensive library of specialized AI agents and personas for GitHub Copilot, ranging from architectural planning and specific tech stacks to advanced cognitive reasoning models.
npm install workspace-architectnpx workspace-architect.
npx - no global installation needed
npx:
bash
npx workspace-architect list
or use the shorter alias
npx wsa list
`
Or install globally if you prefer:
`bash
npm install -g workspace-architect
`
Quick Start
List all available assets:
`bash
npx workspace-architect list
or use the shorter alias
npx wsa list
`
Download a collection for web development:
`bash
npx workspace-architect download collections web-frontend-development
or
npx wsa download collections web-frontend-development
`
Download a specific agent:
`bash
npx workspace-architect download agents azure-architect
or
npx wsa download agents azure-architect
`
Usage
$3
View all available assets or filter by type:
`bash
List all assets
npx workspace-architect list
or
npx wsa list
List specific types
npx workspace-architect list instructions
npx wsa list agents
npx wsa list prompts
npx wsa list collections
`
$3
Download assets to your project (default location: .github/):
`bash
npx workspace-architect download
or
npx wsa download
`
Examples:
`bash
Download an instruction
npx wsa download instructions reactjs
Download an agent
npx wsa download agents planner
Download a complete collection
npx wsa download collections devops-essentials
`
$3
- -d, --dry-run - Preview what will be downloaded without writing files
- -f, --force - Overwrite existing files without confirmation
- -o, --output - Specify custom output directory
Asset Types
Workspace Architect provides five types of assets:
| Type | Description | Location |
|------|-------------|----------|
| Instructions | System-level guidelines for Copilot context | .github/copilot-instructions.md |
| Prompts | Reusable templates for specific tasks | .github/prompts/ |
| Agents | Specialized personas defining Copilot behavior | .github/agents/ |
| Skills | Claude Skills with templates, scripts, and resources | .github/skills/ |
| Collections | Bundled assets for specific domains or workflows | Multiple locations |
$3
Skills are an emerging standard for packaging AI agent capabilities. Compatible with Claude, GitHub Copilot, and other AI platforms, Skills are folder-based assets containing:
- SKILL.md: Main instructions with metadata
- Templates: Document or code templates
- Scripts: Automation scripts (downloaded but not executed)
- Resources: Reference materials and examples
Skills follow the open Agent Skills specification and work across multiple AI platforms.
Example:
`bash
Download a Skill
npx workspace-architect download skills example-planner
List all Skills
npx workspace-architect list skills
`
For more information, see Skills User Guide and Skills vs Agents.
Roadmap
See ROADMAP.md for our development timeline, upcoming features, and current capabilities.
Contributing
We welcome contributions! Whether you want to add a new agent, improve existing prompts, or curate a collection, here's how you can help.
$3
1. Clone the repository:
`bash
git clone https://github.com/archubbuck/workspace-architect.git
cd workspace-architect
`
2. Install dependencies:
`bash
npm install
`
3. Test your changes:
`bash
node bin/cli.js list
`
$3
Create a markdown file in the appropriate directory with optional YAML frontmatter:
`markdown
---
title: My Custom Guide
description: A guide for setting up X.
---
Content starts here...
`
Naming Convention: Filenames become IDs (extensions are stripped)
- assets/instructions/my-guide.md ā ID: instructions:my-guide
- assets/agents/my-agent.agent.md ā ID: agents:my-agent
Note: The colon format (type:name) is used for internal IDs in collections and manifests. When using the CLI, use the space-separated format: npx wsa download instructions my-guide
$3
Create a JSON file in assets/collections/:
`json
{
"name": "My Collection",
"description": "A collection for X development.",
"items": {
"instructions": ["reactjs"],
"prompts": ["code-review"],
"agents": ["expert-architect"]
}
}
`
Collection Format: Collections use a nested object structure where items are grouped by type. Each type key contains an array of asset names (without the type prefix).
$3
- npm run generate-manifest - Generate assets-manifest.json (required before PRs)
- npm run migrate-collections - Migrate collections from old flat array format to new nested format
- npm run analyze - Analyze collections with TF-IDF/Cosine Similarity
- npm run analyze -- --add - Auto-add high-confidence matches
- npm run analyze -- --remove - Remove low-confidence items
- Sync scripts for upstream resources:
- npm run sync-agents - Sync agents from github/awesome-copilot
- npm run sync-instructions - Sync instructions from github/awesome-copilot
- npm run sync-prompts - Sync prompts from github/awesome-copilot
- npm run sync-collections - Sync collections from github/awesome-copilot
- npm run sync-skills - Sync skills from anthropics/skills
- npm run validate-skills - Validate all synced skills
#### Upstream Configuration
Sync scripts require a JSON configuration file for controlling which files are synced from upstream repositories using glob patterns. Create an upstream.config.json file in the project root:
`json
{
"upstreamRepos": [
{
"repo": "github/awesome-copilot",
"syncPatterns": ["agents//.md", "collections//.yml"]
},
{
"repo": "anthropics/skills",
"syncPatterns": ["skills/**/SKILL.md"]
}
]
}
`
Note: The configuration file is required. Sync scripts will fail if the file doesn't exist or doesn't contain configuration for the repository being synced.
See Upstream Configuration Guide for detailed documentation, examples, and best practices.
$3
Use Verdaccio for end-to-end testing:
`bash
Terminal 1: Start local registry
npm run start:registry
Terminal 2: Publish and test
npm run publish:local
npx --registry http://localhost:4873 workspace-architect list
npx --registry http://localhost:4873 wsa list
`
Project Structure
`
workspace-architect/
āāā assets/
ā āāā agents/ # Agent definitions (.agent.md)
ā āāā collections/ # Collection definitions (.json)
ā āāā instructions/ # Copilot instructions (.md)
ā āāā prompts/ # Reusable prompts (.md)
āāā bin/
ā āāā cli.js # CLI entry point
āāā scripts/ # Maintenance utilities
`
Migration Guide
$3
Note: This guide is for users migrating from the deprecated .chatmode.md format to the current .agent.md format.
If you have legacy .chatmode.md files, run:
`bash
mkdir -p assets/agents
find . -name '*.chatmode.md' -exec bash -c 'mv "$1" "assets/agents/$(basename \"$1\" .chatmode.md).agent.md"' -- {} \;
``