diff --git a/skills/agent-md-refactor/SKILL.md b/skills/agent-md-refactor/SKILL.md index d4ee2b5..aa1b087 100644 --- a/skills/agent-md-refactor/SKILL.md +++ b/skills/agent-md-refactor/SKILL.md @@ -1,6 +1,6 @@ --- name: agent-md-refactor -description: Refactor bloated AGENTS.md, CLAUDE.md, or similar agent instruction files to follow progressive disclosure principles. Splits monolithic files into organized, linked documentation. +description: Refactor bloated AGENTS.md, CLAUDE.md, COPILOT.md, or similar agent instruction files into organized, linked documentation following progressive disclosure principles. Use when files are too long, hard to maintain, or the user wants to split, reorganize, break up, or simplify their agent configuration files. license: MIT --- @@ -10,18 +10,6 @@ Refactor bloated agent instruction files (AGENTS.md, CLAUDE.md, COPILOT.md, etc. --- -## Triggers - -Use this skill when: -- "refactor my AGENTS.md" / "refactor my CLAUDE.md" -- "split my agent instructions" -- "organize my CLAUDE.md file" -- "my AGENTS.md is too long" -- "progressive disclosure for my instructions" -- "clean up my agent config" - ---- - ## Quick Reference | Phase | Action | Output | @@ -101,9 +89,10 @@ Organize remaining instructions into logical categories. **Grouping rules:** 1. Each file should be self-contained for its topic -2. Aim for 3-8 files (not too granular, not too broad) +2. Aim for 3-8 files (not too granular, not too broad) — too many categories cause fragmentation 3. Name files clearly: `{topic}.md` -4. Include only actionable instructions +4. Include only actionable instructions — vague guidance wastes tokens +5. Use a flat structure with links — avoid deep nesting --- @@ -217,18 +206,6 @@ Identify instructions that should be removed entirely. --- -## Anti-Patterns - -| Avoid | Why | Instead | -|-------|-----|---------| -| Keeping everything in root | Bloated, hard to maintain | Split into linked files | -| Too many categories | Fragmentation | Consolidate related topics | -| Vague instructions | Wastes tokens, no value | Be specific or delete | -| Duplicating defaults | Agent already knows | Only override when needed | -| Deep nesting | Hard to navigate | Flat structure with links | - ---- - ## Examples ### Before (Bloated Root) diff --git a/skills/backend-to-frontend-handoff-docs/SKILL.md b/skills/backend-to-frontend-handoff-docs/SKILL.md index faac6de..610fee1 100644 --- a/skills/backend-to-frontend-handoff-docs/SKILL.md +++ b/skills/backend-to-frontend-handoff-docs/SKILL.md @@ -1,6 +1,6 @@ --- name: backend-to-frontend-handoff-docs -description: Create API handoff documentation for frontend developers. Use when backend work is complete and needs to be documented for frontend integration, or user says 'create handoff', 'document API', 'frontend handoff', or 'API documentation'. +description: Generate API handoff documentation including endpoint specifications, request/response schemas, authentication details, validation rules, and example payloads for frontend developers. Use when backend work is complete and needs to be documented for frontend integration, or user says 'create handoff', 'document API', 'frontend handoff', or 'API documentation'. --- # API Handoff Mode @@ -9,8 +9,6 @@ description: Create API handoff documentation for frontend developers. Use when You are a backend developer completing API work. Your task is to produce a structured handoff document that gives frontend developers (or their AI) full business and technical context to build integration/UI without needing to ask backend questions. -> **When to use**: After completing backend API work—endpoints, DTOs, validation, business logic—run this mode to generate handoff documentation. - > **Simple API shortcut**: If the API is straightforward (CRUD, no complex business logic, obvious validation), skip the full template—just provide the endpoint, method, and example request/response JSON. Frontend can infer the rest. ## Goal @@ -109,7 +107,6 @@ interface ExampleDto { --- ## Rules -- **NO CHAT OUTPUT**—produce only the handoff markdown block, nothing else. - Be precise: types, constraints, examples—not vague prose. - Include real example payloads where helpful. - Surface non-obvious behaviors—don't assume frontend will "just know." @@ -119,4 +116,4 @@ interface ExampleDto { - If something is incomplete or TBD, say so explicitly. ## After Generating -Write the final markdown into the handoff file only—do not echo it in chat. (If the platform requires confirmation, reference the file path instead of pasting contents.) +Write the final markdown into the handoff file only—reference the file path instead of pasting contents in chat. diff --git a/skills/c4-architecture/SKILL.md b/skills/c4-architecture/SKILL.md index ed972bc..b58d3c1 100644 --- a/skills/c4-architecture/SKILL.md +++ b/skills/c4-architecture/SKILL.md @@ -12,7 +12,8 @@ Generate software architecture documentation using C4 model diagrams in Mermaid 1. **Understand scope** - Determine which C4 level(s) are needed based on audience 2. **Analyze codebase** - Explore the system to identify components, containers, and relationships 3. **Generate diagrams** - Create Mermaid C4 diagrams at appropriate abstraction levels -4. **Document** - Write diagrams to markdown files with explanatory context +4. **Validate** - Verify all relationships have technology labels, every element has a description, and diagrams render correctly in Mermaid preview +5. **Document** - Write diagrams to markdown files with explanatory context ## C4 Diagram Levels @@ -203,22 +204,14 @@ Use `$offsetX` and `$offsetY` to fix overlapping relationship labels. 4. **Include technology labels** - "JSON/HTTPS", "JDBC", "gRPC" 5. **Stay under 20 elements per diagram** - Split complex systems into multiple diagrams -### Clarity Guidelines - -1. **Start at Level 1** - Context diagrams help frame the system scope -2. **One diagram per file** - Keep diagrams focused on a single abstraction level -3. **Meaningful aliases** - Use descriptive aliases (e.g., `orderService` not `s1`) -4. **Concise descriptions** - Keep descriptions under 50 characters when possible -5. **Always include a title** - "System Context diagram for [System Name]" - -### What to Avoid +### C4-Specific Gotchas See [references/common-mistakes.md](references/common-mistakes.md) for detailed anti-patterns: -- Confusing containers (deployable) vs components (non-deployable) -- Modeling shared libraries as containers -- Showing message brokers as single containers instead of individual topics -- Adding undefined abstraction levels like "subcomponents" -- Removing type labels to "simplify" diagrams +- Confusing containers (deployable units) vs components (non-deployable modules within a container) +- Modeling shared libraries as containers — they are not independently deployable +- Showing message brokers as single containers instead of individual topics/queues +- Adding undefined abstraction levels like "subcomponents" — C4 has exactly four levels +- Removing type labels to "simplify" diagrams — types are what make C4 diagrams self-describing ## Microservices Guidelines diff --git a/skills/codex/SKILL.md b/skills/codex/SKILL.md index 82f09ba..7bf1838 100644 --- a/skills/codex/SKILL.md +++ b/skills/codex/SKILL.md @@ -1,12 +1,13 @@ --- name: codex -description: Use when the user asks to run Codex CLI (codex exec, codex resume) or references OpenAI Codex for code analysis, refactoring, or automated editing. Uses GPT-5.2 by default for state-of-the-art software engineering. +description: Executes OpenAI Codex CLI for AI-assisted code generation, multi-file editing, and automated refactoring. Use when the user asks to run Codex CLI commands (codex exec, codex resume), generate code patches, apply multi-file edits, execute AI-assisted shell commands, or references OpenAI Codex for code analysis or automated editing. --- # Codex Skill Guide ## Running a Task -1. Default to `gpt-5.2` model. Ask the user (via `AskUserQuestion`) which reasoning effort to use (`xhigh`,`high`, `medium`, or `low`). User can override model if needed (see Model Options below). + +1. Default to `gpt-5.2` model. Ask the user (via `AskUserQuestion`) which reasoning effort to use (`xhigh`, `high`, `medium`, or `low`). User can override model if needed (see Model Options below). 2. Select the sandbox mode required for the task; default to `--sandbox read-only` unless edits or network access are necessary. 3. Assemble the command with the appropriate options: - `-m, --model ` @@ -14,53 +15,64 @@ description: Use when the user asks to run Codex CLI (codex exec, codex resume) - `--sandbox ` - `--full-auto` - `-C, --cd ` - - `--skip-git-repo-check` -3. Always use --skip-git-repo-check. -4. When continuing a previous session, use `codex exec --skip-git-repo-check resume --last` via stdin. When resuming don't use any configuration flags unless explicitly requested by the user e.g. if he species the model or the reasoning effort when requesting to resume a session. Resume syntax: `echo "your prompt here" | codex exec --skip-git-repo-check resume --last 2>/dev/null`. All flags have to be inserted between exec and resume. -5. **IMPORTANT**: By default, append `2>/dev/null` to all `codex exec` commands to suppress thinking tokens (stderr). Only show stderr if the user explicitly requests to see thinking tokens or if debugging is needed. -6. Run the command, capture stdout/stderr (filtered as appropriate), and summarize the outcome for the user. -7. **After Codex completes**, inform the user: "You can resume this Codex session at any time by saying 'codex resume' or asking me to continue with additional analysis or changes." + - `--skip-git-repo-check` (always include this flag) +4. **IMPORTANT**: Append `2>/dev/null` to all `codex exec` commands to suppress thinking tokens (stderr). Only show stderr if the user explicitly requests it or debugging is needed. +5. Run the command, capture output, and summarize the outcome for the user. +6. **Validate**: If the exit code is non-zero, report the error and ask the user how to proceed before retrying. +7. **After Codex completes**, inform the user: "You can resume this Codex session at any time by saying 'codex resume'." + +### Resuming a Session + +When continuing a previous session, pipe the new prompt via stdin. Do not add configuration flags unless the user explicitly requests a different model or reasoning effort: + +```bash +echo "your prompt here" | codex exec --skip-git-repo-check resume --last 2>/dev/null +``` + +All flags must be inserted between `exec` and `resume`. The resumed session inherits model, reasoning effort, and sandbox mode from the original. ### Quick Reference -| Use case | Sandbox mode | Key flags | + +| Use case | Sandbox mode | Command pattern | | --- | --- | --- | -| Read-only review or analysis | `read-only` | `--sandbox read-only 2>/dev/null` | -| Apply local edits | `workspace-write` | `--sandbox workspace-write --full-auto 2>/dev/null` | -| Permit network or broad access | `danger-full-access` | `--sandbox danger-full-access --full-auto 2>/dev/null` | -| Resume recent session | Inherited from original | `echo "prompt" \| codex exec --skip-git-repo-check resume --last 2>/dev/null` (no flags allowed) | -| Run from another directory | Match task needs | `-C ` plus other flags `2>/dev/null` | +| Read-only review or analysis | `read-only` | `codex exec --skip-git-repo-check -m gpt-5.2 --sandbox read-only "prompt" 2>/dev/null` | +| Apply local edits | `workspace-write` | `codex exec --skip-git-repo-check --sandbox workspace-write --full-auto "prompt" 2>/dev/null` | +| Network or broad access | `danger-full-access` | `codex exec --skip-git-repo-check --sandbox danger-full-access --full-auto "prompt" 2>/dev/null` | +| Resume recent session | Inherited | `echo "prompt" \| codex exec --skip-git-repo-check resume --last 2>/dev/null` | +| Run from another directory | Match task needs | `codex exec --skip-git-repo-check -C "prompt" 2>/dev/null` | ## Model Options -| Model | Best for | Context window | Key features | -| --- | --- | --- | --- | -| `gpt-5.2-max` | **Max model**: Ultra-complex reasoning, deep problem analysis | 400K input / 128K output | 76.3% SWE-bench, adaptive reasoning, $1.25/$10.00 | -| `gpt-5.2` ⭐ | **Flagship model**: Software engineering, agentic coding workflows | 400K input / 128K output | 76.3% SWE-bench, adaptive reasoning, $1.25/$10.00 | -| `gpt-5.2-mini` | Cost-efficient coding (4x more usage allowance) | 400K input / 128K output | Near SOTA performance, $0.25/$2.00 | -| `gpt-5.1-thinking` | Ultra-complex reasoning, deep problem analysis | 400K input / 128K output | Adaptive thinking depth, runs 2x slower on hardest tasks | +| Model | Best for | +| --- | --- | +| `gpt-5.2` (default) | Software engineering, agentic coding workflows | +| `gpt-5.2-max` | Ultra-complex reasoning, deep problem analysis | +| `gpt-5.2-mini` | Cost-efficient coding (4x more usage allowance) | +| `gpt-5.1-thinking` | Adaptive thinking depth for hardest tasks | -**GPT-5.2 Advantages**: 76.3% SWE-bench (vs 72.8% GPT-5), 30% faster on average tasks, better tool handling, reduced hallucinations, improved code quality. Knowledge cutoff: September 30, 2024. +All models support 400K input / 128K output context windows. -**Reasoning Effort Levels**: -- `xhigh` - Ultra-complex tasks (deep problem analysis, complex reasoning, deep understanding of the problem) -- `high` - Complex tasks (refactoring, architecture, security analysis, performance optimization) -- `medium` - Standard tasks (refactoring, code organization, feature additions, bug fixes) -- `low` - Simple tasks (quick fixes, simple changes, code formatting, documentation) +### Reasoning Effort Levels -**Cached Input Discount**: 90% off ($0.125/M tokens) for repeated context, cache lasts up to 24 hours. +| Level | When to use | Examples | +| --- | --- | --- | +| `xhigh` | Ultra-complex tasks | Deep problem analysis, complex multi-system reasoning | +| `high` | Complex tasks | Architecture refactoring, security analysis, performance optimization | +| `medium` | Standard tasks | Code organization, feature additions, bug fixes | +| `low` | Simple tasks | Quick fixes, formatting, documentation updates | ## Following Up -- After every `codex` command, immediately use `AskUserQuestion` to confirm next steps, collect clarifications, or decide whether to resume with `codex exec resume --last`. -- When resuming, pipe the new prompt via stdin: `echo "new prompt" | codex exec resume --last 2>/dev/null`. The resumed session automatically uses the same model, reasoning effort, and sandbox mode from the original session. -- Restate the chosen model, reasoning effort, and sandbox mode when proposing follow-up actions. + +1. After every `codex` command, use `AskUserQuestion` to confirm next steps or decide whether to resume. +2. Restate the chosen model, reasoning effort, and sandbox mode when proposing follow-up actions. ## Error Handling -- Stop and report failures whenever `codex --version` or a `codex exec` command exits non-zero; request direction before retrying. -- Before you use high-impact flags (`--full-auto`, `--sandbox danger-full-access`, `--skip-git-repo-check`) ask the user for permission using AskUserQuestion unless it was already given. -- When output includes warnings or partial results, summarize them and ask how to adjust using `AskUserQuestion`. -## CLI Version +1. **Non-zero exit**: Stop, report the failure, and request direction via `AskUserQuestion` before retrying. +2. **High-impact flags**: Before using `--full-auto`, `--sandbox danger-full-access`, or `--skip-git-repo-check`, ask permission via `AskUserQuestion` unless already granted. +3. **Warnings or partial results**: Summarize issues and ask how to adjust via `AskUserQuestion`. +4. **Validation checkpoint**: After each `codex exec` run, check the exit code. If non-zero, inspect stderr (`codex exec ... 2>&1`), adjust the prompt or flags, and retry with user approval. -Requires Codex CLI v0.57.0 or later for GPT-5.2 model support. The CLI defaults to `gpt-5.2` on macOS/Linux and `gpt-5.2` on Windows. Check version: `codex --version` +## CLI Version -Use `/model` slash command within a Codex session to switch models, or configure default in `~/.codex/config.toml`. +Requires Codex CLI v0.57.0+. Check version: `codex --version`. Use `/model` within a session to switch models, or set defaults in `~/.codex/config.toml`. diff --git a/skills/crafting-effective-readmes/SKILL.md b/skills/crafting-effective-readmes/SKILL.md index a6c30d9..3678265 100644 --- a/skills/crafting-effective-readmes/SKILL.md +++ b/skills/crafting-effective-readmes/SKILL.md @@ -1,6 +1,6 @@ --- name: crafting-effective-readmes -description: Use when writing or improving README files. Not all READMEs are the same — provides templates and guidance matched to your audience and project type. +description: Generate and improve README.md files — structure sections, write installation instructions, create usage examples, format code blocks, and add badges. Use when writing or improving README files, project documentation, repo descriptions, or markdown docs. Provides templates and guidance matched to your audience and project type. --- # Crafting Effective READMEs diff --git a/skills/daily-meeting-update/SKILL.md b/skills/daily-meeting-update/SKILL.md index 190b070..2257523 100644 --- a/skills/daily-meeting-update/SKILL.md +++ b/skills/daily-meeting-update/SKILL.md @@ -12,31 +12,9 @@ Generate a daily standup/meeting update through an **interactive interview**. Ne ## Workflow -``` -START - │ - ▼ -┌─────────────────────────────────────────────────────┐ -│ Phase 1: DETECT & OFFER INTEGRATIONS │ -│ • Check: Claude Code history? gh CLI? jira CLI? │ -│ • Claude Code → Pull yesterday's session digest │ -│ → User selects relevant items via multiSelect │ -│ • GitHub/Jira → Ask user, pull if approved │ -│ • Pull data NOW (before interview) │ -├─────────────────────────────────────────────────────┤ -│ Phase 2: INTERVIEW (with insights) │ -│ • Show pulled data as context │ -│ • Yesterday: "I see you merged PR #123, what else?" │ -│ • Today: What will you work on? │ -│ • Blockers: Anything blocking you? │ -│ • Topics: Anything to discuss at end of meeting? │ -├─────────────────────────────────────────────────────┤ -│ Phase 3: GENERATE UPDATE │ -│ • Combine interview answers + tool data │ -│ • Format as clean Markdown │ -│ • Present to user │ -└─────────────────────────────────────────────────────┘ -``` +1. **Detect & Offer Integrations** - Silently check for gh/jira/Claude Code, ask user for consent, pull approved data +2. **Interview (with insights)** - Ask 4 questions using pulled data as context to trigger memory +3. **Generate Update** - Combine interview answers + tool data into clean Markdown --- @@ -105,8 +83,6 @@ Options: ### Step 4: Offer Claude Code History -This integration captures everything you worked on with Claude Code — useful for recalling work that isn't in git or Jira. - **Detection:** ```bash ls ~/.claude/projects/*/*.jsonl 2>/dev/null | head -1 @@ -301,108 +277,19 @@ python3 ~/.claude/skills/daily-meeting-update/scripts/claude_digest.py --project --- -## Example Session - -``` -Claude: "Let's prepare your daily! I detected GitHub configured. Want me to pull your recent activity?" -User: "Yes" - -Claude: "Which repos should I check?" -User: "backend-api and frontend-app" - -[Claude pulls GitHub data silently] - -Claude: "I can also pull your Claude Code session history from yesterday. Want me to check?" -User: "Yes" - -[Claude runs digest script, gets 5 sessions] - -Claude: "Here are your Claude Code sessions from yesterday. Select the ones relevant to your standup:" - ☑ Fix authentication timeout bug (backend-api) - ☑ Implement OAuth flow (backend-api) - ☐ Update personal blog (blog) - [user unchecks personal project] - ☑ Research payment providers (docs) - ☐ Debugging test failures (experiments) - -User: [selects 3 relevant items] - -Claude: "Here's what I found from your activity: -- Merged PR #120: fix login timeout -- Opened PR #125: feat: add OAuth flow -- Reviewed PR #123 (approved), PR #456 (changes requested) -- 5 commits in backend-api -- [From Claude Code] Fix authentication timeout bug -- [From Claude Code] Implement OAuth flow -- [From Claude Code] Research payment providers - -Anything else you worked on yesterday that I missed?" -User: "No, that covers it" - -Claude: "What will you work on today?" -User: "Continue the OAuth feature and deploy to staging" - -Claude: "Any blockers?" -User: "No" - -Claude: "Any topic to bring up at the end of the daily?" -User: "Yes, I want to discuss the architecture of the new payments module" - -[Claude generates update] -``` - ---- - -## Output Example - -```markdown -# Daily Update - 2026-01-22 - -## Yesterday -- Worked on authentication feature -- Research on payment providers -- Merged PR #120 (fix: login timeout) -- Opened PR #125 (feat: add OAuth flow) - -## Today -- Continue OAuth feature -- Deploy to staging - -## Blockers -- No blockers - -## PRs & Reviews -- **Opened:** PR #125 - feat: add OAuth flow -- **Merged:** PR #120 - fix: login timeout -- **Reviews:** PR #123 (approved), PR #456 (changes requested) - -## Topics for Discussion -- Architecture of the new payments module - ---- -*Links:* -- https://github.com/org/repo/pull/125 -- https://github.com/org/repo/pull/120 -``` - ---- - -## Anti-Patterns +## Examples -| Avoid | Why (Expert Knowledge) | Instead | -|-------|------------------------|---------| -| Run gh/jira without asking | Users may have personal repos visible, or be in a sensitive project context they don't want exposed | Always ask first, let user choose repos | -| Assume current directory is the only project | Developers often work on 2-5 repos simultaneously (frontend, backend, infra) | Ask "Which projects are you working on?" | -| Skip interview even with tool data | Tools capture WHAT happened but miss WHY and context (research, meetings, planning) | Interview is primary, tools supplement | -| Generate update before all 4 questions | User might have critical blocker or discussion topic that changes the narrative | Complete interview, then generate | -| Include raw commit messages | Commit messages are often cryptic ("fix", "wip") and don't tell the story | Summarize into human-readable outcomes | -| Ask for data after interview | Showing insights during interview makes questions smarter ("I see you merged PR #123, anything else?") | Pull data first, then interview with context | +For a complete example session and output template, see [references/examples.md](references/examples.md). --- -## NEVER +## Constraints -- **NEVER assume tools are configured** — Many devs have gh installed but not authenticated, or jira CLI pointing to wrong instance -- **NEVER skip the "Topics for Discussion" question** — This is often the most valuable part of standup that tools can't capture -- **NEVER generate more than 15 bullets** — Standup should be <2 minutes to read; long updates lose the audience -- **NEVER include ticket/PR numbers without context** — "PROJ-123" means nothing; always include title or summary -- **NEVER pull data from repos user didn't explicitly approve** — Even if you can see other repos, respect boundaries +- **Never assume tools are configured** — detect silently, ask before pulling +- **Never skip "Topics for Discussion"** — often the most valuable part that tools cannot capture +- **Never generate more than 15 bullets** — standup should be <2 minutes to read +- **Never include ticket/PR numbers without context** — always include title or summary +- **Never pull data from repos user didn't approve** — respect boundaries +- **Always pull data before interview** — showing insights makes questions smarter +- **Always complete all 4 questions before generating** — blockers or discussion topics may change the narrative +- **Summarize, don't copy** — raw commit messages ("fix", "wip") don't tell the story diff --git a/skills/daily-meeting-update/references/examples.md b/skills/daily-meeting-update/references/examples.md new file mode 100644 index 0000000..b4180af --- /dev/null +++ b/skills/daily-meeting-update/references/examples.md @@ -0,0 +1,82 @@ +# Daily Meeting Update - Examples + +## Example Session + +``` +Claude: "Let's prepare your daily! I detected GitHub configured. Want me to pull your recent activity?" +User: "Yes" + +Claude: "Which repos should I check?" +User: "backend-api and frontend-app" + +[Claude pulls GitHub data silently] + +Claude: "I can also pull your Claude Code session history from yesterday. Want me to check?" +User: "Yes" + +[Claude runs digest script, gets 5 sessions] + +Claude: "Here are your Claude Code sessions from yesterday. Select the ones relevant to your standup:" + ☑ Fix authentication timeout bug (backend-api) + ☑ Implement OAuth flow (backend-api) + ☐ Update personal blog (blog) - [user unchecks personal project] + ☑ Research payment providers (docs) + ☐ Debugging test failures (experiments) + +User: [selects 3 relevant items] + +Claude: "Here's what I found from your activity: +- Merged PR #120: fix login timeout +- Opened PR #125: feat: add OAuth flow +- Reviewed PR #123 (approved), PR #456 (changes requested) +- 5 commits in backend-api +- [From Claude Code] Fix authentication timeout bug +- [From Claude Code] Implement OAuth flow +- [From Claude Code] Research payment providers + +Anything else you worked on yesterday that I missed?" +User: "No, that covers it" + +Claude: "What will you work on today?" +User: "Continue the OAuth feature and deploy to staging" + +Claude: "Any blockers?" +User: "No" + +Claude: "Any topic to bring up at the end of the daily?" +User: "Yes, I want to discuss the architecture of the new payments module" + +[Claude generates update] +``` + +## Output Example + +```markdown +# Daily Update - 2026-01-22 + +## Yesterday +- Worked on authentication feature +- Research on payment providers +- Merged PR #120 (fix: login timeout) +- Opened PR #125 (feat: add OAuth flow) + +## Today +- Continue OAuth feature +- Deploy to staging + +## Blockers +- No blockers + +## PRs & Reviews +- **Opened:** PR #125 - feat: add OAuth flow +- **Merged:** PR #120 - fix: login timeout +- **Reviews:** PR #123 (approved), PR #456 (changes requested) + +## Topics for Discussion +- Architecture of the new payments module + +--- +*Links:* +- https://github.com/org/repo/pull/125 +- https://github.com/org/repo/pull/120 +``` diff --git a/skills/database-schema-designer/SKILL.md b/skills/database-schema-designer/SKILL.md index 624a8e2..200b6ce 100644 --- a/skills/database-schema-designer/SKILL.md +++ b/skills/database-schema-designer/SKILL.md @@ -1,6 +1,6 @@ --- name: database-schema-designer -description: Design robust, scalable database schemas for SQL and NoSQL databases. Provides normalization guidelines, indexing strategies, migration patterns, constraint design, and performance optimization. Ensures data integrity, query performance, and maintainable data models. +description: Design robust, scalable database schemas for SQL and NoSQL databases. Provides normalization guidelines, indexing strategies, migration patterns, constraint design, and performance optimization for PostgreSQL, MySQL, SQLite, and MongoDB. Use when the user asks to design tables, plan a database structure, create an ERD or entity-relationship model, define foreign keys, normalize data, plan migrations, or optimize query performance. license: MIT --- @@ -57,21 +57,6 @@ CREATE TABLE orders ( --- -## Key Terms - -| Term | Definition | -|------|------------| -| **Normalization** | Organizing data to reduce redundancy (1NF → 2NF → 3NF) | -| **3NF** | Third Normal Form - no transitive dependencies between columns | -| **OLTP** | Online Transaction Processing - write-heavy, needs normalization | -| **OLAP** | Online Analytical Processing - read-heavy, benefits from denormalization | -| **Foreign Key (FK)** | Column that references another table's primary key | -| **Index** | Data structure that speeds up queries (at cost of slower writes) | -| **Access Pattern** | How your app reads/writes data (queries, joins, filters) | -| **Denormalization** | Intentionally duplicating data to speed up reads | - ---- - ## Quick Reference | Task | Approach | Key Consideration | diff --git a/skills/dependency-updater/SKILL.md b/skills/dependency-updater/SKILL.md index edede5b..8d94d73 100644 --- a/skills/dependency-updater/SKILL.md +++ b/skills/dependency-updater/SKILL.md @@ -1,6 +1,6 @@ --- name: dependency-updater -description: Smart dependency management for any language. Auto-detects project type, applies safe updates automatically, prompts for major versions, diagnoses and fixes dependency issues. +description: Smart dependency management for any language. Auto-detects project type, applies safe updates automatically, prompts for major versions, diagnoses and fixes dependency issues. Use when updating packages, resolving version conflicts, running npm/pip/cargo/go outdated checks, upgrading dependencies in package.json, requirements.txt, go.mod, or Cargo.toml, or auditing for vulnerabilities. license: MIT metadata: version: 1.0.0 @@ -248,33 +248,7 @@ go mod tidy --- -## Security Audit - -Run security checks for any project: - -```bash -# Node.js -npm audit -npm audit --json | jq '.metadata.vulnerabilities' - -# Python -pip-audit -safety check - -# Go -govulncheck ./... - -# Rust -cargo audit - -# Ruby -bundle audit - -# .NET -dotnet list package --vulnerable -``` - -### Severity Response +## Severity Response | Severity | Action | |----------|--------| @@ -380,43 +354,6 @@ Some packages have frequent major bumps but are backward-compatible: -
-Deep Dive: Version Strategies - -### Semantic Versioning - -``` -MAJOR.MINOR.PATCH (e.g., 2.3.1) - -MAJOR: Breaking changes - requires code changes -MINOR: New features - backward compatible -PATCH: Bug fixes - backward compatible -``` - -### Range Specifiers - -| Specifier | Meaning | Example | -|-----------|---------|---------| -| `^1.2.3` | Minor + Patch OK | `>=1.2.3 <2.0.0` | -| `~1.2.3` | Patch only | `>=1.2.3 <1.3.0` | -| `1.2.3` | Exact (fixed) | Only `1.2.3` | -| `>=1.2.3` | At least | Any `>=1.2.3` | -| `*` | Any | Latest (dangerous) | - -### Recommended Strategy - -```json -{ - "dependencies": { - "critical-lib": "1.2.3", // Exact for critical - "stable-lib": "~1.2.3", // Patch only for stable - "modern-lib": "^1.2.3" // Minor OK for active - } -} -``` - -
-
Deep Dive: Conflict Resolution @@ -480,12 +417,3 @@ pip install -c constraints.txt -r requirements.txt --- -## Related Tools - -| Tool | Language | Purpose | -|------|----------|---------| -| [taze](https://github.com/antfu-collective/taze) | Node.js | Smart dependency updates | -| [npm-check-updates](https://github.com/raineorshine/npm-check-updates) | Node.js | Alternative to taze | -| [pip-review](https://github.com/jgonggrijp/pip-review) | Python | Interactive pip updates | -| [cargo-edit](https://github.com/killercup/cargo-edit) | Rust | Cargo dependency management | -| [bundler-audit](https://github.com/rubysec/bundler-audit) | Ruby | Security auditing | diff --git a/skills/design-system-starter/SKILL.md b/skills/design-system-starter/SKILL.md index 4d37e9b..981ce61 100644 --- a/skills/design-system-starter/SKILL.md +++ b/skills/design-system-starter/SKILL.md @@ -1,603 +1,104 @@ --- name: design-system-starter -description: Create and evolve design systems with design tokens, component architecture, accessibility guidelines, and documentation templates. Ensures consistent, scalable, and accessible UI across products. +description: "Create and evolve design systems with design tokens, component architecture, theming, and WCAG-compliant accessibility patterns for front-end UI projects. Use when the user asks to build a design system, UI kit, style guide, component library, theme system, brand guidelines, or set up design tokens, dark mode, or consistent UI across products." license: MIT metadata: version: 1.0.0 - tags: [design-system, ui, components, design-tokens, accessibility, frontend] + tags: "design-system, ui, components, design-tokens, accessibility, frontend" --- # Design System Starter Build robust, scalable design systems that ensure visual consistency and exceptional user experiences. ---- - -## Quick Start - -Just describe what you need: - -``` -Create a design system for my React app with dark mode support -``` - -That's it. The skill provides tokens, components, and accessibility guidelines. - ---- - ## Triggers | Trigger | Example | |---------|---------| -| Create design system | "Create a design system for my app" | -| Design tokens | "Set up design tokens for colors and spacing" | -| Component architecture | "Design component structure using atomic design" | -| Accessibility | "Ensure WCAG 2.1 compliance for my components" | -| Dark mode | "Implement theming with dark mode support" | - ---- +| Create design system / UI kit / style guide | "Create a design system for my app" | +| Design tokens / theme setup | "Set up design tokens for colors and spacing" | +| Component library / component architecture | "Design component structure using atomic design" | +| Accessibility / WCAG compliance | "Ensure WCAG 2.1 compliance for my components" | +| Dark mode / theming | "Implement theming with dark mode support" | +| Brand guidelines / style consistency | "Set up brand guidelines for consistent UI" | ## Quick Reference | Task | Output | |------|--------| -| Design tokens | Color, typography, spacing, shadows JSON | +| Design tokens | Color, typography, spacing, shadows in W3C token format | | Component structure | Atomic design hierarchy (atoms, molecules, organisms) | -| Theming | CSS variables or ThemeProvider setup | -| Accessibility | WCAG 2.1 AA compliant patterns | +| Theming | CSS variables, Tailwind dark mode, or ThemeProvider setup | +| Accessibility | WCAG 2.1 AA compliant patterns with keyboard and ARIA support | | Documentation | Component docs with props, examples, a11y notes | ---- - ## Bundled Resources -- `references/component-examples.md` - Complete component implementations -- `templates/design-tokens-template.json` - W3C design token format -- `templates/component-template.tsx` - React component template -- `checklists/design-system-checklist.md` - Design system audit checklist - ---- - -## Design System Philosophy - -### What is a Design System? - -A design system is more than a component library—it's a collection of: - -1. **Design Tokens**: Foundational design decisions (colors, spacing, typography) -2. **Components**: Reusable UI building blocks -3. **Patterns**: Common UX solutions and compositions -4. **Guidelines**: Rules, principles, and best practices -5. **Documentation**: How to use everything effectively - -### Core Principles - -**1. Consistency Over Creativity** -- Predictable patterns reduce cognitive load -- Users learn once, apply everywhere -- Designers and developers speak the same language - -**2. Accessible by Default** -- WCAG 2.1 Level AA compliance minimum -- Keyboard navigation built-in -- Screen reader support from the start - -**3. Scalable and Maintainable** -- Design tokens enable global changes -- Component composition reduces duplication -- Versioning and deprecation strategies - -**4. Developer-Friendly** -- Clear API contracts -- Comprehensive documentation -- Easy to integrate and customize - ---- - -## Design Tokens - -Design tokens are the atomic design decisions that define your system's visual language. - -### Token Categories - -#### 1. Color Tokens - -**Primitive Colors** (Raw values): -```json -{ - "color": { - "primitive": { - "blue": { - "50": "#eff6ff", - "100": "#dbeafe", - "200": "#bfdbfe", - "300": "#93c5fd", - "400": "#60a5fa", - "500": "#3b82f6", - "600": "#2563eb", - "700": "#1d4ed8", - "800": "#1e40af", - "900": "#1e3a8a", - "950": "#172554" - } - } - } -} -``` - -**Semantic Colors** (Contextual meaning): -```json -{ - "color": { - "semantic": { - "brand": { - "primary": "{color.primitive.blue.600}", - "primary-hover": "{color.primitive.blue.700}", - "primary-active": "{color.primitive.blue.800}" - }, - "text": { - "primary": "{color.primitive.gray.900}", - "secondary": "{color.primitive.gray.600}", - "tertiary": "{color.primitive.gray.500}", - "disabled": "{color.primitive.gray.400}", - "inverse": "{color.primitive.white}" - }, - "background": { - "primary": "{color.primitive.white}", - "secondary": "{color.primitive.gray.50}", - "tertiary": "{color.primitive.gray.100}" - }, - "feedback": { - "success": "{color.primitive.green.600}", - "warning": "{color.primitive.yellow.600}", - "error": "{color.primitive.red.600}", - "info": "{color.primitive.blue.600}" - } - } - } -} -``` - -**Accessibility**: Ensure color contrast ratios meet WCAG 2.1 Level AA: -- Normal text: 4.5:1 minimum -- Large text (18pt+ or 14pt+ bold): 3:1 minimum -- UI components and graphics: 3:1 minimum - -#### 2. Typography Tokens - -```json -{ - "typography": { - "fontFamily": { - "sans": "'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif", - "serif": "'Georgia', 'Times New Roman', serif", - "mono": "'Fira Code', 'Courier New', monospace" - }, - "fontSize": { - "xs": "0.75rem", // 12px - "sm": "0.875rem", // 14px - "base": "1rem", // 16px - "lg": "1.125rem", // 18px - "xl": "1.25rem", // 20px - "2xl": "1.5rem", // 24px - "3xl": "1.875rem", // 30px - "4xl": "2.25rem", // 36px - "5xl": "3rem" // 48px - }, - "fontWeight": { - "normal": 400, - "medium": 500, - "semibold": 600, - "bold": 700 - }, - "lineHeight": { - "tight": 1.25, - "normal": 1.5, - "relaxed": 1.75, - "loose": 2 - }, - "letterSpacing": { - "tight": "-0.025em", - "normal": "0", - "wide": "0.025em" - } - } -} -``` - -#### 3. Spacing Tokens - -**Scale**: Use a consistent spacing scale (commonly 4px or 8px base) - -```json -{ - "spacing": { - "0": "0", - "1": "0.25rem", // 4px - "2": "0.5rem", // 8px - "3": "0.75rem", // 12px - "4": "1rem", // 16px - "5": "1.25rem", // 20px - "6": "1.5rem", // 24px - "8": "2rem", // 32px - "10": "2.5rem", // 40px - "12": "3rem", // 48px - "16": "4rem", // 64px - "20": "5rem", // 80px - "24": "6rem" // 96px - } -} -``` - -**Component-Specific Spacing**: -```json -{ - "component": { - "button": { - "padding-x": "{spacing.4}", - "padding-y": "{spacing.2}", - "gap": "{spacing.2}" - }, - "card": { - "padding": "{spacing.6}", - "gap": "{spacing.4}" - } - } -} -``` - -#### 4. Border Radius Tokens - -```json -{ - "borderRadius": { - "none": "0", - "sm": "0.125rem", // 2px - "base": "0.25rem", // 4px - "md": "0.375rem", // 6px - "lg": "0.5rem", // 8px - "xl": "0.75rem", // 12px - "2xl": "1rem", // 16px - "full": "9999px" - } -} -``` - -#### 5. Shadow Tokens - -```json -{ - "shadow": { - "xs": "0 1px 2px 0 rgba(0, 0, 0, 0.05)", - "sm": "0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px -1px rgba(0, 0, 0, 0.1)", - "base": "0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1)", - "md": "0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1)", - "lg": "0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 8px 10px -6px rgba(0, 0, 0, 0.1)", - "xl": "0 25px 50px -12px rgba(0, 0, 0, 0.25)" - } -} -``` - ---- - -## Component Architecture +- `references/component-examples.md` — Complete component implementations (Button, FormField, Card, Modal, polymorphic patterns) +- `templates/design-tokens-template.json` — W3C design token format with color, typography, spacing, shadows +- `templates/component-template.tsx` — React component template with TypeScript props and a11y +- `checklists/design-system-checklist.md` — Design system audit checklist -### Atomic Design Methodology +## Workflow -**Atoms** → **Molecules** → **Organisms** → **Templates** → **Pages** +### 1. Define Design Tokens -#### Atoms (Primitive Components) -Basic building blocks that can't be broken down further. +Establish foundational tokens for colors, typography, spacing, border-radius, and shadows. Use a three-tier token architecture: -**Examples:** -- Button -- Input -- Label -- Icon -- Badge -- Avatar +- **Primitive tokens**: Raw values (e.g., `blue.600: "#2563eb"`) +- **Semantic tokens**: Contextual meaning referencing primitives (e.g., `brand.primary: "{color.primitive.blue.600}"`) +- **Component tokens**: Component-specific values referencing semantic tokens (e.g., `button.padding-x: "{spacing.4}"`) -**Button Component:** -```typescript -interface ButtonProps { - variant?: 'primary' | 'secondary' | 'outline' | 'ghost'; - size?: 'sm' | 'md' | 'lg'; - disabled?: boolean; - loading?: boolean; - icon?: React.ReactNode; - children: React.ReactNode; -} -``` +See `templates/design-tokens-template.json` for the complete W3C token format with all categories. -See `references/component-examples.md` for complete Button implementation with variants, sizes, and styling patterns. +**Validation**: Run a contrast checker on all text/background color combinations. WCAG 2.1 AA requires 4.5:1 for normal text, 3:1 for large text and UI components. -#### Molecules (Simple Compositions) -Groups of atoms that function together. +### 2. Build Components (Atomic Design) -**Examples:** -- SearchBar (Input + Button) -- FormField (Label + Input + ErrorMessage) -- Card (Container + Title + Content + Actions) +Follow the atomic design hierarchy: **Atoms** → **Molecules** → **Organisms** → **Templates** → **Pages** -**FormField Molecule:** -```typescript -interface FormFieldProps { - label: string; - name: string; - error?: string; - hint?: string; - required?: boolean; - children: React.ReactNode; -} -``` +Start with atoms (Button, Input, Label, Icon, Badge, Avatar), then compose into molecules (SearchBar, FormField, Card) and organisms (Navigation, Modal Dialog). -See `references/component-examples.md` for FormField, Card (compound component pattern), Input with variants, Modal, and more composition examples. +Key API design principles: +- Use consistent prop names across components (`variant`, `size`) +- Provide sensible defaults (variant defaults to `primary`, size to `md`) +- Prefer composition over configuration (use `` not `header="..."` props) +- Support polymorphic rendering (` - -``` - -See `references/component-examples.md` for complete polymorphic component TypeScript patterns. - ---- - -## Theming and Dark Mode - -### Theme Structure - -```typescript -interface Theme { - colors: { - brand: { - primary: string; - secondary: string; - }; - text: { - primary: string; - secondary: string; - }; - background: { - primary: string; - secondary: string; - }; - feedback: { - success: string; - warning: string; - error: string; - info: string; - }; - }; - typography: { - fontFamily: { - sans: string; - mono: string; - }; - fontSize: Record; - }; - spacing: Record; - borderRadius: Record; - shadow: Record; -} -``` - -### Dark Mode Implementation - -**Approach 1: CSS Variables** -```css -:root { - --color-bg-primary: #ffffff; - --color-text-primary: #000000; -} - -[data-theme="dark"] { - --color-bg-primary: #1a1a1a; - --color-text-primary: #ffffff; -} -``` - -**Approach 2: Tailwind CSS Dark Mode** -```tsx -
- Content -
-``` - -**Approach 3: Styled Components ThemeProvider** -```typescript -const lightTheme = { background: '#fff', text: '#000' }; -const darkTheme = { background: '#000', text: '#fff' }; - - - - -``` - ---- +See `references/component-examples.md` for accessibility patterns including Skip Links and focus traps. -## Accessibility Guidelines +### 5. Document and Ship -### WCAG 2.1 Level AA Compliance +Each component needs: purpose, usage example, variants, props table, accessibility notes, and code examples. Use Storybook or Docusaurus for interactive documentation. -#### Color Contrast -- **Normal text** (< 18pt): 4.5:1 minimum -- **Large text** (≥ 18pt or ≥ 14pt bold): 3:1 minimum -- **UI components**: 3:1 minimum - -**Tools**: Use contrast checkers like [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) - -#### Keyboard Navigation -```typescript -// ✅ All interactive elements must be keyboard accessible - - -// ✅ Focus management - - - {/* Modal content */} - - -``` - -#### ARIA Attributes -Essential ARIA patterns: -- `aria-label`: Provide accessible names -- `aria-expanded`: Communicate expanded/collapsed state -- `aria-controls`: Associate controls with content -- `aria-live`: Announce dynamic content changes - -#### Screen Reader Support -- Use semantic HTML elements (`