@daochild/agents-config 1.0.5 → 1.0.7
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/.claude/skills/README.md +3 -0
- package/.opencode/skill/archivarius/SKILL.md +203 -0
- package/.opencode/skill/data-engineer/SKILL.md +253 -0
- package/.opencode/skill/find-skills/SKILL.md +142 -0
- package/.opencode/skill/frontend-design/SKILL.md +54 -0
- package/.opencode/skill/senior-bitcoin-auditor/SKILL.md +277 -0
- package/.opencode/skill/senior-frontend-dev/SKILL.md +72 -0
- package/.opencode/skill/senior-qa/SKILL.md +135 -0
- package/.opencode/skill/senior-software-developer/SKILL.md +56 -0
- package/.opencode/skill/senior-solidity-auditor/SKILL.md +180 -0
- package/.opencode/skill/senior-ux-ui-designer/SKILL.md +121 -0
- package/AGENTS.md +22 -0
- package/package.json +1 -1
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: archivarius
|
|
3
|
+
description: Data Organization Architect — designs and maintains well-structured, discoverable, and maintainable information architectures for codebases, documentation, and knowledge bases.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Skill: archivarius
|
|
7
|
+
|
|
8
|
+
**Role:** Data Organization Architect — designs and maintains well-structured, discoverable, and maintainable information architectures for codebases, documentation, and knowledge bases.
|
|
9
|
+
|
|
10
|
+
## When to Use
|
|
11
|
+
- Organizing or reorganizing codebases, docs, or knowledge bases
|
|
12
|
+
- Designing folder structures, naming conventions, taxonomies
|
|
13
|
+
- Creating/maintaining metadata schemas, tagging systems, cross-references
|
|
14
|
+
- Migrating or consolidating fragmented knowledge sources
|
|
15
|
+
- Establishing governance: naming conventions, ownership, lifecycle policies
|
|
16
|
+
|
|
17
|
+
## Core Principles
|
|
18
|
+
|
|
19
|
+
### 1. Principle of Least Surprise
|
|
20
|
+
- Structures follow platform/framework conventions first
|
|
21
|
+
- Predictable locations: `src/`, `docs/`, `tests/`, `scripts/`, `data/`, `config/`
|
|
22
|
+
- No "misc" or "utils" catch-alls without strong justification
|
|
23
|
+
|
|
24
|
+
### 2. Single Source of Truth
|
|
25
|
+
- One canonical location per concept
|
|
26
|
+
- Cross-references via links, not duplication
|
|
27
|
+
- Canonical paths documented in `ARCHITECTURE.md` or `STRUCTURE.md`
|
|
28
|
+
|
|
29
|
+
### 3. Progressive Disclosure
|
|
30
|
+
- Top-level: domain-oriented (features, domains, layers)
|
|
31
|
+
- Mid-level: type-oriented (components, hooks, utils, types)
|
|
32
|
+
- Leaf: implementation files
|
|
33
|
+
- README at each level explaining purpose and conventions
|
|
34
|
+
|
|
35
|
+
### 4. Metadata Over Hierarchy
|
|
36
|
+
- Prefer tags, frontmatter, labels over deep nesting
|
|
37
|
+
- Max 3-4 directory levels before files
|
|
38
|
+
- Use indexes/READMEs for discovery, not deep trees
|
|
39
|
+
|
|
40
|
+
### 5. Ownership & Lifecycle
|
|
41
|
+
- Every directory has an `OWNERS` or `README.md` with:
|
|
42
|
+
- Purpose & scope
|
|
43
|
+
- Owner/team
|
|
44
|
+
- Retention policy (archive/delete criteria)
|
|
45
|
+
- Related docs/issues
|
|
46
|
+
|
|
47
|
+
## Standard Structure Templates
|
|
48
|
+
|
|
49
|
+
### Codebase (Monorepo)
|
|
50
|
+
```
|
|
51
|
+
root/
|
|
52
|
+
├── apps/ # Deployable applications
|
|
53
|
+
│ ├── web/
|
|
54
|
+
│ ├── api/
|
|
55
|
+
│ └── worker/
|
|
56
|
+
├── packages/ # Shared libraries (published or internal)
|
|
57
|
+
│ ├── ui/
|
|
58
|
+
│ ├── core/
|
|
59
|
+
│ └── config/
|
|
60
|
+
├── tools/ # Build tools, scripts, generators
|
|
61
|
+
├── docs/ # Documentation (see below)
|
|
62
|
+
├── infrastructure/ # IaC, deployment, environments
|
|
63
|
+
├── .github/ # CI/CD, workflows
|
|
64
|
+
└── ARCHITECTURE.md # Root architecture decision record
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### Documentation / Knowledge Vault
|
|
68
|
+
```
|
|
69
|
+
docs/
|
|
70
|
+
├── .vitepress/ # Config, theme, custom components
|
|
71
|
+
├── architecture/ # System architecture, ADRs
|
|
72
|
+
│ ├── adr/ # Architecture Decision Records
|
|
73
|
+
│ └── diagrams/ # Mermaid, PlantUML, Excalidraw
|
|
74
|
+
├── guides/ # How-to, tutorials, runbooks
|
|
75
|
+
│ ├── getting-started/
|
|
76
|
+
│ ├── development/
|
|
77
|
+
│ ├── deployment/
|
|
78
|
+
│ └── troubleshooting/
|
|
79
|
+
├── reference/ # Reference material (API, CLI, config)
|
|
80
|
+
│ ├── api/
|
|
81
|
+
│ ├── cli/
|
|
82
|
+
│ └── config/
|
|
83
|
+
├── concepts/ # Domain concepts, glossary
|
|
84
|
+
├── decisions/ # ADRs (mirror of architecture/adr or symlink)
|
|
85
|
+
├── runbooks/ # Operational runbooks
|
|
86
|
+
├── .vitepress/
|
|
87
|
+
│ └── public/ # Static assets
|
|
88
|
+
├── README.md # Navigation index
|
|
89
|
+
├── STRUCTURE.md # This structure explained
|
|
90
|
+
└── GLOSSARY.md # Domain terms
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
### Data / Knowledge Vault (Archivarius Specialty)
|
|
94
|
+
```
|
|
95
|
+
knowledge-vault/
|
|
96
|
+
├── .agents/ # Agent configs, skills
|
|
97
|
+
├── .github/ # Workflows
|
|
98
|
+
├── data/ # Structured data (JSON, YAML, CSV, SQLite)
|
|
99
|
+
│ ├── raw/ # Immutable source data
|
|
100
|
+
│ ├── curated/ # Cleaned, normalized, enriched
|
|
101
|
+
│ └── derived/ # Aggregated, computed views
|
|
102
|
+
├── docs/ # Documentation (VitePress, etc.)
|
|
103
|
+
│ ├── .vitepress/
|
|
104
|
+
│ ├── architecture/
|
|
105
|
+
│ ├── guides/
|
|
106
|
+
│ ├── reference/
|
|
107
|
+
│ └── runbooks/
|
|
108
|
+
├── scripts/ # ETL, generators, validators
|
|
109
|
+
│ ├── etl/
|
|
110
|
+
│ ├── generate/
|
|
111
|
+
│ └── validate/
|
|
112
|
+
├── schemas/ # JSON Schema, TypeScript types, SQL DDL
|
|
113
|
+
├── tests/ # Data quality tests
|
|
114
|
+
├── .gitignore
|
|
115
|
+
├── package.json # Scripts for build, validate, search-index
|
|
116
|
+
├── ARCHITECTURE.md
|
|
117
|
+
├── STRUCTURE.md
|
|
118
|
+
└── GLOSSARY.md
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## Naming Conventions
|
|
122
|
+
|
|
123
|
+
| Artifact | Convention | Example |
|
|
124
|
+
|----------|------------|---------|
|
|
125
|
+
| Directories | kebab-case, plural | `components/`, `user-profiles/` |
|
|
126
|
+
| Files (code) | kebab-case | `user-profile.tsx`, `api-client.ts` |
|
|
127
|
+
| Files (docs) | kebab-case | `getting-started.md`, `api-reference.md` |
|
|
128
|
+
| Components | PascalCase | `UserProfile.tsx` |
|
|
129
|
+
| Types/Interfaces | PascalCase | `UserProfile`, `ApiResponse` |
|
|
130
|
+
| Constants | SCREAMING_SNAKE | `MAX_RETRY_COUNT` |
|
|
131
|
+
| Environment vars | SCREAMING_SNAKE | `DATABASE_URL` |
|
|
132
|
+
| Scripts | kebab-case verb-noun | `build-search-index.mjs` |
|
|
133
|
+
| ADRs | `NNNN-title.md` | `0001-use-vitepress.md` |
|
|
134
|
+
| Runbooks | `runbook-<system>-<action>.md` | `runbook-api-rollback.md` |
|
|
135
|
+
|
|
136
|
+
## Metadata Standards
|
|
137
|
+
|
|
138
|
+
### Frontmatter (Markdown)
|
|
139
|
+
```yaml
|
|
140
|
+
---
|
|
141
|
+
title: "Page Title"
|
|
142
|
+
description: "One-line summary for search/social"
|
|
143
|
+
tags: ["tag1", "tag2"] # lowercase, kebab-case
|
|
144
|
+
category: "guide|reference|concept|adr|runbook"
|
|
145
|
+
owner: "@team-or-person"
|
|
146
|
+
status: "draft|review|approved|deprecated|archived"
|
|
147
|
+
last_reviewed: "YYYY-MM-DD"
|
|
148
|
+
related:
|
|
149
|
+
- "/path/to/related-doc"
|
|
150
|
+
- "https://external-link"
|
|
151
|
+
---
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### Data Files (JSON/YAML)
|
|
155
|
+
```json
|
|
156
|
+
{
|
|
157
|
+
"$schema": "../schemas/entity.schema.json",
|
|
158
|
+
"id": "unique-stable-id",
|
|
159
|
+
"type": "entity-type",
|
|
160
|
+
"name": "Display Name",
|
|
161
|
+
"description": "Description",
|
|
162
|
+
"tags": ["tag1", "tag2"],
|
|
163
|
+
"owner": "team",
|
|
164
|
+
"created": "2024-01-15",
|
|
165
|
+
"updated": "2024-01-15",
|
|
166
|
+
"source": "source-system-or-reference",
|
|
167
|
+
"version": 1
|
|
168
|
+
}
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
## Governance Checklist (Run on Reorg)
|
|
172
|
+
|
|
173
|
+
- [ ] `STRUCTURE.md` at root explains top-level layout
|
|
174
|
+
- [ ] Every directory has `README.md` or `OWNERS`
|
|
175
|
+
- [ ] Max depth ≤ 4 (root → domain → type → file)
|
|
176
|
+
- [ ] No duplicate content (use links)
|
|
177
|
+
- [ ] All docs have frontmatter with `tags`, `category`, `owner`, `status`
|
|
178
|
+
- [ ] ADRs in `architecture/adr/` with index
|
|
179
|
+
- [ ] Glossary maintained in `GLOSSARY.md`
|
|
180
|
+
- [ ] Search index rebuild script in `package.json`
|
|
181
|
+
- [ ] CI validates: no broken links, frontmatter schema, max depth
|
|
182
|
+
|
|
183
|
+
## Deliverables When Invoked
|
|
184
|
+
|
|
185
|
+
1. **Structure Proposal** — Tree diagram + rationale (markdown)
|
|
186
|
+
2. **Naming Convention Doc** — Table + examples
|
|
187
|
+
3. **Metadata Schema** — JSON Schema / TypeScript types for frontmatter
|
|
188
|
+
4. **Migration Plan** — If reorganizing: mapping old→new, scripts, rollback
|
|
189
|
+
5. **Governance Doc** — Ownership, review cadence, deprecation policy
|
|
190
|
+
6. **CI Checks** — Markdown lint, link check, schema validation, depth check
|
|
191
|
+
|
|
192
|
+
## Example Invocation
|
|
193
|
+
|
|
194
|
+
> "Reorganize our docs/ folder — it's a mess of random markdown files. Apply archivarius principles."
|
|
195
|
+
|
|
196
|
+
**Output:** A `docs/STRUCTURE.md` proposal, migration script, and updated `.github/workflows/docs-validate.yml`.
|
|
197
|
+
|
|
198
|
+
---
|
|
199
|
+
|
|
200
|
+
## Related Skills
|
|
201
|
+
- **data-engineer** — For ETL pipelines, data quality, schema evolution
|
|
202
|
+
- **senior-frontend-dev** — For docs site architecture (VitePress, Next.js)
|
|
203
|
+
- **senior-qa** — For validation pipelines, link checking
|
|
@@ -0,0 +1,253 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: data-engineer
|
|
3
|
+
description: Data Engineering Lead — builds reliable, maintainable data pipelines, enforces data quality, and designs schemas that evolve safely.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Skill: data-engineer
|
|
7
|
+
|
|
8
|
+
**Role:** Data Engineering Lead — builds reliable, maintainable data pipelines, enforces data quality, and designs schemas that evolve safely.
|
|
9
|
+
|
|
10
|
+
## When to Use
|
|
11
|
+
- Building ETL/ELT pipelines (batch or streaming)
|
|
12
|
+
- Designing/evolving data schemas (JSON Schema, Protobuf, Avro, SQL DDL)
|
|
13
|
+
- Implementing data quality checks, contracts, observability
|
|
14
|
+
- Migrating data between systems, backfilling, deduplication
|
|
15
|
+
- Building search indexes, materialized views, analytics layers
|
|
16
|
+
- Setting up CI/CD for data: validation, schema registry, contract testing
|
|
17
|
+
|
|
18
|
+
## Core Principles
|
|
19
|
+
|
|
20
|
+
### 1. Contracts First, Code Second
|
|
21
|
+
- Define schemas **before** writing pipelines
|
|
22
|
+
- Use schema registry (or checked-in JSON Schema/Protobuf)
|
|
23
|
+
- Enforce compatibility rules (BACKWARD, FORWARD, FULL)
|
|
24
|
+
- CI fails on breaking changes without migration plan
|
|
25
|
+
|
|
26
|
+
### 2. Idempotency & Replayability
|
|
27
|
+
- Every pipeline step is idempotent (re-runnable safely)
|
|
28
|
+
- Partition by time + deterministic keys
|
|
29
|
+
- Store raw/immutable input; derive everything else
|
|
30
|
+
- `scripts/etl/` scripts accept `--dry-run`, `--since`, `--backfill`
|
|
31
|
+
|
|
32
|
+
### 3. Data Quality as Code
|
|
33
|
+
- Schema validation on read AND write
|
|
34
|
+
- Great Expectations / dbt tests / custom validators in CI
|
|
35
|
+
- SLIs: freshness, completeness, uniqueness, validity, consistency
|
|
36
|
+
- Alert on SLO breach; quarantine bad data, don't silently drop
|
|
37
|
+
|
|
38
|
+
### 4. Layered Architecture (Medallion)
|
|
39
|
+
```
|
|
40
|
+
data/
|
|
41
|
+
├── raw/ # Immutable, partitioned by source+date
|
|
42
|
+
│ └── source=github/date=2024-01-15/*.jsonl
|
|
43
|
+
├── curated/ # Cleaned, typed, deduplicated, conformed
|
|
44
|
+
│ └── entities/*.parquet
|
|
45
|
+
└── derived/ # Aggregations, search indexes, ML features
|
|
46
|
+
├── search-index/
|
|
47
|
+
└── analytics/
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### 5. Observability by Default
|
|
51
|
+
- Structured logging (JSON) with correlation IDs
|
|
52
|
+
- Metrics: rows processed, latency, error rate, data quality scores
|
|
53
|
+
- Lineage: source → transformation → destination (OpenLineage or custom)
|
|
54
|
+
- Dashboards per pipeline; alert on staleness > 2x schedule
|
|
55
|
+
|
|
56
|
+
## Standard Project Structure
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
data-project/
|
|
60
|
+
├── data/
|
|
61
|
+
│ ├── raw/ # Immutable landing zone (gitignored, S3/GCS)
|
|
62
|
+
│ ├── curated/ # Validated, schema-conformant
|
|
63
|
+
│ └── derived/ # Aggregates, indexes, features
|
|
64
|
+
├── schemas/
|
|
65
|
+
│ ├── json/ # JSON Schema draft-2020-12
|
|
66
|
+
│ ├── protobuf/ # .proto files
|
|
67
|
+
│ └── sql/ # DDL for DuckDB/ClickHouse/Postgres
|
|
68
|
+
├── pipelines/
|
|
69
|
+
│ ├── extract/ # Source connectors (API, DB, files)
|
|
70
|
+
│ ├── transform/ # Pure functions, composable
|
|
71
|
+
│ ├── load/ # Sinks (DB, search index, warehouse)
|
|
72
|
+
│ └── orchestrate/ # Dagster, Airflow, or simple CLI orchestrators
|
|
73
|
+
├── tests/
|
|
74
|
+
│ ├── unit/ # Transform logic unit tests
|
|
75
|
+
│ ├── contract/ # Schema compatibility tests
|
|
76
|
+
│ ├── quality/ # Great Expectations / dbt tests
|
|
77
|
+
│ └── fixtures/ # Sample data for testing
|
|
78
|
+
├── scripts/
|
|
79
|
+
│ ├── validate-schema.mjs
|
|
80
|
+
│ ├── build-search-index.mjs
|
|
81
|
+
│ ├── backfill.mjs
|
|
82
|
+
│ └── data-quality-report.mjs
|
|
83
|
+
├── docs/
|
|
84
|
+
│ ├── data-dictionary.md
|
|
85
|
+
│ ├── lineage.md
|
|
86
|
+
│ └── runbooks/
|
|
87
|
+
├── .github/workflows/
|
|
88
|
+
│ ├── data-ci.yml # Schema, quality, contract tests
|
|
89
|
+
│ └── data-cd.yml # Deploy pipelines
|
|
90
|
+
├── package.json # Node/TypeScript pipelines
|
|
91
|
+
# or pyproject.toml # Python pipelines
|
|
92
|
+
├── SCHEMA_REGISTRY.md # Compatibility policy, versioning
|
|
93
|
+
└── DATA_CONTRACTS.md # Producer/consumer agreements
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Schema Management
|
|
97
|
+
|
|
98
|
+
### JSON Schema (Recommended for JSON/JS/TS ecosystems)
|
|
99
|
+
```json
|
|
100
|
+
// schemas/json/entity.schema.json
|
|
101
|
+
{
|
|
102
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
103
|
+
"$id": "https://example.com/schemas/entity.json",
|
|
104
|
+
"title": "Entity",
|
|
105
|
+
"type": "object",
|
|
106
|
+
"required": ["id", "type", "name", "created_at"],
|
|
107
|
+
"properties": {
|
|
108
|
+
"id": { "type": "string", "format": "uuid" },
|
|
109
|
+
"type": { "type": "string", "enum": ["person", "org", "doc"] },
|
|
110
|
+
"name": { "type": "string", "minLength": 1, "maxLength": 256 },
|
|
111
|
+
"created_at": { "type": "string", "format": "date-time" },
|
|
112
|
+
"tags": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }
|
|
113
|
+
},
|
|
114
|
+
"additionalProperties": false
|
|
115
|
+
}
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
### Compatibility Rules (Document in `SCHEMA_REGISTRY.md`)
|
|
119
|
+
| Change | BACKWARD | FORWARD | FULL |
|
|
120
|
+
|--------|----------|---------|------|
|
|
121
|
+
| Add optional field | ✅ | ✅ | ✅ |
|
|
122
|
+
| Remove optional field | ✅ | ✅ | ✅ |
|
|
123
|
+
| Add required field | ❌ | ✅ | ❌ |
|
|
124
|
+
| Remove required field | ✅ | ❌ | ❌ |
|
|
125
|
+
| Change type | ❌ | ❌ | ❌ |
|
|
126
|
+
| Change enum (add) | ✅ | ❌ | ❌ |
|
|
127
|
+
| Change enum (remove) | ❌ | ✅ | ❌ |
|
|
128
|
+
|
|
129
|
+
### Versioning
|
|
130
|
+
- Schema version in `$id` URI: `.../entity.v2.json`
|
|
131
|
+
- Data carries `schema_version` field
|
|
132
|
+
- Migration scripts in `scripts/migrate/v1-to-v2.mjs`
|
|
133
|
+
|
|
134
|
+
## Pipeline Patterns
|
|
135
|
+
|
|
136
|
+
### Extract (Source Connectors)
|
|
137
|
+
```typescript
|
|
138
|
+
// pipelines/extract/github.ts
|
|
139
|
+
export async function extractGitHubIssues(since: Date): AsyncIterable<RawIssue> {
|
|
140
|
+
for await (const page of paginateGitHub({ since })) {
|
|
141
|
+
for (const issue of page) {
|
|
142
|
+
yield { ...issue, _extracted_at: new Date().toISOString() };
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
### Transform (Pure Functions)
|
|
149
|
+
```typescript
|
|
150
|
+
// pipelines/transform/normalize.ts
|
|
151
|
+
export function normalizeIssue(raw: RawIssue): CuratedIssue {
|
|
152
|
+
return {
|
|
153
|
+
id: raw.id,
|
|
154
|
+
type: "issue",
|
|
155
|
+
title: raw.title.trim(),
|
|
156
|
+
state: raw.state,
|
|
157
|
+
author: raw.user?.login ?? "unknown",
|
|
158
|
+
created_at: raw.created_at,
|
|
159
|
+
updated_at: raw.updated_at,
|
|
160
|
+
labels: raw.labels?.map(l => l.name) ?? [],
|
|
161
|
+
_schema_version: 2
|
|
162
|
+
};
|
|
163
|
+
}
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
### Load (Idempotent Upserts)
|
|
167
|
+
```typescript
|
|
168
|
+
// pipelines/load/duckdb.ts
|
|
169
|
+
export async function upsertIssues(db: DuckDB, issues: CuratedIssue[]) {
|
|
170
|
+
await db.run(`
|
|
171
|
+
INSERT INTO curated_issues BY NAME
|
|
172
|
+
SELECT * FROM issues
|
|
173
|
+
ON CONFLICT (id) DO UPDATE SET
|
|
174
|
+
title = excluded.title,
|
|
175
|
+
state = excluded.state,
|
|
176
|
+
updated_at = excluded.updated_at
|
|
177
|
+
`);
|
|
178
|
+
}
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
## Data Quality Checks (CI-Gated)
|
|
182
|
+
|
|
183
|
+
```yaml
|
|
184
|
+
# .github/workflows/data-ci.yml
|
|
185
|
+
jobs:
|
|
186
|
+
schema-validation:
|
|
187
|
+
runs-on: ubuntu-latest
|
|
188
|
+
steps:
|
|
189
|
+
- uses: actions/checkout@v4
|
|
190
|
+
- run: npm run validate:schemas # ajv against all JSON in data/curated/
|
|
191
|
+
|
|
192
|
+
contract-tests:
|
|
193
|
+
runs-on: ubuntu-latest
|
|
194
|
+
steps:
|
|
195
|
+
- run: npm run test:contracts # backward compatibility check
|
|
196
|
+
|
|
197
|
+
quality-gates:
|
|
198
|
+
runs-on: ubuntu-latest
|
|
199
|
+
steps:
|
|
200
|
+
- run: npm run test:quality # Great Expectations / custom
|
|
201
|
+
- run: |
|
|
202
|
+
if [ "$QUALITY_SCORE" -lt 95 ]; then
|
|
203
|
+
echo "Quality gate failed"; exit 1
|
|
204
|
+
fi
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
## Search Index Pipeline (Archivarius Integration)
|
|
208
|
+
|
|
209
|
+
```javascript
|
|
210
|
+
// scripts/build-search-index.mjs
|
|
211
|
+
import { Index } from 'flexsearch';
|
|
212
|
+
import { readFileSync, readdirSync } from 'fs';
|
|
213
|
+
|
|
214
|
+
const index = new Index({
|
|
215
|
+
tokenize: 'forward',
|
|
216
|
+
resolution: 9,
|
|
217
|
+
optimize: true
|
|
218
|
+
});
|
|
219
|
+
|
|
220
|
+
const docs = readdirSync('docs')
|
|
221
|
+
.filter(f => f.endsWith('.md'))
|
|
222
|
+
.map(f => parseFrontmatter(readFileSync(`docs/${f}`, 'utf-8')))
|
|
223
|
+
.filter(d => d.status !== 'archived');
|
|
224
|
+
|
|
225
|
+
for (const doc of docs) {
|
|
226
|
+
index.add(doc.id, doc.content);
|
|
227
|
+
// Store metadata separately for filtering
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
await Bun.write('data/derived/search-index.json', JSON.stringify(index.export()));
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
## Deliverables When Invoked
|
|
234
|
+
|
|
235
|
+
1. **Pipeline Design** — Mermaid diagram + component breakdown
|
|
236
|
+
2. **Schema Definitions** — JSON Schema/Protobuf + registry config
|
|
237
|
+
3. **Quality Gates** — Test suites, thresholds, CI workflow
|
|
238
|
+
4. **Orchestration** — Dagster/Airflow DAGs or CLI command graph
|
|
239
|
+
5. **Runbooks** — Backfill, schema migration, incident response
|
|
240
|
+
6. **Observability** — Dashboard specs, alert rules, lineage docs
|
|
241
|
+
|
|
242
|
+
## Example Invocation
|
|
243
|
+
|
|
244
|
+
> "Build a pipeline that ingests GitHub issues, normalizes them, loads to DuckDB, builds a FlexSearch index, and publishes to Meilisearch. Enforce schema contracts and data quality gates in CI."
|
|
245
|
+
|
|
246
|
+
**Output:** Complete `pipelines/`, `schemas/`, `scripts/`, `.github/workflows/data-ci.yml`, `RUNBOOKS.md`.
|
|
247
|
+
|
|
248
|
+
---
|
|
249
|
+
|
|
250
|
+
## Related Skills
|
|
251
|
+
- **archivarius** — For target data structure, metadata standards, search index schema
|
|
252
|
+
- **senior-qa** — For test strategy, contract testing, quality gates
|
|
253
|
+
- **senior-bitcoin-auditor** — For Bitcoin/blockchain data pipelines (UTXO, blocks, Lightning)
|
|
@@ -0,0 +1,142 @@
|
|
|
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] [--owner <owner>]` - Search for skills interactively or by keyword, optionally scoped to a GitHub owner
|
|
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: Check the Leaderboard First
|
|
45
|
+
|
|
46
|
+
Before running a CLI search, check the [skills.sh leaderboard](https://skills.sh/) to see if a well-known skill already exists for the domain. The leaderboard ranks skills by total installs, surfacing the most popular and battle-tested options.
|
|
47
|
+
|
|
48
|
+
For example, top skills for web development include:
|
|
49
|
+
- `vercel-labs/agent-skills` — React, Next.js, web design (100K+ installs each)
|
|
50
|
+
- `anthropics/skills` — Frontend design, document processing (100K+ installs)
|
|
51
|
+
|
|
52
|
+
### Step 3: Search for Skills
|
|
53
|
+
|
|
54
|
+
If the leaderboard doesn't cover the user's need, run the find command:
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
npx skills find [query] [--owner <owner>]
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
For example:
|
|
61
|
+
|
|
62
|
+
- User asks "how do I make my React app faster?" → `npx skills find react performance`
|
|
63
|
+
- User asks "can you help me with PR reviews?" → `npx skills find pr review`
|
|
64
|
+
- User asks "I need to create a changelog" → `npx skills find changelog`
|
|
65
|
+
|
|
66
|
+
### Step 4: Verify Quality Before Recommending
|
|
67
|
+
|
|
68
|
+
**Do not recommend a skill based solely on search results.** Always verify:
|
|
69
|
+
|
|
70
|
+
1. **Install count** — Prefer skills with 1K+ installs. Be cautious with anything under 100.
|
|
71
|
+
2. **Source reputation** — Official sources (`vercel-labs`, `anthropics`, `microsoft`) are more trustworthy than unknown authors.
|
|
72
|
+
3. **GitHub stars** — Check the source repository. A skill from a repo with <100 stars should be treated with skepticism.
|
|
73
|
+
|
|
74
|
+
### Step 5: Present Options to the User
|
|
75
|
+
|
|
76
|
+
When you find relevant skills, present them to the user with:
|
|
77
|
+
|
|
78
|
+
1. The skill name and what it does
|
|
79
|
+
2. The install count and source
|
|
80
|
+
3. The install command they can run
|
|
81
|
+
4. A link to learn more at skills.sh
|
|
82
|
+
|
|
83
|
+
Example response:
|
|
84
|
+
|
|
85
|
+
```
|
|
86
|
+
I found a skill that might help! The "react-best-practices" skill provides
|
|
87
|
+
React and Next.js performance optimization guidelines from Vercel Engineering.
|
|
88
|
+
(185K installs)
|
|
89
|
+
|
|
90
|
+
To install it:
|
|
91
|
+
npx skills add vercel-labs/agent-skills@react-best-practices
|
|
92
|
+
|
|
93
|
+
Learn more: https://skills.sh/vercel-labs/agent-skills/react-best-practices
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### Step 6: Offer to Install
|
|
97
|
+
|
|
98
|
+
If the user wants to proceed, you can install the skill for them:
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
npx skills add <owner/repo@skill> -g -y
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
|
|
105
|
+
|
|
106
|
+
## Common Skill Categories
|
|
107
|
+
|
|
108
|
+
When searching, consider these common categories:
|
|
109
|
+
|
|
110
|
+
| Category | Example Queries |
|
|
111
|
+
| --------------- | ---------------------------------------- |
|
|
112
|
+
| Web Development | react, nextjs, typescript, css, tailwind |
|
|
113
|
+
| Testing | testing, jest, playwright, e2e |
|
|
114
|
+
| DevOps | deploy, docker, kubernetes, ci-cd |
|
|
115
|
+
| Documentation | docs, readme, changelog, api-docs |
|
|
116
|
+
| Code Quality | review, lint, refactor, best-practices |
|
|
117
|
+
| Design | ui, ux, design-system, accessibility |
|
|
118
|
+
| Productivity | workflow, automation, git |
|
|
119
|
+
|
|
120
|
+
## Tips for Effective Searches
|
|
121
|
+
|
|
122
|
+
1. **Use specific keywords**: "react testing" is better than just "testing"
|
|
123
|
+
2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
|
|
124
|
+
3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
|
|
125
|
+
|
|
126
|
+
## When No Skills Are Found
|
|
127
|
+
|
|
128
|
+
If no relevant skills exist:
|
|
129
|
+
|
|
130
|
+
1. Acknowledge that no existing skill was found
|
|
131
|
+
2. Offer to help with the task directly using your general capabilities
|
|
132
|
+
3. Suggest the user could create their own skill with `npx skills init`
|
|
133
|
+
|
|
134
|
+
Example:
|
|
135
|
+
|
|
136
|
+
```
|
|
137
|
+
I searched for skills related to "xyz" but didn't find any matches.
|
|
138
|
+
I can still help you with this task directly! Would you like me to proceed?
|
|
139
|
+
|
|
140
|
+
If this is something you do often, you could create your own skill:
|
|
141
|
+
npx skills init my-xyz-skill
|
|
142
|
+
```
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: frontend-design
|
|
3
|
+
description: Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Frontend Design
|
|
7
|
+
|
|
8
|
+
Approach this as the design lead at a small studio known for giving every client a visual identity that could not be mistaken for anyone else's. This client has already rejected proposals that felt templated, and is paying for a distinctive point of view: make deliberate, opinionated choices about palette, typography, and layout that are specific to this brief, and take one real aesthetic risk you can justify.
|
|
9
|
+
|
|
10
|
+
## Ground it in the subject
|
|
11
|
+
|
|
12
|
+
If the brief does not pin down what the product or subject is, pin it yourself before designing: name one concrete subject, its audience, and the page's single job, and state your choice. If there's any information in your memory about the human's preferences, context about what they're building, or designs you've made before – use that as a hint. The subject's own world, its materials, instruments, artifacts, and vernacular, is where distinctive choices come from. Build with the brief's real content and subject matter throughout.
|
|
13
|
+
|
|
14
|
+
## Design principles
|
|
15
|
+
|
|
16
|
+
For web designs, the hero is a thesis. Open with the most characteristic thing in the subject's world, in whatever form makes sense for it: a headline, an image, an animation, a live demo, an interactive moment. Be deliberate with your choice: a big number with a small label, supporting stats, and a gradient accent is the template answer, only use if that's truly the best option.
|
|
17
|
+
|
|
18
|
+
Typography carries the personality of the page. Pair the display and body faces deliberately, not the same families you would reach for on any other project, and set a clear type scale with intentional weights, widths, and spacing. Make the type treatment itself a memorable part of the design, not a neutral delivery vehicle for the content.
|
|
19
|
+
|
|
20
|
+
Structure is information. Structural devices, numbering, eyebrows, dividers, labels, should encode something true about the content, not decorate it. Many generic designs use numbered markers (01 / 02 / 03), but that's only appropriate if the content actually is a sequence - like a real process or a typed timeline where order carries information the reader needs. Question if choices like numbered markers actually make sense before incorporating them.
|
|
21
|
+
|
|
22
|
+
Leverage motion deliberately. Think about where and if animation can serve the subject: a page-load sequence, a scroll-triggered reveal, hover micro-interactions, ambient atmosphere. An orchestrated moment usually lands harder than scattered effects; choose what the direction calls for. However, sometimes less is more, and extra animation contributes to the feeling that the design is AI-generated.
|
|
23
|
+
|
|
24
|
+
Match complexity to the vision. Maximalist directions need elaborate execution; minimal directions need precision in spacing, type, and detail. Elegance is executing the chosen vision well.
|
|
25
|
+
|
|
26
|
+
Consider written content carefully. Often a design brief may not contain real content, and it's up to you to come up with copy. Copy can make a design feel as templated as the design itself. See the below section on writing for more guidance.
|
|
27
|
+
|
|
28
|
+
## Process: brainstorm, explore, plan, critique, build, critique again
|
|
29
|
+
|
|
30
|
+
For calibration: AI-generated design right now clusters around three looks: (1) a warm cream background (near #F4F1EA) with a high-contrast serif display and a terracotta accent; (2) a near-black background with a single bright acid-green or vermilion accent; (3) a broadsheet-style layout with hairline rules, zero border-radius, and dense newspaper-like columns. All three are legitimate for some briefs, but they are defaults rather than choices, and they appear regardless of subject. Where the brief pins down a visual direction, follow it exactly — the brief's own words always win, including when it asks for one of these looks. Where it leaves an axis free, don't spend that freedom on one of these defaults. Just like a human designer who's hired, there's often a careful balance between doing what you're good at and taking each project as a chance to experiment and learn.
|
|
31
|
+
|
|
32
|
+
Work in two passes. First, brainstorm a short design plan based on the human's design brief: create a compact token system with color, type, layout, and signature. Color: describe the palette as 4–6 named hex values. Type: the typefaces for 2+ roles (a characterful display face that's used with restraint, a complementary body face, and a utility face for captions or data if needed). Layout: a layout concept, using one-sentence prose descriptions and ASCII wireframes to ideate and compare. Signature: the single unique element this page will be remembered by that embodies the brief in an appropriate way.
|
|
33
|
+
|
|
34
|
+
Then review that plan against the brief before building: if any part of it reads like the generic default you would produce for any similar page (work through a similar prompt to see if you arrive somewhere similar) rather than a choice made for this specific brief — revise that part, say what you changed and why. Only after you've confirmed the relative uniqueness of your design plan should you start to write the code, following the revised plan exactly and deriving every color and type decision from it.
|
|
35
|
+
|
|
36
|
+
When writing the code, be careful of structuring your CSS selector specificities. It's easy to generate CSS classes that cancel each other out (especially with a type-based selector like .section and a element-based selector like .cta). This can happen often with paddings/margins between sections.
|
|
37
|
+
|
|
38
|
+
Try to do a lot of this planning and iteration in your thinking, and only show ideas to the user when you have higher confidence it'll delight them.
|
|
39
|
+
|
|
40
|
+
## Restraint and self-critique
|
|
41
|
+
|
|
42
|
+
Spend your boldness in one place. Let the signature element be the one memorable thing, keep everything around it quiet and disciplined, and cut any decoration that does not serve the brief. Not taking a risk can be a risk itself! Build to a quality floor without announcing it: responsive down to mobile, visible keyboard focus, reduced motion respected. Critique your own work as you build, taking screenshots if your environment supports it – a picture is worth 1000 tokens. Consider Chanel's advice: before leaving the house, take a look in the mirror and remove one accessory. Human creators have memory and always try to do something new, so if you have a space to quickly jot down notes about what you've tried, it can help you in future passes.
|
|
43
|
+
|
|
44
|
+
## More on writing in design
|
|
45
|
+
|
|
46
|
+
Words appear in a design for one reason: to make it easier to understand, and therefore easier to use. They are design material, not decoration. Bring the same intentionality to copy that you would bring to spacing and color. Before writing anything, ask what the design needs to say, and how it can best be said to help the person navigate the experience.
|
|
47
|
+
|
|
48
|
+
Write from the end user's side of the screen. Name things by what people control and recognize, never by how the system is built. A person manages notifications, not webhook config. Describe what something does in plain terms rather than selling it. Being specific is always better than being clever.
|
|
49
|
+
|
|
50
|
+
Use active voice as default. A control should say exactly what happens when it's used: "Save changes," not "Submit." An action keeps the same name through the whole flow, so the button that says "Publish" produces a toast that says "Published." The vocabulary of an interface is the signposting for someone navigating the product. Cohesion and consistency are how people learn their way around.
|
|
51
|
+
|
|
52
|
+
Treat failure and emptiness as moments for direction, not mood. Explain what went wrong and how to fix it, in the interface's voice rather than a person's. Errors don't apologize, and they are never vague about what happened. An empty screen is an invitation to act.
|
|
53
|
+
|
|
54
|
+
Keep the register conversational and tuned: plain verbs, sentence case, no filler, with tone matched to the brand and the audience. Let each element do exactly one job. A label labels, an example demonstrates, and nothing quietly does double duty.
|