diff --git a/README.md b/README.md index d03ef3f4..11538996 100644 --- a/README.md +++ b/README.md @@ -44,11 +44,13 @@ Below is the complete list of available skills. Each skill folder contains a `SK | Skill Name | Description | Path | | :------------------------------- | :------------------------------------------------------------- | :--------------------------------------------- | +| **Address GitHub Comments** | Systematic PR feedback handling using gh CLI. | `skills/address-github-comments` ⭐ NEW | | **Algorithmic Art** | Creative generative art using p5.js and seeded randomness. | `skills/algorithmic-art` | | **App Store Optimization** | Complete ASO toolkit for iOS and Android app performance. | `skills/app-store-optimization` | | **Autonomous Agent Patterns** | Design patterns for autonomous coding agents and tools. | `skills/autonomous-agent-patterns` ⭐ NEW | | **AWS Pentesting** | Specialized security assessment for Amazon Web Services. | `skills/aws-penetration-testing` | | **Backend Guidelines** | Core architecture patterns for Node/Express microservices. | `skills/backend-dev-guidelines` | +| **Concise Planning** | Atomic, actionable task planning and checklists. | `skills/concise-planning` ⭐ NEW | | **Brainstorming** | Requirement discovery and intent exploration framework. | `skills/brainstorming` | | **Brand Guidelines (Anthropic)** | Official Anthropic brand styling and visual standards. | `skills/brand-guidelines-anthropic` ⭐ NEW | | **Brand Guidelines (Community)** | Community-contributed brand guidelines and templates. | `skills/brand-guidelines-community` | diff --git a/skills/address-github-comments/SKILL.md b/skills/address-github-comments/SKILL.md new file mode 100644 index 00000000..424fab73 --- /dev/null +++ b/skills/address-github-comments/SKILL.md @@ -0,0 +1,55 @@ +--- +name: address-github-comments +description: Use when you need to address review or issue comments on an open GitHub Pull Request using the gh CLI. +--- + +# Address GitHub Comments + +## Overview + +Efficiently address PR review comments or issue feedback using the GitHub CLI (`gh`). This skill ensures all feedback is addressed systematically. + +## Prerequisites + +Ensure `gh` is authenticated. + +```bash +gh auth status +``` + +If not logged in, run `gh auth login`. + +## Workflow + +### 1. Inspect Comments + +Fetch the comments for the current branch's PR. + +```bash +gh pr view --comments +``` + +Or use a custom script if available to list threads. + +### 2. Categorize and Plan + +- List the comments and review threads. +- Propose a fix for each. +- **Wait for user confirmation** on which comments to address first if there are many. + +### 3. Apply Fixes + +Apply the code changes for the selected comments. + +### 4. Respond to Comments + +Once fixed, respond to the threads as resolved. + +```bash +gh pr comment --body "Addressed in latest commit." +``` + +## Common Mistakes + +- **Applying fixes without understanding context**: Always read the surrounding code of a comment. +- **Not verifying auth**: Check `gh auth status` before starting. diff --git a/skills/concise-planning/SKILL.md b/skills/concise-planning/SKILL.md new file mode 100644 index 00000000..51746315 --- /dev/null +++ b/skills/concise-planning/SKILL.md @@ -0,0 +1,62 @@ +--- +name: concise-planning +description: Use when a user asks for a plan for a coding task, to generate a clear, actionable, and atomic checklist. +--- + +# Concise Planning + +## Goal + +Turn a user request into a **single, actionable plan** with atomic steps. + +## Workflow + +### 1. Scan Context + +- Read `README.md`, docs, and relevant code files. +- Identify constraints (language, frameworks, tests). + +### 2. Minimal Interaction + +- Ask **at most 1–2 questions** and only if truly blocking. +- Make reasonable assumptions for non-blocking unknowns. + +### 3. Generate Plan + +Use the following structure: + +- **Approach**: 1-3 sentences on what and why. +- **Scope**: Bullet points for "In" and "Out". +- **Action Items**: A list of 6-10 atomic, ordered tasks (Verb-first). +- **Validation**: At least one item for testing. + +## Plan Template + +```markdown +# Plan + + + +## Scope + +- In: +- Out: + +## Action Items + +[ ] +[ ] +[ ] +[ ] +[ ] + +## Open Questions + +- +``` + +## Checklist Guidelines + +- **Atomic**: Each step should be a single logical unit of work. +- **Verb-first**: "Add...", "Refactor...", "Verify...". +- **Concrete**: Name specific files or modules when possible. diff --git a/skills/writing-skills/SKILL.md b/skills/writing-skills/SKILL.md index c60f18a4..71ac79b6 100644 --- a/skills/writing-skills/SKILL.md +++ b/skills/writing-skills/SKILL.md @@ -9,7 +9,7 @@ description: Use when creating new skills, editing existing skills, or verifying **Writing skills IS Test-Driven Development applied to process documentation.** -**Personal skills live in agent-specific directories (`~/.claude/skills` for Claude Code, `~/.codex/skills` for Codex)** +**Personal skills live in agent-specific directories (`~/.claude/skills` for Claude Code, `~/.codex/skills` for Codex)** You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes). @@ -29,30 +29,32 @@ A **skill** is a reference guide for proven techniques, patterns, or tools. Skil ## TDD Mapping for Skills -| TDD Concept | Skill Creation | -|-------------|----------------| -| **Test case** | Pressure scenario with subagent | -| **Production code** | Skill document (SKILL.md) | -| **Test fails (RED)** | Agent violates rule without skill (baseline) | -| **Test passes (GREEN)** | Agent complies with skill present | -| **Refactor** | Close loopholes while maintaining compliance | -| **Write test first** | Run baseline scenario BEFORE writing skill | -| **Watch it fail** | Document exact rationalizations agent uses | -| **Minimal code** | Write skill addressing those specific violations | -| **Watch it pass** | Verify agent now complies | -| **Refactor cycle** | Find new rationalizations → plug → re-verify | +| TDD Concept | Skill Creation | +| ----------------------- | ------------------------------------------------ | +| **Test case** | Pressure scenario with subagent | +| **Production code** | Skill document (SKILL.md) | +| **Test fails (RED)** | Agent violates rule without skill (baseline) | +| **Test passes (GREEN)** | Agent complies with skill present | +| **Refactor** | Close loopholes while maintaining compliance | +| **Write test first** | Run baseline scenario BEFORE writing skill | +| **Watch it fail** | Document exact rationalizations agent uses | +| **Minimal code** | Write skill addressing those specific violations | +| **Watch it pass** | Verify agent now complies | +| **Refactor cycle** | Find new rationalizations → plug → re-verify | The entire skill creation process follows RED-GREEN-REFACTOR. ## When to Create a Skill **Create when:** + - Technique wasn't intuitively obvious to you - You'd reference this again across projects - Pattern applies broadly (not project-specific) - Others would benefit **Don't create for:** + - One-off solutions - Standard practices well-documented elsewhere - Project-specific conventions (put in CLAUDE.md) @@ -61,17 +63,19 @@ The entire skill creation process follows RED-GREEN-REFACTOR. ## Skill Types ### Technique + Concrete method with steps to follow (condition-based-waiting, root-cause-tracing) ### Pattern + Way of thinking about problems (flatten-with-flags, test-invariants) ### Reference + API docs, syntax guides, tool documentation (office docs) ## Directory Structure - ``` skills/ skill-name/ @@ -82,17 +86,41 @@ skills/ **Flat namespace** - all skills in one searchable namespace **Separate files for:** + 1. **Heavy reference** (100+ lines) - API docs, comprehensive syntax 2. **Reusable tools** - Scripts, utilities, templates **Keep inline:** + - Principles and concepts - Code patterns (< 50 lines) - Everything else +## Set Appropriate Degrees of Freedom + +Match the level of specificity to the task's fragility and variability: + +- **High freedom (text-based instructions)**: Use when multiple approaches are valid or decisions depend on context. +- **Medium freedom (pseudocode or scripts with parameters)**: Use when a preferred pattern exists but some variation is acceptable. +- **Low freedom (specific scripts, no-context instructions)**: Use when operations are fragile, error-prone, or consistency is critical. + +## Progressive Disclosure + +Manage context efficiently by splitting detailed information into separate files: + +1. **Metadata (name + description)**: Always loaded for discovery. +2. **SKILL.md body**: Core workflow and high-level guidance. Keep under 500 lines. +3. **Bundled resources**: + - `scripts/`: Deterministic code/logic. + - `references/`: Detailed schemas, API docs, or domain knowledge. + - `assets/`: Templates, images, or static files. + +**Pattern**: Link to advanced content or variant-specific details (e.g., `aws.md` vs `gcp.md`) from the main `SKILL.md`. + ## SKILL.md Structure **Frontmatter (YAML):** + - Only two fields supported: `name` and `description` - Max 1024 characters total - `name`: Use letters, numbers, and hyphens only (no parentheses, special chars) @@ -111,32 +139,38 @@ description: Use when [specific triggering conditions and symptoms] # Skill Name ## Overview + What is this? Core principle in 1-2 sentences. ## When to Use + [Small inline flowchart IF decision non-obvious] Bullet list with SYMPTOMS and use cases When NOT to use ## Core Pattern (for techniques/patterns) + Before/after code comparison ## Quick Reference + Table or bullets for scanning common operations ## Implementation + Inline code for simple patterns Link to file for heavy reference or reusable tools ## Common Mistakes + What goes wrong + fixes ## Real-World Impact (optional) + Concrete results ``` - ## Claude Search Optimization (CSO) **Critical for discovery:** Future Claude needs to FIND your skill @@ -172,8 +206,9 @@ description: Use when implementing any feature or bugfix, before writing impleme ``` **Content:** + - Use concrete triggers, symptoms, and situations that signal this skill applies -- Describe the *problem* (race conditions, inconsistent behavior) not *language-specific symptoms* (setTimeout, sleep) +- Describe the _problem_ (race conditions, inconsistent behavior) not _language-specific symptoms_ (setTimeout, sleep) - Keep triggers technology-agnostic unless the skill itself is technology-specific - If skill is technology-specific, make that explicit in the trigger - Write in third person (injected into system prompt) @@ -199,6 +234,7 @@ description: Use when using React Router and handling authentication redirects ### 2. Keyword Coverage Use words Claude would search for: + - Error messages: "Hook timed out", "ENOTEMPTY", "race condition" - Symptoms: "flaky", "hanging", "zombie", "pollution" - Synonyms: "timeout/hang/freeze", "cleanup/teardown/afterEach" @@ -207,6 +243,7 @@ Use words Claude would search for: ### 3. Descriptive Naming **Use active voice, verb-first:** + - ✅ `creating-skills` not `skill-creation` - ✅ `condition-based-waiting` not `async-test-helpers` @@ -215,6 +252,7 @@ Use words Claude would search for: **Problem:** getting-started and frequently-referenced skills load into EVERY conversation. Every token counts. **Target word counts:** + - getting-started workflows: <150 words each - Frequently-loaded skills: <200 words total - Other skills: <500 words (still be concise) @@ -222,6 +260,7 @@ Use words Claude would search for: **Techniques:** **Move details to tool help:** + ```bash # ❌ BAD: Document all flags in SKILL.md search-conversations supports --text, --both, --after DATE, --before DATE, --limit N @@ -231,34 +270,42 @@ search-conversations supports multiple modes and filters. Run --help for details ``` **Use cross-references:** + ```markdown # ❌ BAD: Repeat workflow details + When searching, dispatch subagent with template... [20 lines of repeated instructions] # ✅ GOOD: Reference other skill + Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow. ``` **Compress examples:** + ```markdown # ❌ BAD: Verbose example (42 words) + your human partner: "How did we handle authentication errors in React Router before?" You: I'll search past conversations for React Router authentication patterns. [Dispatch subagent with search query: "React Router authentication error handling 401"] # ✅ GOOD: Minimal example (20 words) + Partner: "How did we handle auth errors in React Router?" You: Searching... [Dispatch subagent → synthesis] ``` **Eliminate redundancy:** + - Don't repeat what's in cross-referenced skills - Don't explain what's obvious from command - Don't include multiple examples of same pattern **Verification:** + ```bash wc -w skills/path/SKILL.md # getting-started workflows: aim for <150 each @@ -266,12 +313,14 @@ wc -w skills/path/SKILL.md ``` **Name by what you DO or core insight:** + - ✅ `condition-based-waiting` > `async-test-helpers` - ✅ `using-skills` not `skill-usage` - ✅ `flatten-with-flags` > `data-structure-refactoring` - ✅ `root-cause-tracing` > `debugging-techniques` **Gerunds (-ing) work well for processes:** + - `creating-skills`, `testing-skills`, `debugging-with-logs` - Active, describes the action you're taking @@ -280,6 +329,7 @@ wc -w skills/path/SKILL.md **When writing documentation that references other skills:** Use skill name only, with explicit requirement markers: + - ✅ Good: `**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development` - ✅ Good: `**REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debugging` - ❌ Bad: `See skills/testing/test-driven-development` (unclear if required) @@ -303,11 +353,13 @@ digraph when_flowchart { ``` **Use flowcharts ONLY for:** + - Non-obvious decision points - Process loops where you might stop too early - "When to use A vs B" decisions **Never use flowcharts for:** + - Reference material → Tables, lists - Code examples → Markdown blocks - Linear instructions → Numbered lists @@ -316,6 +368,7 @@ digraph when_flowchart { See @graphviz-conventions.dot for graphviz style rules. **Visualizing for your human partner:** Use `render-graphs.js` in this directory to render a skill's flowcharts to SVG: + ```bash ./render-graphs.js ../some-skill # Each diagram separately ./render-graphs.js ../some-skill --combine # All diagrams in one SVG @@ -326,11 +379,13 @@ See @graphviz-conventions.dot for graphviz style rules. **One excellent example beats many mediocre ones** Choose most relevant language: + - Testing techniques → TypeScript/JavaScript - System debugging → Shell/Python - Data processing → Python **Good example:** + - Complete and runnable - Well-commented explaining WHY - From real scenario @@ -338,6 +393,7 @@ Choose most relevant language: - Ready to adapt (not generic template) **Don't:** + - Implement in 5+ languages - Create fill-in-the-blank templates - Write contrived examples @@ -347,21 +403,26 @@ You're good at porting - one great example is enough. ## File Organization ### Self-Contained Skill + ``` defense-in-depth/ SKILL.md # Everything inline ``` + When: All content fits, no heavy reference needed ### Skill with Reusable Tool + ``` condition-based-waiting/ SKILL.md # Overview + patterns example.ts # Working helpers to adapt ``` + When: Tool is reusable code, not just narrative ### Skill with Heavy Reference + ``` pptx/ SKILL.md # Overview + workflows @@ -369,6 +430,7 @@ pptx/ ooxml.md # 500 lines XML structure scripts/ # Executable tools ``` + When: Reference material too large for inline ## The Iron Law (Same as TDD) @@ -383,6 +445,7 @@ Write skill before testing? Delete it. Start over. Edit skill without testing? Same violation. **No exceptions:** + - Not for "simple additions" - Not for "just adding a section" - Not for "documentation updates" @@ -401,6 +464,7 @@ Different skill types need different test approaches: **Examples:** TDD, verification-before-completion, designing-before-coding **Test with:** + - Academic questions: Do they understand the rules? - Pressure scenarios: Do they comply under stress? - Multiple pressures combined: time + sunk cost + exhaustion @@ -413,6 +477,7 @@ Different skill types need different test approaches: **Examples:** condition-based-waiting, root-cause-tracing, defensive-programming **Test with:** + - Application scenarios: Can they apply the technique correctly? - Variation scenarios: Do they handle edge cases? - Missing information tests: Do instructions have gaps? @@ -424,6 +489,7 @@ Different skill types need different test approaches: **Examples:** reducing-complexity, information-hiding concepts **Test with:** + - Recognition scenarios: Do they recognize when pattern applies? - Application scenarios: Can they use the mental model? - Counter-examples: Do they know when NOT to apply? @@ -435,6 +501,7 @@ Different skill types need different test approaches: **Examples:** API documentation, command references, library guides **Test with:** + - Retrieval scenarios: Can they find the right information? - Application scenarios: Can they use what they found correctly? - Gap testing: Are common use cases covered? @@ -443,16 +510,16 @@ Different skill types need different test approaches: ## Common Rationalizations for Skipping Testing -| Excuse | Reality | -|--------|---------| -| "Skill is obviously clear" | Clear to you ≠ clear to other agents. Test it. | -| "It's just a reference" | References can have gaps, unclear sections. Test retrieval. | -| "Testing is overkill" | Untested skills have issues. Always. 15 min testing saves hours. | -| "I'll test if problems emerge" | Problems = agents can't use skill. Test BEFORE deploying. | -| "Too tedious to test" | Testing is less tedious than debugging bad skill in production. | -| "I'm confident it's good" | Overconfidence guarantees issues. Test anyway. | -| "Academic review is enough" | Reading ≠ using. Test application scenarios. | -| "No time to test" | Deploying untested skill wastes more time fixing it later. | +| Excuse | Reality | +| ------------------------------ | ---------------------------------------------------------------- | +| "Skill is obviously clear" | Clear to you ≠ clear to other agents. Test it. | +| "It's just a reference" | References can have gaps, unclear sections. Test retrieval. | +| "Testing is overkill" | Untested skills have issues. Always. 15 min testing saves hours. | +| "I'll test if problems emerge" | Problems = agents can't use skill. Test BEFORE deploying. | +| "Too tedious to test" | Testing is less tedious than debugging bad skill in production. | +| "I'm confident it's good" | Overconfidence guarantees issues. Test anyway. | +| "Academic review is enough" | Reading ≠ using. Test application scenarios. | +| "No time to test" | Deploying untested skill wastes more time fixing it later. | **All of these mean: Test before deploying. No exceptions.** @@ -477,11 +544,13 @@ Write code before test? Delete it. Write code before test? Delete it. Start over. **No exceptions:** + - Don't keep it as "reference" - Don't "adapt" it while writing tests - Don't look at it - Delete means delete -``` + +```` ### Address "Spirit vs Letter" Arguments @@ -490,7 +559,7 @@ Add foundational principle early: ```markdown **Violating the letter of the rules is violating the spirit of the rules.** -``` +```` This cuts off entire class of "I'm following the spirit" rationalizations. @@ -499,10 +568,10 @@ This cuts off entire class of "I'm following the spirit" rationalizations. Capture rationalizations from baseline testing (see Testing section below). Every excuse agents make goes in the table: ```markdown -| Excuse | Reality | -|--------|---------| -| "Too simple to test" | Simple code breaks. Test takes 30 seconds. | -| "I'll test after" | Tests passing immediately prove nothing. | +| Excuse | Reality | +| -------------------------------- | ----------------------------------------------------------------------- | +| "Too simple to test" | Simple code breaks. Test takes 30 seconds. | +| "I'll test after" | Tests passing immediately prove nothing. | | "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" | ``` @@ -537,6 +606,7 @@ Follow the TDD cycle: ### RED: Write Failing Test (Baseline) Run pressure scenario with subagent WITHOUT the skill. Document exact behavior: + - What choices did they make? - What rationalizations did they use (verbatim)? - Which pressures triggered violations? @@ -554,6 +624,7 @@ Run same scenarios WITH skill. Agent should now comply. Agent found new rationalization? Add explicit counter. Re-test until bulletproof. **Testing methodology:** See @testing-skills-with-subagents.md for the complete testing methodology: + - How to write pressure scenarios - Pressure types (time, sunk cost, authority, exhaustion) - Plugging holes systematically @@ -562,21 +633,26 @@ Agent found new rationalization? Add explicit counter. Re-test until bulletproof ## Anti-Patterns ### ❌ Narrative Example + "In session 2025-10-03, we found empty projectDir caused..." **Why bad:** Too specific, not reusable ### ❌ Multi-Language Dilution + example-js.js, example-py.py, example-go.go **Why bad:** Mediocre quality, maintenance burden ### ❌ Code in Flowcharts + ```dot step1 [label="import fs"]; step2 [label="read file"]; ``` + **Why bad:** Can't copy-paste, hard to read ### ❌ Generic Labels + helper1, helper2, step3, pattern4 **Why bad:** Labels should have semantic meaning @@ -585,6 +661,7 @@ helper1, helper2, step3, pattern4 **After writing ANY skill, you MUST STOP and complete the deployment process.** **Do NOT:** + - Create multiple skills in batch without testing each - Move to next skill before current one is verified - Skip testing because "batching is more efficient" @@ -598,11 +675,13 @@ Deploying untested skills = deploying untested code. It's a violation of quality **IMPORTANT: Use TodoWrite to create todos for EACH checklist item below.** **RED Phase - Write Failing Test:** + - [ ] Create pressure scenarios (3+ combined pressures for discipline skills) - [ ] Run scenarios WITHOUT skill - document baseline behavior verbatim - [ ] Identify patterns in rationalizations/failures **GREEN Phase - Write Minimal Skill:** + - [ ] Name uses only letters, numbers, hyphens (no parentheses/special chars) - [ ] YAML frontmatter with only name and description (max 1024 chars) - [ ] Description starts with "Use when..." and includes specific triggers/symptoms @@ -615,6 +694,7 @@ Deploying untested skills = deploying untested code. It's a violation of quality - [ ] Run scenarios WITH skill - verify agents now comply **REFACTOR Phase - Close Loopholes:** + - [ ] Identify NEW rationalizations from testing - [ ] Add explicit counters (if discipline skill) - [ ] Build rationalization table from all test iterations @@ -622,6 +702,7 @@ Deploying untested skills = deploying untested code. It's a violation of quality - [ ] Re-test until bulletproof **Quality Checks:** + - [ ] Small flowchart only if decision non-obvious - [ ] Quick reference table - [ ] Common mistakes section @@ -629,6 +710,7 @@ Deploying untested skills = deploying untested code. It's a violation of quality - [ ] Supporting files only for tools or heavy reference **Deployment:** + - [ ] Commit skill to git and push to your fork (if configured) - [ ] Consider contributing back via PR (if broadly useful) @@ -637,10 +719,10 @@ Deploying untested skills = deploying untested code. It's a violation of quality How future Claude finds your skill: 1. **Encounters problem** ("tests are flaky") -3. **Finds SKILL** (description matches) -4. **Scans overview** (is this relevant?) -5. **Reads patterns** (quick reference table) -6. **Loads example** (only when implementing) +2. **Finds SKILL** (description matches) +3. **Scans overview** (is this relevant?) +4. **Reads patterns** (quick reference table) +5. **Loads example** (only when implementing) **Optimize for this flow** - put searchable terms early and often. diff --git a/skills_index.json b/skills_index.json index fe835543..f6b1b8eb 100644 --- a/skills_index.json +++ b/skills_index.json @@ -412,5 +412,17 @@ "path": "skills/github-workflow-automation", "name": "github-workflow-automation", "description": "Automate GitHub workflows with AI assistance. Includes PR reviews, issue triage, CI/CD integration, and Git operations. Use when automating GitHub workflows, setting up PR review automation, creating GitHub Actions, or triaging issues." + }, + { + "id": "address-github-comments", + "path": "skills/address-github-comments", + "name": "address-github-comments", + "description": "Use when you need to address review or issue comments on an open GitHub Pull Request using the gh CLI." + }, + { + "id": "concise-planning", + "path": "skills/concise-planning", + "name": "concise-planning", + "description": "Use when a user asks for a plan for a coding task, to generate a clear, actionable, and atomic checklist." } ]