@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.
@@ -0,0 +1,3 @@
1
+ # Skills
2
+
3
+ List in ../../.opencode/skill
@@ -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.