Skip to content

Commit fd4362c

Browse files
aRustyDevclaude
aRustyDev
and
claude
committed
docs: rewrite README to reflect current repo state
Replaced outdated README (referenced legacy/, components/, profiles/ directories that no longer exist) with current architecture: - CLI commands for skill/mcp/component management - Universal component model with 7 providers - 19 AI client config support - Plugin marketplace - Dependency management table Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent f11f6de commit fd4362c

1 file changed

Lines changed: 101 additions & 191 deletions

File tree

‎README.md‎

Lines changed: 101 additions & 191 deletions
Original file line numberDiff line numberDiff line change
@@ -1,234 +1,144 @@
1-
# AI Configuration Library
1+
# Agents — AI Context Library
22

3-
Shareable source of truth for AI-related configurations: rules, skills, commands, hooks, context, and MCP server definitions.
3+
Reusable Claude Code components: skills, agents, commands, rules, plugins, MCP server configurations, and a universal component management system.
44

5-
## Architecture
6-
7-
```text
8-
Project .claude/ ──promote──▶ ai/ (source) ──build──▶ global (~/.claude/)
9-
│
10-
▼
11-
dotfiles/
12-
(deployment layer)
13-
```
14-
15-
This repo contains atomic, reusable components that can be composed into tool-specific configurations based on machine profiles.
16-
17-
## Directory Structure
18-
19-
```text
20-
ai/
21-
├── components/ # Atomic, reusable pieces
22-
│ ├── rules/ # Instruction rules (schema'd JSON, future)
23-
│ ├── skills/ # Claude Code skills (SKILL.md + files)
24-
│ ├── commands/ # Slash command templates
25-
│ ├── hooks/ # Hook definitions
26-
│ └── context/ # Shared context fragments
27-
│
28-
├── profiles/ # Machine/use-case profiles (future)
29-
│ ├── personal.profile.json
30-
│ ├── work.profile.json
31-
│ └── minimal.profile.json
32-
│
33-
├── tools/ # Tool-specific output schemas (future)
34-
│ ├── claude-code/
35-
│ ├── zed/
36-
│ ├── claude-desktop/
37-
│ └── vscode/
38-
│
39-
├── mcp/ # MCP server definitions
40-
│ ├── global/ # Remote/HTTP MCP servers
41-
│ └── local/ # Project-scoped MCP templates
42-
│
43-
├── schemas/ # JSON schemas for validation (future)
44-
├── build/ # Build/compile tooling (future)
45-
├── dist/ # Generated output (gitignored)
46-
│
47-
└── legacy/ # Previous content (migrating from)
48-
```
49-
50-
## Usage
51-
52-
### As a Submodule (Recommended)
5+
## Quick Start
536

547
```bash
55-
# In your dotfiles repo
56-
git submodule add git@github.com:aRustyDev/agents.git ai/
57-
git submodule update --init --recursive
8+
just init # Install deps, init knowledge graph, pull embedding model
9+
just agents --help # CLI tool for component management
5810
```
5911

60-
### Installing Components
61-
62-
For now, manually copy components to target locations:
12+
## Architecture
6313

64-
```bash
65-
# Claude Code
66-
cp -r ai/components/commands/* ~/.claude/commands/
67-
cp -r ai/components/skills/* ~/.claude/skills/
68-
cp -r ai/components/rules/* ~/.claude/rules/
6914
```
70-
71-
Future: Use `just ai-build` and `just ai-deploy` from dotfiles repo.
72-
73-
## Plugin Marketplace
74-
75-
This repo includes a plugin marketplace at `.claude-plugin/marketplace.json` with curated plugin bundles.
76-
77-
### Available Plugins
78-
79-
| Plugin | Description |
80-
|--------|-------------|
81-
| `homebrew-dev` | Homebrew formula development toolkit |
82-
| `browser-extension-dev` | Cross-browser extension development (Firefox, Chrome, Safari) |
83-
| `blog-workflow` | Technical blog post creation workflow |
84-
| `job-hunting` | Job hunting toolkit (resume, applications, research) |
85-
| `swiftui-dev` | SwiftUI development with testing and data analytics |
86-
87-
### Installing a Plugin
88-
89-
```bash
90-
# Clone or add as submodule
91-
git clone https://github.com/aRustyDev/agents.git ~/ai-plugins
92-
93-
# Copy a plugin to your Claude Code config
94-
cp -r ~/ai-plugins/context/plugins/homebrew-dev ~/.claude/plugins/
95-
96-
# Or symlink for auto-updates
97-
ln -s ~/ai-plugins/context/plugins/homebrew-dev ~/.claude/plugins/homebrew-dev
15+
context/ Component source of truth
16+
├── skills/ SKILL.md files (130+)
17+
├── agents/ Agent definitions (markdown + frontmatter)
18+
├── commands/ Slash commands (markdown + frontmatter)
19+
├── rules/ Instruction rules (markdown)
20+
├── plugins/ Plugin bundles (.claude-plugin/plugin.json)
21+
├── hooks/ Hook configurations
22+
├── output-styles/ Output formatting templates
23+
└── reference/ Reference documentation
24+
25+
.scripts/ TypeScript tooling (Bun + Citty)
26+
├── bin/agents.ts CLI entrypoint
27+
├── commands/ CLI command trees (skill, mcp, component, plugin, ...)
28+
├── lib/ Library modules
29+
│ ├── component/ Universal component model (7 providers)
30+
│ ├── skill-*.ts Skill lifecycle (add/find/list/outdated/update/remove/info/init)
31+
│ └── ... Hash, lockfile, output, runtime, schemas, etc.
32+
└── test/ bun:test suites (900+ tests)
33+
34+
settings/mcp/ MCP server configurations
35+
docs/src/adr/ Architecture Decision Records
9836
```
9937

100-
### Adding This Marketplace
101-
102-
To use this marketplace as a plugin source:
103-
104-
1. **Via settings.json** (Claude Code):
38+
## CLI Commands
10539

106-
```json
107-
{
108-
"pluginMarketplaces": [
109-
{
110-
"name": "arustydev",
111-
"url": "https://raw.githubusercontent.com/aRustyDev/agents/main/.claude-plugin/marketplace.json"
112-
}
113-
]
114-
}
115-
```
116-
117-
2. **Via ccpm** (Claude Code Plugin Manager):
40+
### Skill Management
11841

11942
```bash
120-
ccpm registry add arustydev https://raw.githubusercontent.com/aRustyDev/agents/main/.claude-plugin/marketplace.json
121-
ccpm search swiftui
122-
ccpm install arustydev/swiftui-dev
43+
just agents skill add owner/repo@skill # Install a skill
44+
just agents skill find "kubernetes" # Search registries
45+
just agents skill list # List installed skills
46+
just agents skill list --agent claude-code # Filter by agent
47+
just agents skill outdated # Check for updates
48+
just agents skill update # Update outdated skills
49+
just agents skill remove skill-name # Remove a skill
50+
just agents skill info skill-name # Detailed metadata
51+
just agents skill init my-skill # Scaffold new skill
12352
```
12453

125-
3. **Via local clone**:
54+
### MCP Server Management
12655

12756
```bash
128-
# Add to your .claude/settings.json
129-
{
130-
"pluginMarketplaces": [
131-
{
132-
"name": "arustydev-local",
133-
"path": "~/repos/ai/.claude-plugin/marketplace.json"
134-
}
135-
]
136-
}
57+
just agents mcp search "postgres" # Search Smithery registry
58+
just agents mcp add smithery://ns/server --client cursor # Add to client config
59+
just agents mcp list --client claude-desktop # List in client config
60+
just agents mcp remove server-name --client cursor # Remove from client
61+
just agents mcp info ns/server-name # Server details
62+
just agents mcp publish --name ns/server --url https://...# Publish to Smithery
13763
```
13864

139-
### Marketplace Schema
140-
141-
Each plugin entry in `marketplace.json` follows this structure:
142-
143-
```json
144-
{
145-
"name": "plugin-name",
146-
"source": "./context/plugins/plugin-name",
147-
"description": "What the plugin does",
148-
"version": "1.0.0",
149-
"keywords": ["keyword1", "keyword2"],
150-
"license": "MIT",
151-
"homepage": "https://docs.arusty.dev/ai/plugins/plugin-name",
152-
"repository": "https://github.com/aRustyDev/agents.git"
153-
}
154-
```
155-
156-
## Workflow
157-
158-
### 1. Develop in Project
159-
160-
Create/test configs in your project's `.claude/` directory.
161-
162-
### 2. Promote to Source
65+
### Cross-Type Component Search
16366

16467
```bash
165-
# Future: promote-component script
166-
cp -r .claude/skills/new-skill/ ~/repos/configs/ai/components/skills/
167-
cd ~/repos/configs/ai
168-
git add -A && git commit -m "feat: add new-skill"
169-
git push
68+
just agents component search "kubernetes" # Search all types
69+
just agents component list # List all installed
70+
just agents component list --type agent # Filter by type
17071
```
17172

172-
### 3. Deploy to Global
73+
### Other Commands
17374

17475
```bash
175-
# On each machine
176-
cd ~/repos/configs/dotfiles
177-
git submodule update --remote ai/
178-
just install-ai
76+
just agents plugin check <name> # Validate a plugin
77+
just agents skill validate <name> # Validate skill frontmatter
78+
just kg-search "query" # Semantic search (knowledge graph)
17979
```
18080

181-
## Roadmap
182-
183-
- [x] Phase 1: Directory structure and legacy migration
184-
- [ ] Phase 2: Basic promote/build/deploy workflow
185-
- [ ] Phase 3: JSON schemas and compilation
186-
- [ ] Phase 4: Profiles and dynamic MCP config generation
81+
## Component Model
18782

188-
See [Issue #1](https://github.com/aRustyDev/agents/issues/1) for full details.
83+
All entity types flow through a universal `ComponentProvider` interface:
18984

190-
## Legacy Content
85+
| Provider | ID | Entity Types | Backend |
86+
|----------|----|-------------|---------|
87+
| LocalProvider | `local` | skill | Filesystem (wraps skill-* modules) |
88+
| LocalAgentProvider | `local-agent` | agent | `context/agents/**/*.md` |
89+
| LocalPluginProvider | `local-plugin` | plugin | `context/plugins/**/.claude-plugin/` |
90+
| LocalRuleProvider | `local-rule` | rule | `context/rules/**/*.md` |
91+
| LocalCommandProvider | `local-command` | command | `context/commands/**/*.md` |
92+
| LocalOutputStyleProvider | `local-output-style` | output_style | `context/output-styles/**/*.md` |
93+
| SmitheryProvider | `smithery` | mcp_server | registry.smithery.ai API |
19194

192-
Previous content is preserved in `legacy/` during migration. This includes:
95+
The `ComponentManager` aggregates search across all providers, deduplicates results, and handles pagination.
19396

194-
### From arustydev/agents (archived)
97+
## AI Client Config Support
19598

196-
- `agents/` - Agent definitions
99+
MCP servers can be installed to 19 AI client config files:
197100

198-
### From arustydev/prompts (archived)
101+
| Client | Method | Format |
102+
|--------|--------|--------|
103+
| Claude Desktop | file | JSON |
104+
| Claude Code | command | `claude mcp add` |
105+
| Cursor | file | JSON |
106+
| Windsurf | file | JSON |
107+
| VS Code | command | `code --add-mcp` |
108+
| Cline, Roo Code, Continue, Zed, Goose, OpenCode, ... | file | JSON/YAML/JSONC |
199109

200-
- `prompts/commands/` - Slash commands (/audit, /plan, /report, etc.)
201-
- `prompts/processes/` - Workflow processes (CI/CD, code-review, testing)
202-
- `prompts/core/` - Core patterns (error handling, validation, git operations)
203-
- `prompts/patterns/` - Development patterns (BDD, TDD, CDD)
204-
- `prompts/templates/` - Issue, report, and documentation templates
205-
- `prompts/roles/` - Role definitions (developer levels, security engineer)
206-
- `prompts/guides/` - Tool usage guides
207-
- `prompts/knowledge/` - Knowledge bases
208-
- `prompts/hooks/` - Validation hooks and scripts
209-
- `prompts/automation/` - Automation scripts
210-
- `prompts/docs/` - Architecture and planning documentation
211-
212-
### Original legacy
110+
## Plugin Marketplace
213111

214-
- `commands/` - Slash commands
215-
- `rules/` - Instruction rules
216-
- `skills/` - Skill definitions
217-
- `plugins/` - Various plugins
218-
- `roles/` - Role definitions
219-
- `context/` - Context documents
220-
- And more...
112+
Curated plugins at `.claude-plugin/marketplace.json`:
221113

222-
Content will be migrated to the new structure over time. Valuable content can be promoted to `components/` using the `/promote-skill` command or similar workflows.
114+
| Plugin | Description |
115+
|--------|-------------|
116+
| `homebrew-dev` | Homebrew formula development |
117+
| `browser-extension-dev` | Cross-browser extension development |
118+
| `blog-workflow` | Technical blog post creation |
119+
| `job-hunting` | Job hunting toolkit |
120+
| `swiftui-dev` | SwiftUI development |
121+
| `design-to-code` | Design-to-code conversion |
223122

224-
## Merged Repositories
123+
## Dependencies
225124

226-
The following repositories have been archived and merged into this repo:
125+
| Layer | Tool | Config |
126+
|-------|------|--------|
127+
| System tools | Homebrew | `brewfile` |
128+
| TypeScript | Bun | `.scripts/package.json` |
129+
| Python (KG only) | uv | `pyproject.toml` |
130+
| Task runner | just | `justfile` |
131+
| Issue tracking | beads (bd) | `.beads/config.yaml` |
227132

228-
- **arustydev/agents** → `legacy/agents/`
229-
- **arustydev/prompts** → `legacy/prompts/`
133+
## Development
230134

231-
See `.ai/plans/merge-agents-prompts.md` for the full merge plan and history.
135+
```bash
136+
just init # One-time setup
137+
cd .scripts && bun test # Run all tests
138+
cd .scripts && bun test test/component/ # Component tests only
139+
just agents skill validate <name> # Validate a skill
140+
just agents plugin check <name> # Validate a plugin
141+
```
232142

233143
## License
234144

0 commit comments

Comments
 (0)