Showing preview only (1,066K chars total). Download the full file or copy to clipboard to get everything.
Repository: luongnv89/claude-howto
Branch: main
Commit: d41b335cbc40
Files: 153
Total size: 1015.3 KB
Directory structure:
gitextract_4pfp0y5z/
├── .cspell.json
├── .github/
│ ├── FUNDING.yml
│ ├── ISSUE_TEMPLATE/
│ │ ├── bug_report.md
│ │ ├── config.yml
│ │ ├── documentation.md
│ │ ├── feature_request.md
│ │ └── question.md
│ ├── SECURITY_REPORTING.md
│ ├── TESTING.md
│ ├── markdown-link-check-config.json
│ ├── pull_request_template.md
│ └── workflows/
│ ├── ci.yml
│ ├── docs-check.yml
│ ├── release.yml
│ └── test.yml
├── .gitignore
├── .pre-commit-config.yaml
├── 01-slash-commands/
│ ├── README.md
│ ├── commit.md
│ ├── doc-refactor.md
│ ├── generate-api-docs.md
│ ├── optimize.md
│ ├── pr.md
│ ├── push-all.md
│ ├── setup-ci-cd.md
│ └── unit-test-expand.md
├── 02-memory/
│ ├── README.md
│ ├── directory-api-CLAUDE.md
│ ├── personal-CLAUDE.md
│ └── project-CLAUDE.md
├── 03-skills/
│ ├── .gitignore
│ ├── README.md
│ ├── blog-draft/
│ │ ├── SKILL.md
│ │ └── templates/
│ │ ├── draft-template.md
│ │ └── outline-template.md
│ ├── brand-voice/
│ │ ├── SKILL.md
│ │ ├── templates/
│ │ │ ├── email-template.txt
│ │ │ └── social-post-template.txt
│ │ └── tone-examples.md
│ ├── claude-md/
│ │ └── SKILL.md
│ ├── code-review/
│ │ ├── SKILL.md
│ │ ├── scripts/
│ │ │ ├── analyze-metrics.py
│ │ │ └── compare-complexity.py
│ │ └── templates/
│ │ ├── finding-template.md
│ │ └── review-checklist.md
│ ├── doc-generator/
│ │ ├── SKILL.md
│ │ └── generate-docs.py
│ └── refactor/
│ ├── SKILL.md
│ ├── references/
│ │ ├── code-smells.md
│ │ └── refactoring-catalog.md
│ ├── scripts/
│ │ ├── analyze-complexity.py
│ │ └── detect-smells.py
│ └── templates/
│ └── refactoring-plan.md
├── 04-subagents/
│ ├── README.md
│ ├── clean-code-reviewer.md
│ ├── code-reviewer.md
│ ├── data-scientist.md
│ ├── debugger.md
│ ├── documentation-writer.md
│ ├── implementation-agent.md
│ ├── secure-reviewer.md
│ └── test-engineer.md
├── 05-mcp/
│ ├── README.md
│ ├── database-mcp.json
│ ├── filesystem-mcp.json
│ ├── github-mcp.json
│ └── multi-mcp.json
├── 06-hooks/
│ ├── README.md
│ ├── auto-adapt-mode.py
│ ├── context-tracker-tiktoken.py
│ ├── context-tracker.py
│ ├── format-code.sh
│ ├── log-bash.sh
│ ├── notify-team.sh
│ ├── pre-commit.sh
│ ├── security-scan.sh
│ └── validate-prompt.sh
├── 07-plugins/
│ ├── README.md
│ ├── devops-automation/
│ │ ├── .claude-plugin/
│ │ │ └── plugin.json
│ │ ├── README.md
│ │ ├── agents/
│ │ │ ├── alert-analyzer.md
│ │ │ ├── deployment-specialist.md
│ │ │ └── incident-commander.md
│ │ ├── commands/
│ │ │ ├── deploy.md
│ │ │ ├── incident.md
│ │ │ ├── rollback.md
│ │ │ └── status.md
│ │ ├── hooks/
│ │ │ ├── post-deploy.js
│ │ │ └── pre-deploy.js
│ │ ├── mcp/
│ │ │ └── kubernetes-config.json
│ │ └── scripts/
│ │ ├── deploy.sh
│ │ ├── health-check.sh
│ │ └── rollback.sh
│ ├── documentation/
│ │ ├── .claude-plugin/
│ │ │ └── plugin.json
│ │ ├── README.md
│ │ ├── agents/
│ │ │ ├── api-documenter.md
│ │ │ ├── code-commentator.md
│ │ │ └── example-generator.md
│ │ ├── commands/
│ │ │ ├── generate-api-docs.md
│ │ │ ├── generate-readme.md
│ │ │ ├── sync-docs.md
│ │ │ └── validate-docs.md
│ │ ├── mcp/
│ │ │ └── github-docs-config.json
│ │ └── templates/
│ │ ├── adr-template.md
│ │ ├── api-endpoint.md
│ │ └── function-docs.md
│ └── pr-review/
│ ├── .claude-plugin/
│ │ └── plugin.json
│ ├── README.md
│ ├── agents/
│ │ ├── performance-analyzer.md
│ │ ├── security-reviewer.md
│ │ └── test-checker.md
│ ├── commands/
│ │ ├── check-security.md
│ │ ├── check-tests.md
│ │ └── review-pr.md
│ ├── hooks/
│ │ └── pre-review.js
│ └── mcp/
│ └── github-config.json
├── 08-checkpoints/
│ ├── README.md
│ └── checkpoint-examples.md
├── 09-advanced-features/
│ ├── README.md
│ ├── config-examples.json
│ └── planning-mode-examples.md
├── 10-cli/
│ └── README.md
├── CATALOG.md
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── INDEX.md
├── LEARNING-ROADMAP.md
├── LICENSE
├── QUICK_REFERENCE.md
├── README.backup.md
├── README.md
├── RELEASE_NOTES.md
├── SECURITY.md
├── STYLE_GUIDE.md
├── claude_concepts_guide.md
├── clean-code-rules.md
├── coverage.xml
├── prompts/
│ └── remotion-video.md
├── resources/
│ ├── DESIGN-SYSTEM.md
│ ├── INDEX.txt
│ ├── MANIFEST.txt
│ ├── QUICK-START.md
│ └── README.md
├── resources.md
└── scripts/
├── README.md
├── build_epub.py
├── pyproject.toml
├── requirements-dev.txt
├── requirements.txt
└── tests/
├── __init__.py
├── conftest.py
└── test_build_epub.py
================================================
FILE CONTENTS
================================================
================================================
FILE: .cspell.json
================================================
{
"version": "0.2",
"language": "en",
"words": [
"claude",
"Claude",
"Anthropic",
"subagent",
"subagents",
"CLAUDE",
"MCP",
"Mermaid",
"frontmatter",
"pre-commit",
"Ruff",
"Bandit",
"EPUB",
"Sonnet",
"Opus",
"Haiku",
"luongnv89",
"claude-howto",
"ModelContextProtocol",
"YAML",
"JSON",
"API",
"DevOps",
"CRUD",
"CLI",
"SSH",
"HTTP",
"HTTPS",
"AWS",
"GitHub",
"GitLab",
"MongoDB",
"PostgreSQL",
"SQLite",
"Redis",
"JWT",
"OAuth",
"CORS",
"REST",
"GraphQL",
"TypeScript",
"JavaScript",
"Python",
"Bash",
"Unix",
"Linux",
"macOS",
"Windows",
"PowerShell",
"VSCode",
"IDE",
"MCP",
"Checks",
"checkpoints",
"THINKING",
"Headless",
"Headless mode",
"Kyrie",
"subprocesses",
"subprocess",
"checklist",
"checklists",
"customizable",
"customization",
"delegated",
"delegating",
"permissioning",
"GOPATH",
"goToDefinition",
"outgoingCalls",
"incomingCalls",
"docstring",
"docstrings",
"EOSMTP",
"OPENSPEC",
"Markdown",
"realtime",
"real-time",
"refactoring",
"runtime",
"namespace",
"namespacing",
"linting",
"pytest",
"Pytest",
"telemetry",
"caching",
"HTTPS",
"repo",
"repos",
"readme",
"README",
"mypy",
"wjhrdy",
"BigQuery",
"Sentry",
"bcherny",
"autoCheckpoint",
"autoEnter",
"backgroundTasks",
"extendedThinking",
"maxConcurrentTasks",
"PostCommit",
"PostToolUse",
"PreCommit",
"PrePush",
"PreToolUse",
"CODEOWNERS",
"PyPI",
"CVSS",
"CWE",
"OWASP",
"unrecognized",
"Dependabot",
"Codecov",
"codecov",
"pytest",
"anyio",
"asyncio",
"beautifulsoup",
"ebooklib",
"httpx",
"pillow",
"tenacity",
"cSpell",
"markdownlint",
"Kroki",
"setuptools",
"configurability",
"proactively",
"Kyrie",
"ChatGPT",
"GPT",
"Claude",
"Anthropic",
"OpenAI",
"subagent",
"emoji",
"emojis",
"reusable",
"scalability",
"latency",
"throughput",
"middleware",
"backend",
"frontend",
"middleware",
"templating",
"templated",
"serialization",
"deserialization",
"polymorphism",
"refactor",
"refactoring",
"refactored",
"reproducible",
"deterministic",
"probabilistic",
"hardcoded",
"tradeoff",
"tradeoffs",
"monorepo",
"monorepositories",
"idempotent",
"idempotence",
"mutable",
"immutable",
"invariant",
"invariants",
"docstring",
"docstrings",
"boilerplate",
"scaffolding",
"middleware",
"plugin",
"plugins",
"middleware",
"precommit",
"commitments",
"filesystem",
"subprocess",
"subprocesses",
"multiprocessing",
"Zod",
"zod",
"OpenAPI",
"RESTful",
"CRUD",
"SOLID",
"DRY",
"YAGNI",
"KISS",
"BATHWATER",
"scalable",
"configurable",
"maintainable",
"reliable",
"performant",
"resilient",
"idempotent",
"interoperable",
"composable",
"extensible",
"srcset",
"overcomplicate",
"Asana",
"oneline",
"anthropics",
"worktree",
"worktrees",
"dontAsk",
"VikalpP",
"sandboxed",
"Sandboxing",
"pycache",
"inlines",
"pyproject",
"Spawnable",
"spawnable",
"agentic",
"Ghostty",
"Backgrounding",
"AUTOCOMPACT",
"reconnections",
"CLAUDEAI",
"blocklist",
"Blocklist",
"mcporter",
"SESSIONEND",
"tiktoken",
"gopls",
"pyright",
"langserver",
"rustup",
"Lockdown",
"Checkpointing",
"opusplan",
"ultrathink",
"spacebar",
"MSIX",
"NONSTREAMING",
"startswith",
"unparse"
],
"ignoreWords": [
"luongnv89",
"wjhrdy",
"Cherry",
"Boris",
"Cherny's"
],
"ignoreRegExpList": [
"code\\{[^}]*\\}",
"```[\\s\\S]*?```"
],
"overrides": [
{
"filename": "**/*.md",
"words": [
"commandline",
"cmd"
]
}
]
}
================================================
FILE: .github/FUNDING.yml
================================================
# These are supported funding model platforms
github: [luongnv89] # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
buy_me_a_coffee: luongnv89 # Replace with a single Buy Me a Coffee username
================================================
FILE: .github/ISSUE_TEMPLATE/bug_report.md
================================================
---
name: Bug Report
about: Report an issue with an example, guide, or documentation
title: "[BUG] "
labels: bug
assignees: ''
---
## Description
Brief description of the issue.
## Steps to Reproduce
1. Step 1
2. Step 2
3. Step 3
## Expected Behavior
What should happen?
## Actual Behavior
What actually happened?
## Environment
- **Claude Code Version**: (e.g., 1.0.5)
- **Operating System**: (e.g., macOS 14.1, Ubuntu 22.04, Windows 11)
- **Python Version**: (if relevant, e.g., 3.11)
- **Affected Component**: (e.g., 01-slash-commands, 03-skills, etc.)
## Example Code
If applicable, provide the example code that's not working:
```
[Insert code here]
```
## Screenshots
If applicable, add screenshots showing the issue.
## Additional Context
Any other context that might help us understand the issue?
## Possible Solution
If you have a suggestion for fixing this, share it here.
================================================
FILE: .github/ISSUE_TEMPLATE/config.yml
================================================
blank_issues_enabled: false
contact_links:
- name: Claude Code Documentation
url: https://code.claude.com/docs/en/overview
about: Official Claude Code documentation
- name: Discussions
url: https://github.com/luongnv89/claude-howto/discussions
about: Ask questions and share ideas with the community
- name: Anthropic Cookbook
url: https://github.com/anthropics/anthropic-cookbook
about: Official examples and guides from Anthropic
================================================
FILE: .github/ISSUE_TEMPLATE/documentation.md
================================================
---
name: Documentation Issue
about: Report unclear documentation, typos, or missing information
title: "[DOCS] "
labels: documentation
assignees: ''
---
## Type of Issue
- [ ] Typo or grammar error
- [ ] Unclear explanation
- [ ] Missing information
- [ ] Broken link or reference
- [ ] Outdated content
- [ ] Better example needed
## Location
Which section has the issue?
- **File**: (e.g., README.md, 03-skills/README.md)
- **Section**: (e.g., "Installation Quick Reference")
- **Line/Area**: (if specific)
## Current Content
What does it currently say?
```
[Paste the current text here]
```
## Issue Description
What's wrong with it?
## Suggested Improvement
How could this be improved or clarified?
```
[Provide improved text or suggestion here]
```
## Why This Matters
How does this issue impact users?
## Related Documentation
Links to related sections:
- Related Guide: <!-- Add link here -->
================================================
FILE: .github/ISSUE_TEMPLATE/feature_request.md
================================================
---
name: Feature Request
about: Suggest a new example, guide, or improvement
title: "[FEATURE] "
labels: enhancement
assignees: ''
---
## Description
Describe the feature or improvement you'd like to see.
## Problem It Solves
What problem or gap does this address?
Examples:
- There's no example of X feature
- The current documentation for Y is unclear
- We need a guide for Z use case
- The structure could be improved by...
## Use Case
When and how would this be used? Include real-world scenarios.
## Proposed Solution
How should this be implemented or documented?
## Example
If applicable, provide an example of what you envision:
```
[Insert example here]
```
## Related Examples
Link any existing related examples or guides:
- Existing Guide: <!-- Add link here -->
- Feature: (e.g., Skills, Hooks, Subagents)
## Additional Context
Any other information that might be helpful?
## Acceptance Criteria
How would you know this feature is complete?
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3
================================================
FILE: .github/ISSUE_TEMPLATE/question.md
================================================
---
name: Question
about: Ask a question about Claude Code or this guide
title: "[QUESTION] "
labels: question
assignees: ''
---
## Question
What would you like to know?
## Context
Provide some background or context for your question:
- What are you trying to do?
- What have you already tried?
- What examples or guides have you looked at?
## Relevant Topic
Which topic is this related to?
- [ ] Slash Commands
- [ ] Memory
- [ ] Skills
- [ ] Subagents
- [ ] MCP Protocol
- [ ] Hooks
- [ ] Plugins
- [ ] Checkpoints
- [ ] Advanced Features
- [ ] CLI Reference
- [ ] Other
## What You've Tried
Have you already tried anything? What was the result?
## Expected Outcome
What would help you solve this?
## Additional Resources
Any links or resources that might be relevant?
================================================
FILE: .github/SECURITY_REPORTING.md
================================================
# Security Vulnerability Reporting
This file explains how to report security vulnerabilities to the Claude How To project.
## Quick Links
- **Private Reporting**: https://github.com/luongnv89/claude-howto/security/advisories
- **Security Policy**: [SECURITY.md](../SECURITY.md)
- **Report Template**: See below
## Report a Vulnerability
### Option 1: GitHub Private Vulnerability Report (RECOMMENDED)
This is the preferred method for reporting security vulnerabilities.
**Steps:**
1. Go to: https://github.com/luongnv89/claude-howto/security/advisories
2. Click "Report a vulnerability"
3. Fill in the details (use template below)
4. Submit
**Advantages:**
- Keeps vulnerability private until fix is released
- Automatic notifications to maintainers
- Built-in collaboration features
- Integrated with GitHub security tools
### Option 2: GitHub Security Alert (For Dependencies)
If you discover a vulnerability in a dependency:
1. Go to: https://github.com/luongnv89/claude-howto/security/dependabot/alerts
2. Review the alert
3. Create a pull request with the fix
4. Tag with `security` label
### Option 3: Private Email (If GitHub unavailable)
If you cannot use GitHub's reporting system:
**Coming soon**: Security contact email will be added here
For now, use GitHub's private vulnerability reporting as described above.
## Vulnerability Report Template
Use this template when reporting a vulnerability:
```
**Title**: [Brief description of vulnerability]
**Severity**: [Critical/High/Medium/Low]
Estimated CVSS Score: [0-10]
**Type**: [Code/Documentation/Dependency/Configuration]
**Affected Component**:
- File: [path/to/file.py]
- Section: [Section name if documentation]
- Version: [latest/specific version]
**Description**:
[Clear explanation of what the vulnerability is]
**Potential Impact**:
[What could an attacker do with this vulnerability?]
[Who could be affected?]
**Steps to Reproduce**:
1. [First step]
2. [Second step]
3. [Third step]
[Expected result vs actual result]
**Proof of Concept** (if available):
[Code or steps to demonstrate the vulnerability]
**Suggested Fix**:
[Your recommended solution, if you have one]
**Additional Context**:
[Any other relevant information]
**Your Information**:
- Name: [Your name or anonymous]
- Email: [Your email]
- Credit: [How you'd like to be credited, if at all]
```
## What Happens After You Report
### Timeline
1. **Immediate (< 1 hour)**
- Automatic notification sent to project maintainers
2. **Within 24 hours**
- Initial assessment of the report
- Confirmation that we received it
- Preliminary severity assessment
3. **Within 48 hours**
- Detailed response from security team
- Questions for clarification (if needed)
- Timeline for fix (if vulnerability confirmed)
4. **Within 1-7 days** (depends on severity)
- Fix developed and tested
- Security advisory prepared
- Fix released and public advisory published
### Communication
We will keep you informed through:
- GitHub private vulnerability discussion
- Email (if provided)
- Updates in the discussion thread
You can:
- Ask clarifying questions
- Provide additional information
- Suggest improvements to the fix
- Request timeline adjustments
### Disclosure Timeline
**Critical Issues (CVSS 9.0-10.0)**
- Fix: Released immediately (within 24 hours)
- Disclosure: Public advisory issued same day
- Notice: 24 hours advance notice to reporter
**High Issues (CVSS 7.0-8.9)**
- Fix: Released within 48-72 hours
- Disclosure: Public advisory on release
- Notice: 5 days advance notice to reporter
**Medium Issues (CVSS 4.0-6.9)**
- Fix: Included in next regular update
- Disclosure: Public advisory on release
- Notice: Coordinated timing
**Low Issues (CVSS 0.1-3.9)**
- Fix: Included in next regular update
- Disclosure: Advisory on release
- Notice: Same day as release
## Security Vulnerability Criteria
### In Scope
We accept reports on:
- **Code Vulnerabilities**
- Injection attacks (command, SQL, etc.)
- Cross-site scripting (XSS) in examples
- Authentication/authorization flaws
- Path traversal vulnerabilities
- Cryptography issues
- **Documentation Security**
- Exposed secrets or credentials
- Insecure code patterns
- Security anti-patterns
- Misleading security claims
- **Dependency Vulnerabilities**
- Known CVEs in dependencies
- Supply chain attacks
- Malicious dependencies
- **Configuration Issues**
- Insecure defaults
- Missing security headers
- Credential exposure in examples
### Out of Scope
We do NOT accept reports on:
- Vulnerabilities in Claude Code itself (contact Anthropic)
- Vulnerabilities in external services
- Theoretical vulnerabilities without proof
- Issues already reported to upstream projects
- Social engineering or phishing
- User education/training issues
## Responsible Disclosure Guidelines
### Do's ✅
- **Report privately** before public disclosure
- **Be specific** with file paths and line numbers
- **Provide proof** of the vulnerability
- **Give us time** to fix (coordinated disclosure)
- **Update** if you discover more details
- **Be professional** in all communications
- **Respect confidentiality** until we publish
### Don'ts ❌
- **Don't publicly disclose** before we fix
- **Don't exploit** the vulnerability beyond testing
- **Don't modify** other users' data
- **Don't demand** payment or favors
- **Don't share** the vulnerability with others
- **Don't use** it in any harmful way
- **Don't spam** with non-security related issues
## Coordinated Disclosure
We practice responsible disclosure:
1. **Private Report**: You report to us privately
2. **Our Assessment**: We evaluate and assess severity
3. **Fix Development**: We develop and test a fix
4. **Advance Notice**: We give you advance notice before public disclosure
5. **Public Release**: We release fix and advisory together
6. **Your Credit**: We acknowledge your contribution (if desired)
**Timeline varies based on severity** (see section above)
## After the Fix is Released
### Public Advisory
A public security advisory will include:
- Description of the vulnerability
- Affected versions
- Severity (CVSS score)
- Steps to remediate
- Link to the fix
- Credit to reporter (with permission)
### Your Recognition
If you wish to be credited:
- Your name/handle in the advisory
- Link to your profile/website
- Mention in release notes
- Addition to hall of fame (if created)
### No Compensation
Please note:
- This is a volunteer-run open-source project
- We cannot offer financial rewards
- We do offer recognition and credit
- Your contribution helps the community
## Security Research
If you're conducting security research:
1. **Get Permission**: Contact maintainers first
2. **Define Scope**: Agree on what you'll test
3. **Report Findings**: Use this process
4. **Respect Timeline**: Allow time for fixes
5. **Publish Responsibly**: Coordinate with us
## Questions?
For questions about this process:
1. Check [SECURITY.md](../SECURITY.md) for detailed policy
2. Look at [FAQ](#faq) section below
3. Open a discussion with `[SECURITY]` label
4. Use private vulnerability reporting for sensitive questions
## FAQ
**Q: Will my report be kept confidential?**
A: Yes, until the fix is released. We only share details with those working on the fix.
**Q: How long do I need to wait before public disclosure?**
A: We follow responsible disclosure timelines based on severity (24 hours to 7 days). You can agree to extend this if needed.
**Q: Will I get credit?**
A: Yes, in the security advisory and release notes (unless you prefer anonymity).
**Q: What if the vulnerability is minor?**
A: All legitimate security issues are taken seriously. Even minor fixes will be acknowledged.
**Q: Can I report vulnerabilities in documentation only?**
A: Yes! Documentation security is important too. Examples with insecure patterns are in scope.
**Q: What if I'm not sure if something is a security issue?**
A: Report it anyway! If it's not a security issue, we'll let you know. False positives are fine.
**Q: Can I publicly discuss the vulnerability after reporting?**
A: No, please keep it private until we publish the advisory. Premature disclosure could put users at risk.
**Q: How do I know you received my report?**
A: GitHub will send an automatic notification, and we'll follow up within 24 hours.
**Q: What if I don't hear back?**
A: Check GitHub security advisories page. If you still don't see a response, you can follow up with a comment on the private report.
## Resources
- [SECURITY.md](../SECURITY.md) - Full security policy
- [CONTRIBUTING.md](../CONTRIBUTING.md) - Contributing guidelines
- [CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md) - Community standards
- [OWASP Vulnerability Disclosure](https://cheatsheetseries.owasp.org/cheatsheets/Vulnerability_Disclosure_Cheat_Sheet.html) - Responsible disclosure best practices
- [Coordinated Vulnerability Disclosure](https://cheatsheetseries.owasp.org/cheatsheets/Vulnerable_Dependency_Management_Cheat_Sheet.html)
---
Thank you for helping keep this project secure! 🔒
================================================
FILE: .github/TESTING.md
================================================
# Testing Guide
This document describes the testing infrastructure for Claude How To.
## Overview
The project uses GitHub Actions to automatically run tests on every push and pull request. Tests cover:
- **Unit Tests**: Python tests using pytest
- **Code Quality**: Linting and formatting with Ruff
- **Security**: Vulnerability scanning with Bandit
- **Type Checking**: Static type analysis with mypy
- **Build Verification**: EPUB generation test
## Running Tests Locally
### Prerequisites
```bash
# Install uv (fast Python package manager)
pip install uv
# Or on macOS with Homebrew
brew install uv
```
### Setup Environment
```bash
# Clone the repository
git clone https://github.com/luongnv89/claude-howto.git
cd claude-howto
# Create virtual environment
uv venv
# Activate it
source .venv/bin/activate # macOS/Linux
# or
.venv\Scripts\activate # Windows
# Install development dependencies
uv pip install -r requirements-dev.txt
```
### Run Tests
```bash
# Run all unit tests
pytest scripts/tests/ -v
# Run tests with coverage
pytest scripts/tests/ -v --cov=scripts --cov-report=html
# Run specific test file
pytest scripts/tests/test_build_epub.py -v
# Run specific test function
pytest scripts/tests/test_build_epub.py::test_function_name -v
# Run tests in watch mode (requires pytest-watch)
ptw scripts/tests/
```
### Run Linting
```bash
# Check code formatting
ruff format --check scripts/
# Auto-fix formatting issues
ruff format scripts/
# Run linter
ruff check scripts/
# Auto-fix linter issues
ruff check --fix scripts/
```
### Run Security Scan
```bash
# Run Bandit security scan
bandit -c pyproject.toml -r scripts/ --exclude scripts/tests/
# Generate JSON report
bandit -c pyproject.toml -r scripts/ --exclude scripts/tests/ -f json -o bandit-report.json
```
### Run Type Checking
```bash
# Check types with mypy
mypy scripts/ --ignore-missing-imports --no-implicit-optional
```
## GitHub Actions Workflow
### Triggered On
- **Push** to `main` or `develop` branches (when scripts change)
- **Pull Request** to `main` (when scripts change)
- Manual workflow dispatch
### Jobs
#### 1. Unit Tests (pytest)
- **Runs on**: Ubuntu latest
- **Python versions**: 3.10, 3.11, 3.12
- **What it does**:
- Installs dependencies from `requirements-dev.txt`
- Runs pytest with coverage reporting
- Uploads coverage to Codecov
- Archives test results and coverage HTML
**Outcome**: If any test fails, the workflow fails (critical)
#### 2. Code Quality (Ruff)
- **Runs on**: Ubuntu latest
- **Python version**: 3.11
- **What it does**:
- Checks code formatting with `ruff format`
- Runs linter with `ruff check`
- Reports issues but doesn't fail the workflow
**Outcome**: Non-blocking (warning only)
#### 3. Security Scan (Bandit)
- **Runs on**: Ubuntu latest
- **Python version**: 3.11
- **What it does**:
- Scans for security vulnerabilities
- Generates JSON report
- Uploads report as artifact
**Outcome**: Non-blocking (warning only)
#### 4. Type Checking (mypy)
- **Runs on**: Ubuntu latest
- **Python version**: 3.11
- **What it does**:
- Performs static type analysis
- Reports type mismatches
- Helps catch bugs early
**Outcome**: Non-blocking (warning only)
#### 5. Build EPUB
- **Runs on**: Ubuntu latest
- **Depends on**: pytest, lint, security (all must pass)
- **What it does**:
- Builds the EPUB file using `scripts/build_epub.py`
- Verifies the EPUB was created successfully
- Uploads EPUB as artifact
**Outcome**: If build fails, the workflow fails (critical)
#### 6. Summary
- **Runs on**: Ubuntu latest
- **Depends on**: All other jobs
- **What it does**:
- Generates workflow summary
- Lists all artifacts
- Reports overall status
## Writing Tests
### Test Structure
Tests should be placed in `scripts/tests/` with names like `test_*.py`:
```python
# scripts/tests/test_example.py
import pytest
from scripts.example_module import some_function
def test_basic_functionality():
"""Test that some_function works correctly."""
result = some_function("input")
assert result == "expected_output"
def test_error_handling():
"""Test that some_function handles errors gracefully."""
with pytest.raises(ValueError):
some_function("invalid_input")
@pytest.mark.asyncio
async def test_async_function():
"""Test async functions."""
result = await async_function()
assert result is not None
```
### Test Best Practices
- **Use descriptive names**: `test_function_returns_correct_value()`
- **One assertion per test** (when possible): Easier to debug failures
- **Use fixtures** for reusable setup: See `scripts/tests/conftest.py`
- **Mock external services**: Use `unittest.mock` or `pytest-mock`
- **Test edge cases**: Empty inputs, None values, errors
- **Keep tests fast**: Avoid sleep() and external I/O
- **Use pytest markers**: `@pytest.mark.slow` for slow tests
### Fixtures
Common fixtures are defined in `scripts/tests/conftest.py`:
```python
# Use fixtures in your tests
def test_something(tmp_path):
"""tmp_path fixture provides temporary directory."""
test_file = tmp_path / "test.txt"
test_file.write_text("content")
assert test_file.read_text() == "content"
```
## Coverage Reports
### Local Coverage
```bash
# Generate coverage report
pytest scripts/tests/ --cov=scripts --cov-report=html
# Open the coverage report in your browser
open htmlcov/index.html
```
### Coverage Goals
- **Minimum coverage**: 80%
- **Branch coverage**: Enabled
- **Focus areas**: Core functionality and error paths
## Pre-commit Hooks
The project uses pre-commit hooks to run checks automatically before commits:
```bash
# Install pre-commit hooks
pre-commit install
# Run hooks manually
pre-commit run --all-files
# Skip hooks for a commit (not recommended)
git commit --no-verify
```
Configured hooks in `.pre-commit-config.yaml`:
- Ruff formatter
- Ruff linter
- Bandit security scanner
- YAML validation
- File size checks
- Merge conflict detection
## Troubleshooting
### Tests Pass Locally but Fail in CI
Common causes:
1. **Python version difference**: CI uses 3.10, 3.11, 3.12
2. **Missing dependencies**: Update `requirements-dev.txt`
3. **Platform differences**: Path separators, environment variables
4. **Flaky tests**: Tests that depend on timing or order
Solution:
```bash
# Test with the same Python versions
uv python install 3.10 3.11 3.12
# Test with clean environment
rm -rf .venv
uv venv
uv pip install -r requirements-dev.txt
pytest scripts/tests/
```
### Bandit Reports False Positives
Some security warnings may be false positives. Configure in `pyproject.toml`:
```toml
[tool.bandit]
exclude_dirs = ["scripts/tests"]
skips = ["B101"] # Skip assert_used warning
```
### Type Checking Too Strict
Relax type checking for specific files:
```python
# Add at the top of file
# type: ignore
# Or for specific lines
some_dynamic_code() # type: ignore
```
## Continuous Integration Best Practices
1. **Keep tests fast**: Each test should complete in <1 second
2. **Don't test external APIs**: Mock external services
3. **Test in isolation**: Each test should be independent
4. **Use clear assertions**: `assert x == 5` not `assert x`
5. **Handle async tests**: Use `@pytest.mark.asyncio`
6. **Generate reports**: Coverage, security, type checking
## Resources
- [pytest Documentation](https://docs.pytest.org/)
- [Ruff Documentation](https://docs.astral.sh/ruff/)
- [Bandit Documentation](https://bandit.readthedocs.io/)
- [mypy Documentation](https://mypy.readthedocs.io/)
- [GitHub Actions Documentation](https://docs.github.com/en/actions)
## Contributing Tests
When submitting a PR:
1. **Write tests** for new functionality
2. **Run tests locally**: `pytest scripts/tests/ -v`
3. **Check coverage**: `pytest scripts/tests/ --cov=scripts`
4. **Run linting**: `ruff check scripts/`
5. **Security scan**: `bandit -r scripts/ --exclude scripts/tests/`
6. **Update documentation** if tests change
Tests are required for all PRs! 🧪
---
For questions or issues with testing, open a GitHub issue or discussion.
================================================
FILE: .github/markdown-link-check-config.json
================================================
{
"ignorePatterns": [
{
"pattern": "^https://docs\\.example\\.com",
"comment": "Example placeholder URLs in documentation templates"
},
{
"pattern": "^\\./docs/",
"comment": "Example relative paths in documentation templates"
},
{
"pattern": "^FORMS\\.md$|^REFERENCE\\.md$",
"comment": "Example file references in skill templates"
},
{
"pattern": "^https://en\\.wikipedia\\.org/wiki/N%2B1",
"comment": "Wikipedia N+1 article - URL encoding issues"
},
{
"pattern": "^https://twitter.com",
"comment": "Twitter/X links require authentication"
},
{
"pattern": "^https://x.com",
"comment": "X (Twitter) links require authentication"
},
{
"pattern": "^https://github.com/[^/]+/claude-howto",
"comment": "Self-referencing links"
},
{
"pattern": "^https://docs\\.claude\\.com",
"comment": "Claude docs - URL structure may vary"
},
{
"pattern": "^https://docs\\.anthropic\\.com",
"comment": "Anthropic docs - May have authentication or access restrictions"
},
{
"pattern": "^https://code\\.claude\\.com",
"comment": "Claude Code docs - May have dynamic content or routing issues"
},
{
"pattern": "^https://plugins\\.claude\\.com",
"comment": "Plugin marketplace - May have access restrictions"
},
{
"pattern": "^https://medium\\.com",
"comment": "Medium posts - May have paywall or tracking restrictions"
},
{
"pattern": "^https://modelcontextprotocol\\.io",
"comment": "MCP docs - May have infrastructure limitations"
},
{
"pattern": "^https://discord\\.gg",
"comment": "Discord invite links - May expire or have access issues"
},
{
"pattern": "^https://bsky\\.app",
"comment": "BlueSky links - May require authentication"
},
{
"pattern": "^https://api\\.star-history\\.com",
"comment": "External badge service - May have rate limiting"
},
{
"pattern": "^https://jazz\\.tools",
"comment": "External tool links - May have dynamic routing"
},
{
"pattern": "^https://mcp\\.notion\\.com",
"comment": "Notion-hosted docs - May require authentication"
}
],
"replacementPatterns": [
{
"pattern": "^/",
"replacement": "https://github.com/luongnv89/claude-howto/blob/main/"
}
],
"timeout": 10000,
"retryOn": [429, 503],
"retryCount": 3,
"fallbackRetryDelay": 5000,
"aliveStatusCodes": [200, 206]
}
================================================
FILE: .github/pull_request_template.md
================================================
## Description
Brief summary of what this PR does.
## Type of Change
- [ ] New example or template
- [ ] Documentation improvement
- [ ] Bug fix
- [ ] Feature guide
- [ ] Other (please describe)
## Related Issues
Closes #(issue number)
## Changes Made
- Change 1
- Change 2
- Change 3
## What to Review
What should reviewers focus on?
## Files Changed
- `path/to/file1.md`
- `path/to/file2.md`
## Testing
How have you tested this?
- [ ] Tested locally with Claude Code
- [ ] Verified examples work
- [ ] Checked links and references
- [ ] Reviewed for typos and clarity
## Checklist
- [ ] Follows project structure and conventions
- [ ] Includes clear documentation/examples
- [ ] Code/examples are copy-paste ready
- [ ] All links are verified and working
- [ ] No sensitive information included (keys, tokens, credentials)
- [ ] Updated relevant README files
- [ ] Commit message follows conventional commit format
- [ ] No large files (>1MB) added
## Screenshots or Examples
If applicable, show what this adds:
```
[Example code or before/after comparison]
```
## Breaking Changes
Does this change any existing content or behavior?
- [ ] No breaking changes
- [ ] Yes, and it's documented below
If yes, please describe:
## Additional Notes
Any other information for reviewers?
================================================
FILE: .github/workflows/ci.yml
================================================
name: CI
on:
push:
branches: [main]
pull_request:
branches: [main]
# Cancel in-progress runs for the same branch
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
lint:
name: Lint & Format
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v4
- name: Set up Python
run: uv python install 3.11
- name: Create venv and install Ruff
run: |
uv venv
uv pip install ruff
- name: Ruff Format Check
run: uv run ruff format --check scripts/
- name: Ruff Lint Check
run: uv run ruff check scripts/
security:
name: Security Scan
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v4
- name: Set up Python
run: uv python install 3.11
- name: Create venv and install Bandit
run: |
uv venv
uv pip install "bandit[toml]"
- name: Run Bandit Security Scan
run: uv run bandit -c scripts/pyproject.toml -r scripts/ --exclude scripts/tests/
test:
name: Unit Tests (Python ${{ matrix.python-version }})
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
python-version: ['3.10', '3.11', '3.12']
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v4
- name: Set up Python ${{ matrix.python-version }}
run: uv python install ${{ matrix.python-version }}
- name: Create venv and install dependencies
run: |
uv venv
uv pip install -r scripts/requirements-dev.txt
- name: Run pytest with coverage
run: uv run pytest scripts/tests/ -v --tb=short --cov=scripts --cov-report=xml --cov-report=term-missing
- name: Upload coverage to Codecov
uses: codecov/codecov-action@v3
with:
files: ./coverage.xml
flags: unittests
name: codecov-python-${{ matrix.python-version }}
fail_ci_if_error: false
build:
name: Build EPUB
runs-on: ubuntu-latest
needs: [lint, security, test]
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v4
- name: Set up Python
run: uv python install 3.11
- name: Create venv and install dependencies
run: |
uv venv
uv pip install -r scripts/requirements-dev.txt
- name: Build EPUB
run: uv run scripts/build_epub.py
- name: Verify EPUB Created
run: |
if [ -f claude-howto-guide.epub ]; then
echo "EPUB built successfully"
ls -lh claude-howto-guide.epub
else
echo "EPUB file not found!"
exit 1
fi
- name: Upload EPUB Artifact
uses: actions/upload-artifact@v4
with:
name: claude-howto-guide-epub
path: claude-howto-guide.epub
retention-days: 7
================================================
FILE: .github/workflows/docs-check.yml
================================================
name: Documentation Checks
on:
push:
branches: [main]
paths:
- '**.md'
- '.github/workflows/docs-check.yml'
- '.cspell.json'
- '.github/markdown-link-check-config.json'
pull_request:
branches: [main]
paths:
- '**.md'
- 'CONTRIBUTING.md'
- 'LICENSE'
- '.cspell.json'
- '.github/markdown-link-check-config.json'
# Cancel in-progress runs for the same branch
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
markdown-lint:
name: Markdown Linting
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '18'
- name: Install markdownlint-cli
run: npm install -g markdownlint-cli
- name: Run Markdown Linter
run: markdownlint '**/*.md' --ignore node_modules --ignore .venv
continue-on-error: true
link-check:
name: Check Links
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Check markdown links
uses: gaurav-nelson/github-action-markdown-link-check@v1
with:
use-quiet-mode: 'yes'
use-verbose-mode: 'no'
config-file: '.github/markdown-link-check-config.json'
spelling:
name: Spell Check
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Run cSpell
uses: streetsidesoftware/cspell-action@v6
with:
files: |
**/*.md
**/*.json
**/*.yml
**/*.yaml
incremental: 'no'
config: '.cspell.json'
frontmatter:
name: YAML Frontmatter Validation
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Install PyYAML
run: pip install pyyaml
- name: Validate YAML Frontmatter
run: |
python3 << 'EOF'
import os
import yaml
import re
from pathlib import Path
errors = []
# Check all markdown files in Claude sections
md_files = list(Path('.').glob('**/README.md')) + list(Path('.').glob('01-*/**/*.md'))
for file_path in md_files:
if '.venv' in str(file_path) or 'node_modules' in str(file_path):
continue
with open(file_path, 'r') as f:
content = f.read()
# Check for YAML frontmatter in skill/agent templates
if 'SKILL.md' in str(file_path) or any(x in str(file_path) for x in ['agent', 'template']):
if content.startswith('---'):
try:
# Extract frontmatter
parts = content.split('---', 2)
if len(parts) >= 3:
yaml.safe_load(parts[1])
except yaml.YAMLError as e:
errors.append(f"{file_path}: Invalid YAML frontmatter - {e}")
else:
if 'skill' in str(file_path).lower():
print(f"⚠ {file_path}: Consider adding YAML frontmatter")
if errors:
for error in errors:
print(f"❌ {error}")
exit(1)
else:
print("✅ All YAML frontmatter is valid")
EOF
structure:
name: Documentation Structure
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Validate Documentation Structure
run: |
python3 << 'EOF'
import os
from pathlib import Path
import re
errors = []
warnings = []
# Check that all numbered directories have README.md
for i in range(1, 11):
dir_path = Path(f"{i:02d}-*")
matches = list(dir_path.parent.glob(str(dir_path)))
if matches:
for match in matches:
if (match / "README.md").exists():
print(f"✅ {match}/README.md found")
else:
errors.append(f"{match}: Missing README.md")
# Check README.md has required sections
readme_path = Path("README.md")
if readme_path.exists():
with open(readme_path) as f:
content = f.read()
required_sections = [
"## Table of Contents",
"## Contributing",
"## License",
]
for section in required_sections:
if section not in content:
errors.append(f"README.md: Missing '{section}' section")
else:
print(f"✅ README.md has '{section}' section")
# Check for broken relative links
md_files = list(Path(".").rglob("*.md"))
for file_path in md_files:
if ".venv" in str(file_path) or "node_modules" in str(file_path):
continue
with open(file_path) as f:
content = f.read()
# Find markdown links to local files
local_links = re.findall(r'\[([^\]]+)\]\(([^)]+\.md)\)', content)
for link_text, link_path in local_links:
# Skip anchor-only links
if link_path.startswith("#"):
continue
resolved_path = (file_path.parent / link_path).resolve()
if not resolved_path.exists():
warnings.append(f"{file_path}: Broken link to '{link_path}'")
if errors:
print("\n❌ Validation Errors:")
for error in errors:
print(f" - {error}")
exit(1)
if warnings:
print("\n⚠ Warnings:")
for warning in warnings:
print(f" - {warning}")
print("\n✅ Documentation structure is valid")
EOF
metadata:
name: File Metadata Checks
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Check for common issues
run: |
set +e # Don't exit on first error
echo "📋 Checking for documentation issues..."
# Check for files over 100KB
echo "Checking file sizes..."
large_files=$(find . -name "*.md" -size +100k | grep -v ".venv" | grep -v "node_modules")
if [ ! -z "$large_files" ]; then
echo "⚠ Large markdown files found (>100KB):"
echo "$large_files"
fi
# Check for TODO markers (might indicate incomplete content)
echo "Checking for TODO markers in main docs..."
todos=$(grep -r "TODO\|FIXME" --include="*.md" . --exclude-dir=.venv --exclude-dir=node_modules --exclude-dir=.git | grep -v ".github" | head -10)
if [ ! -z "$todos" ]; then
echo "⚠ Found TODO/FIXME markers:"
echo "$todos"
fi
# Check for consistent heading structure
echo "Checking heading consistency in key files..."
for file in README.md CONTRIBUTING.md; do
if [ -f "$file" ]; then
heading_count=$(grep -c "^##" "$file")
echo "✅ $file has $heading_count main sections"
fi
done
# Check that LICENSE file exists
if [ -f "LICENSE" ]; then
echo "✅ LICENSE file exists"
else
echo "❌ LICENSE file not found"
exit 1
fi
consistency:
name: Content Consistency
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Check Content Consistency
run: |
python3 << 'EOF'
import re
from pathlib import Path
errors = []
# Check that all numbered sections are referenced in README
readme_path = Path("README.md")
with open(readme_path) as f:
readme_content = f.read()
# Look for numbered directories
for i in range(1, 11):
dir_pattern = f"{i:02d}-"
dirs = list(Path(".").glob(f"{dir_pattern}*"))
if dirs:
for dir_path in dirs:
if dir_path.is_dir():
# Check if referenced in README
dir_name = dir_path.name
if dir_name not in readme_content:
errors.append(f"README.md: Directory '{dir_name}' not mentioned")
else:
print(f"✅ '{dir_name}' is referenced in README")
# Check for consistent code fence formatting
md_files = [f for f in Path(".").rglob("*.md") if ".venv" not in str(f)]
for file_path in md_files:
with open(file_path) as f:
content = f.read()
# Count code fence types
backtick_fences = len(re.findall(r'```', content))
if backtick_fences % 2 != 0:
errors.append(f"{file_path}: Unmatched code fences (backticks)")
if errors:
print("\n❌ Consistency Errors:")
for error in errors:
print(f" - {error}")
exit(1)
print("\n✅ Content is consistent")
EOF
summary:
name: Summary
needs: [markdown-lint, link-check, spelling, frontmatter, structure, metadata, consistency]
runs-on: ubuntu-latest
if: always()
steps:
- name: Check Job Results
run: |
if [ "${{ needs.markdown-lint.result }}" = "failure" ] || \
[ "${{ needs.link-check.result }}" = "failure" ] || \
[ "${{ needs.spelling.result }}" = "failure" ] || \
[ "${{ needs.frontmatter.result }}" = "failure" ] || \
[ "${{ needs.structure.result }}" = "failure" ] || \
[ "${{ needs.metadata.result }}" = "failure" ] || \
[ "${{ needs.consistency.result }}" = "failure" ]; then
echo "❌ Some documentation checks failed"
exit 1
else
echo "✅ All documentation checks passed!"
fi
================================================
FILE: .github/workflows/release.yml
================================================
name: Build and Release EPUB
on:
push:
tags:
- 'v*'
jobs:
build:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v4
- name: Build EPUB
run: uv run scripts/build_epub.py
- name: Create Release
uses: softprops/action-gh-release@v2
with:
files: claude-howto-guide.epub
generate_release_notes: true
================================================
FILE: .github/workflows/test.yml
================================================
name: Automated Testing
on:
push:
branches: [main, develop]
paths:
- 'scripts/**'
- '.github/workflows/test.yml'
- 'pyproject.toml'
- 'requirements*.txt'
pull_request:
branches: [main]
paths:
- 'scripts/**'
- '.github/workflows/test.yml'
- 'pyproject.toml'
- 'requirements*.txt'
# Cancel in-progress runs for the same branch
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
pytest:
name: Unit Tests (Python ${{ matrix.python-version }})
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
python-version: ['3.10', '3.11', '3.12']
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v4
- name: Set up Python ${{ matrix.python-version }}
run: uv python install ${{ matrix.python-version }}
- name: Create venv and install dependencies
run: |
uv venv
uv pip install -r scripts/requirements-dev.txt
- name: Run pytest
run: uv run pytest scripts/tests/ -v --tb=short --cov=scripts --cov-report=xml --cov-report=html
continue-on-error: false
- name: Upload coverage to Codecov
uses: codecov/codecov-action@v3
with:
files: ./coverage.xml
flags: unittests
name: codecov-python-${{ matrix.python-version }}
fail_ci_if_error: false
verbose: true
- name: Archive test results
if: always()
uses: actions/upload-artifact@v4
with:
name: pytest-results-${{ matrix.python-version }}
path: |
coverage.xml
htmlcov/
retention-days: 7
lint:
name: Code Quality (Lint & Format)
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v4
- name: Set up Python
run: uv python install 3.11
- name: Create venv and install Ruff
run: |
uv venv
uv pip install ruff
- name: Ruff Format Check
run: uv run ruff format --check scripts/
continue-on-error: true
- name: Ruff Lint Check
run: uv run ruff check scripts/
continue-on-error: true
security:
name: Security Scan
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v4
- name: Set up Python
run: uv python install 3.11
- name: Create venv and install Bandit
run: |
uv venv
uv pip install "bandit[toml]"
- name: Run Bandit Security Scan
run: uv run bandit -c pyproject.toml -r scripts/ --exclude scripts/tests/ -f json -o bandit-report.json
continue-on-error: true
- name: Upload security report
uses: actions/upload-artifact@v4
if: always()
with:
name: bandit-security-report
path: bandit-report.json
retention-days: 7
type-check:
name: Type Checking
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v4
- name: Set up Python
run: uv python install 3.11
- name: Create venv and install mypy
run: |
uv venv
uv pip install -r scripts/requirements-dev.txt mypy
- name: Run mypy
run: uv run mypy scripts/ --ignore-missing-imports --no-implicit-optional
continue-on-error: true
build-epub:
name: Build EPUB Artifact
runs-on: ubuntu-latest
needs: [pytest, lint, security]
if: success()
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v4
- name: Set up Python
run: uv python install 3.11
- name: Create venv and install dependencies
run: |
uv venv
uv pip install -r scripts/requirements-dev.txt
- name: Build EPUB
run: uv run scripts/build_epub.py
- name: Verify EPUB Created
run: |
if [ -f claude-howto-guide.epub ]; then
echo "✅ EPUB built successfully"
ls -lh claude-howto-guide.epub
else
echo "❌ EPUB file not found!"
exit 1
fi
- name: Upload EPUB Artifact
uses: actions/upload-artifact@v4
with:
name: claude-howto-guide-epub
path: claude-howto-guide.epub
retention-days: 7
compression-level: 0
summary:
name: Test Summary
needs: [pytest, lint, security, type-check, build-epub]
runs-on: ubuntu-latest
if: always()
steps:
- name: Download all artifacts
uses: actions/download-artifact@v4
- name: Generate Summary
run: |
echo "# Test Summary" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "## Results" >> $GITHUB_STEP_SUMMARY
echo "- **Unit Tests**: ${{ needs.pytest.result }}" >> $GITHUB_STEP_SUMMARY
echo "- **Code Quality**: ${{ needs.lint.result }}" >> $GITHUB_STEP_SUMMARY
echo "- **Security Scan**: ${{ needs.security.result }}" >> $GITHUB_STEP_SUMMARY
echo "- **Type Checking**: ${{ needs.type-check.result }}" >> $GITHUB_STEP_SUMMARY
echo "- **EPUB Build**: ${{ needs.build-epub.result }}" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "## Artifacts" >> $GITHUB_STEP_SUMMARY
echo "- pytest-results-* (coverage and test results)" >> $GITHUB_STEP_SUMMARY
echo "- bandit-security-report (security scan JSON)" >> $GITHUB_STEP_SUMMARY
echo "- claude-howto-guide-epub (built EPUB file)" >> $GITHUB_STEP_SUMMARY
- name: Check if all tests passed
if: |
needs.pytest.result != 'success' ||
needs.build-epub.result != 'success'
run: |
echo "❌ Critical tests failed"
exit 1
- name: All tests passed
if: success()
run: echo "✅ All tests passed successfully!"
================================================
FILE: .gitignore
================================================
# macOS
.DS_Store
.AppleDouble
.LSOverride
# Thumbnails
._*
# Files that might appear in the root of a volume
.DocumentRevisions-V100
.fseventsd
.Spotlight-V100
.TemporaryItems
.Trashes
.VolumeIcon.icns
.com.apple.timemachine.donotpresent
# Directories potentially created on remote AFP share
.AppleDB
.AppleDesktop
Network Trash Folder
Temporary Items
.apdisk
# IDEs
.vscode/
.idea/
*.swp
*.swo
*~
# Logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# Environment variables
.env
.env.local
.env.*.local
# Temporary files
*.tmp
*.temp
# Keep .claude/ clean for hand-on section — except project skills
.claude/*
!.claude/skills/
.claude/skills/*
!.claude/skills/self-assessment/
!.claude/skills/lesson-quiz/
blog-posts/
# EPUB files in root directory
/*.epub
# Python virtual environment
.venv/
# Python cache
__pycache__/
*.py[cod]
*$py.class
*.so
.pytest_cache/
.mypy_cache/
*.egg-info/
dist/
build/
# Coverage reports
.coverage
htmlcov/
# uv lockfile
uv.lock
blog-post/
openspec/
.opencode/
# Promo video project
promo-video/
.agents/
.codex/
# Video files (too large for git)
*.mp4
update-plan*.md
================================================
FILE: .pre-commit-config.yaml
================================================
# Pre-commit hooks for claude-howto project
# Run `pre-commit install` to set up hooks
# Run `pre-commit run --all-files` to check all files
default_language_version:
python: python3.11
repos:
# Ruff - Fast Python linter and formatter
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.8.2
hooks:
# Ruff linter
- id: ruff
name: ruff-lint
args: [--fix, --exit-non-zero-on-fix]
types_or: [python, pyi]
files: ^scripts/
# Ruff formatter (replaces black)
- id: ruff-format
name: ruff-format
types_or: [python, pyi]
files: ^scripts/
# Bandit - Security linter
- repo: https://github.com/PyCQA/bandit
rev: 1.7.10
hooks:
- id: bandit
name: bandit-security
args: [-c, pyproject.toml]
additional_dependencies: ["bandit[toml]"]
types: [python]
files: ^scripts/
exclude: ^scripts/tests/
# Standard pre-commit hooks
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v5.0.0
hooks:
- id: check-yaml
name: check-yaml
args: [--allow-multiple-documents]
- id: check-toml
name: check-toml
- id: end-of-file-fixer
name: fix-end-of-file
- id: trailing-whitespace
name: fix-trailing-whitespace
- id: check-added-large-files
name: check-large-files
args: [--maxkb=1000]
- id: check-merge-conflict
name: check-merge-conflict
================================================
FILE: 01-slash-commands/README.md
================================================
<picture>
<source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">
<img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">
</picture>
# Slash Commands
## Overview
Slash commands are shortcuts that control Claude's behavior during an interactive session. They come in several types:
- **Built-in commands**: Provided by Claude Code (`/help`, `/clear`, `/model`)
- **Skills**: User-defined commands created as `SKILL.md` files (`/optimize`, `/pr`)
- **Plugin commands**: Commands from installed plugins (`/frontend-design:frontend-design`)
- **MCP prompts**: Commands from MCP servers (`/mcp__github__list_prs`)
> **Note**: Custom slash commands have been merged into skills. Files in `.claude/commands/` still work, but skills (`.claude/skills/`) are now the recommended approach. Both create `/command-name` shortcuts. See the [Skills Guide](../03-skills/) for the full reference.
## Built-in Commands Reference
Built-in commands are shortcuts for common actions. There are **55+ built-in commands** and **5 bundled skills** available. Type `/` in Claude Code to see the full list, or type `/` followed by any letters to filter.
| Command | Purpose |
|---------|---------|
| `/add-dir <path>` | Add working directory |
| `/agents` | Manage agent configurations |
| `/branch [name]` | Branch conversation into a new session (alias: `/fork`). Note: `/fork` renamed to `/branch` in v2.1.77 |
| `/btw <question>` | Side question without adding to history |
| `/chrome` | Configure Chrome browser integration |
| `/clear` | Clear conversation (aliases: `/reset`, `/new`) |
| `/color [color\|default]` | Set prompt bar color |
| `/compact [instructions]` | Compact conversation with optional focus instructions |
| `/config` | Open Settings (alias: `/settings`) |
| `/context` | Visualize context usage as colored grid |
| `/copy [N]` | Copy assistant response to clipboard; `w` writes to file |
| `/cost` | Show token usage statistics |
| `/desktop` | Continue in Desktop app (alias: `/app`) |
| `/diff` | Interactive diff viewer for uncommitted changes |
| `/doctor` | Diagnose installation health |
| `/effort [low\|medium\|high\|max\|auto]` | Set effort level. `max` requires Opus 4.6 |
| `/exit` | Exit the REPL (alias: `/quit`) |
| `/export [filename]` | Export the current conversation to a file or clipboard |
| `/extra-usage` | Configure extra usage for rate limits |
| `/fast [on\|off]` | Toggle fast mode |
| `/feedback` | Submit feedback (alias: `/bug`) |
| `/help` | Show help |
| `/hooks` | View hook configurations |
| `/ide` | Manage IDE integrations |
| `/init` | Initialize `CLAUDE.md`. Set `CLAUDE_CODE_NEW_INIT=true` for interactive flow |
| `/insights` | Generate session analysis report |
| `/install-github-app` | Set up GitHub Actions app |
| `/install-slack-app` | Install Slack app |
| `/keybindings` | Open keybindings configuration |
| `/login` | Switch Anthropic accounts |
| `/logout` | Sign out from your Anthropic account |
| `/mcp` | Manage MCP servers and OAuth |
| `/memory` | Edit `CLAUDE.md`, toggle auto-memory |
| `/mobile` | QR code for mobile app (aliases: `/ios`, `/android`) |
| `/model [model]` | Select model with left/right arrows for effort |
| `/passes` | Share free week of Claude Code |
| `/permissions` | View/update permissions (alias: `/allowed-tools`) |
| `/plan [description]` | Enter plan mode |
| `/plugin` | Manage plugins |
| `/pr-comments [PR]` | Fetch GitHub PR comments |
| `/privacy-settings` | Privacy settings (Pro/Max only) |
| `/release-notes` | View changelog |
| `/reload-plugins` | Reload active plugins |
| `/remote-control` | Remote control from claude.ai (alias: `/rc`) |
| `/remote-env` | Configure default remote environment |
| `/rename [name]` | Rename session |
| `/resume [session]` | Resume conversation (alias: `/continue`) |
| `/review` | **Deprecated** — install the `code-review` plugin instead |
| `/rewind` | Rewind conversation and/or code (alias: `/checkpoint`) |
| `/sandbox` | Toggle sandbox mode |
| `/schedule [description]` | Create/manage scheduled tasks |
| `/security-review` | Analyze branch for security vulnerabilities |
| `/skills` | List available skills |
| `/stats` | Visualize daily usage, sessions, streaks |
| `/status` | Show version, model, account |
| `/statusline` | Configure status line |
| `/tasks` | List/manage background tasks |
| `/terminal-setup` | Configure terminal keybindings |
| `/theme` | Change color theme |
| `/vim` | Toggle Vim/Normal modes |
| `/voice` | Toggle push-to-talk voice dictation |
### Bundled Skills
These skills ship with Claude Code and are invoked like slash commands:
| Skill | Purpose |
|-------|---------|
| `/batch <instruction>` | Orchestrate large-scale parallel changes using worktrees |
| `/claude-api` | Load Claude API reference for project language |
| `/debug [description]` | Enable debug logging |
| `/loop [interval] <prompt>` | Run prompt repeatedly on interval |
| `/simplify [focus]` | Review changed files for code quality |
### Deprecated Commands
| Command | Status |
|---------|--------|
| `/review` | Deprecated — replaced by `code-review` plugin |
| `/output-style` | Deprecated since v2.1.73 |
| `/fork` | Renamed to `/branch` (alias still works, v2.1.77) |
### Recent Changes
- `/fork` renamed to `/branch` with `/fork` kept as alias (v2.1.77)
- `/output-style` deprecated (v2.1.73)
- `/review` deprecated in favor of the `code-review` plugin
- `/effort` command added with `max` level requiring Opus 4.6
- `/voice` command added for push-to-talk voice dictation
- `/schedule` command added for creating/managing scheduled tasks
- `/color` command added for prompt bar customization
- `/model` picker now shows human-readable labels (e.g., "Sonnet 4.6") instead of raw model IDs
- `/resume` supports `/continue` alias
- MCP prompts are available as `/mcp__<server>__<prompt>` commands (see [MCP Prompts as Commands](#mcp-prompts-as-commands))
## Custom Commands (Now Skills)
Custom slash commands have been **merged into skills**. Both approaches create commands you can invoke with `/command-name`:
| Approach | Location | Status |
|----------|----------|--------|
| **Skills (Recommended)** | `.claude/skills/<name>/SKILL.md` | Current standard |
| **Legacy Commands** | `.claude/commands/<name>.md` | Still works |
If a skill and a command share the same name, the **skill takes precedence**. For example, when both `.claude/commands/review.md` and `.claude/skills/review/SKILL.md` exist, the skill version is used.
### Migration Path
Your existing `.claude/commands/` files continue to work without changes. To migrate to skills:
**Before (Command):**
```
.claude/commands/optimize.md
```
**After (Skill):**
```
.claude/skills/optimize/SKILL.md
```
### Why Skills?
Skills offer additional features over legacy commands:
- **Directory structure**: Bundle scripts, templates, and reference files
- **Auto-invocation**: Claude can trigger skills automatically when relevant
- **Invocation control**: Choose whether users, Claude, or both can invoke
- **Subagent execution**: Run skills in isolated contexts with `context: fork`
- **Progressive disclosure**: Load additional files only when needed
### Creating a Custom Command as a Skill
Create a directory with a `SKILL.md` file:
```bash
mkdir -p .claude/skills/my-command
```
**File:** `.claude/skills/my-command/SKILL.md`
```yaml
---
name: my-command
description: What this command does and when to use it
---
# My Command
Instructions for Claude to follow when this command is invoked.
1. First step
2. Second step
3. Third step
```
### Frontmatter Reference
| Field | Purpose | Default |
|-------|---------|---------|
| `name` | Command name (becomes `/name`) | Directory name |
| `description` | Brief description (helps Claude know when to use it) | First paragraph |
| `argument-hint` | Expected arguments for auto-completion | None |
| `allowed-tools` | Tools the command can use without permission | Inherits |
| `model` | Specific model to use | Inherits |
| `disable-model-invocation` | If `true`, only user can invoke (not Claude) | `false` |
| `user-invocable` | If `false`, hide from `/` menu | `true` |
| `context` | Set to `fork` to run in isolated subagent | None |
| `agent` | Agent type when using `context: fork` | `general-purpose` |
| `hooks` | Skill-scoped hooks (PreToolUse, PostToolUse, Stop) | None |
### Arguments
Commands can receive arguments:
**All arguments with `$ARGUMENTS`:**
```yaml
---
name: fix-issue
description: Fix a GitHub issue by number
---
Fix issue #$ARGUMENTS following our coding standards
```
Usage: `/fix-issue 123` → `$ARGUMENTS` becomes "123"
**Individual arguments with `$0`, `$1`, etc.:**
```yaml
---
name: review-pr
description: Review a PR with priority
---
Review PR #$0 with priority $1
```
Usage: `/review-pr 456 high` → `$0`="456", `$1`="high"
### Dynamic Context with Shell Commands
Execute bash commands before the prompt using `!`command``:
```yaml
---
name: commit
description: Create a git commit with context
allowed-tools: Bash(git *)
---
## Context
- Current git status: !`git status`
- Current git diff: !`git diff HEAD`
- Current branch: !`git branch --show-current`
- Recent commits: !`git log --oneline -5`
## Your task
Based on the above changes, create a single git commit.
```
### File References
Include file contents using `@`:
```markdown
Review the implementation in @src/utils/helpers.js
Compare @src/old-version.js with @src/new-version.js
```
## Plugin Commands
Plugins can provide custom commands:
```
/plugin-name:command-name
```
Or simply `/command-name` when there are no naming conflicts.
**Examples:**
```bash
/frontend-design:frontend-design
/commit-commands:commit
```
## MCP Prompts as Commands
MCP servers can expose prompts as slash commands:
```
/mcp__<server-name>__<prompt-name> [arguments]
```
**Examples:**
```bash
/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug title" high
```
### MCP Permission Syntax
Control MCP server access in permissions:
- `mcp__github` - Access entire GitHub MCP server
- `mcp__github__*` - Wildcard access to all tools
- `mcp__github__get_issue` - Specific tool access
## Command Architecture
```mermaid
graph TD
A["User Input: /command-name"] --> B{"Command Type?"}
B -->|Built-in| C["Execute Built-in"]
B -->|Skill| D["Load SKILL.md"]
B -->|Plugin| E["Load Plugin Command"]
B -->|MCP| F["Execute MCP Prompt"]
D --> G["Parse Frontmatter"]
G --> H["Substitute Variables"]
H --> I["Execute Shell Commands"]
I --> J["Send to Claude"]
J --> K["Return Results"]
```
## Command Lifecycle
```mermaid
sequenceDiagram
participant User
participant Claude as Claude Code
participant FS as File System
participant CLI as Shell/Bash
User->>Claude: Types /optimize
Claude->>FS: Searches .claude/skills/ and .claude/commands/
FS-->>Claude: Returns optimize/SKILL.md
Claude->>Claude: Parses frontmatter
Claude->>CLI: Executes !`command` substitutions
CLI-->>Claude: Command outputs
Claude->>Claude: Substitutes $ARGUMENTS
Claude->>User: Processes prompt
Claude->>User: Returns results
```
## Available Commands in This Folder
These example commands can be installed as skills or legacy commands.
### 1. `/optimize` - Code Optimization
Analyzes code for performance issues, memory leaks, and optimization opportunities.
**Usage:**
```
/optimize
[Paste your code]
```
### 2. `/pr` - Pull Request Preparation
Guides through PR preparation checklist including linting, testing, and commit formatting.
**Usage:**
```
/pr
```
**Screenshot:**
### 3. `/generate-api-docs` - API Documentation Generator
Generates comprehensive API documentation from source code.
**Usage:**
```
/generate-api-docs
```
### 4. `/commit` - Git Commit with Context
Creates a git commit with dynamic context from your repository.
**Usage:**
```
/commit [optional message]
```
### 5. `/push-all` - Stage, Commit, and Push
Stages all changes, creates a commit, and pushes to remote with safety checks.
**Usage:**
```
/push-all
```
**Safety Checks:**
- Secrets: `.env*`, `*.key`, `*.pem`, `credentials.json`
- API Keys: Detects real keys vs. placeholders
- Large files: `>10MB` without Git LFS
- Build artifacts: `node_modules/`, `dist/`, `__pycache__/`
### 6. `/doc-refactor` - Documentation Restructuring
Restructures project documentation for clarity and accessibility.
**Usage:**
```
/doc-refactor
```
### 7. `/setup-ci-cd` - CI/CD Pipeline Setup
Implements pre-commit hooks and GitHub Actions for quality assurance.
**Usage:**
```
/setup-ci-cd
```
### 8. `/unit-test-expand` - Test Coverage Expansion
Increases test coverage by targeting untested branches and edge cases.
**Usage:**
```
/unit-test-expand
```
## Installation
### As Skills (Recommended)
Copy to your skills directory:
```bash
# Create skills directory
mkdir -p .claude/skills
# For each command file, create a skill directory
for cmd in optimize pr commit; do
mkdir -p .claude/skills/$cmd
cp 01-slash-commands/$cmd.md .claude/skills/$cmd/SKILL.md
done
```
### As Legacy Commands
Copy to your commands directory:
```bash
# Project-wide (team)
mkdir -p .claude/commands
cp 01-slash-commands/*.md .claude/commands/
# Personal use
mkdir -p ~/.claude/commands
cp 01-slash-commands/*.md ~/.claude/commands/
```
## Creating Your Own Commands
### Skill Template (Recommended)
Create `.claude/skills/my-command/SKILL.md`:
```yaml
---
name: my-command
description: What this command does. Use when [trigger conditions].
argument-hint: [optional-args]
allowed-tools: Bash(npm *), Read, Grep
---
# Command Title
## Context
- Current branch: !`git branch --show-current`
- Related files: @package.json
## Instructions
1. First step
2. Second step with argument: $ARGUMENTS
3. Third step
## Output Format
- How to format the response
- What to include
```
### User-Only Command (No Auto-Invocation)
For commands with side effects that Claude shouldn't trigger automatically:
```yaml
---
name: deploy
description: Deploy to production
disable-model-invocation: true
allowed-tools: Bash(npm *), Bash(git *)
---
Deploy the application to production:
1. Run tests
2. Build application
3. Push to deployment target
4. Verify deployment
```
## Best Practices
| Do | Don't |
|------|---------|
| Use clear, action-oriented names | Create commands for one-time tasks |
| Include `description` with trigger conditions | Build complex logic in commands |
| Keep commands focused on single task | Hardcode sensitive information |
| Use `disable-model-invocation` for side effects | Skip the description field |
| Use `!` prefix for dynamic context | Assume Claude knows current state |
| Organize related files in skill directories | Put everything in one file |
## Troubleshooting
### Command Not Found
**Solutions:**
- Check file is in `.claude/skills/<name>/SKILL.md` or `.claude/commands/<name>.md`
- Verify the `name` field in frontmatter matches expected command name
- Restart Claude Code session
- Run `/help` to see available commands
### Command Not Executing as Expected
**Solutions:**
- Add more specific instructions
- Include examples in the skill file
- Check `allowed-tools` if using bash commands
- Test with simple inputs first
### Skill vs Command Conflict
If both exist with the same name, the **skill takes precedence**. Remove one or rename it.
## Related Guides
- **[Skills](../03-skills/)** - Full reference for skills (auto-invoked capabilities)
- **[Memory](../02-memory/)** - Persistent context with CLAUDE.md
- **[Subagents](../04-subagents/)** - Delegated AI agents
- **[Plugins](../07-plugins/)** - Bundled command collections
- **[Hooks](../06-hooks/)** - Event-driven automation
## Additional Resources
- [Official Interactive Mode Documentation](https://code.claude.com/docs/en/interactive-mode) - Built-in commands reference
- [Official Skills Documentation](https://code.claude.com/docs/en/skills) - Complete skills reference
- [CLI Reference](https://code.claude.com/docs/en/cli-reference) - Command-line options
---
*Part of the [Claude How To](../) guide series*
================================================
FILE: 01-slash-commands/commit.md
================================================
---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git diff:*)
argument-hint: [message]
description: Create a git commit with context
---
## Context
- Current git status: !`git status`
- Current git diff: !`git diff HEAD`
- Current branch: !`git branch --show-current`
- Recent commits: !`git log --oneline -10`
## Your task
Based on the above changes, create a single git commit.
If a message was provided via arguments, use it: $ARGUMENTS
Otherwise, analyze the changes and create an appropriate commit message following conventional commits format:
- `feat:` for new features
- `fix:` for bug fixes
- `docs:` for documentation changes
- `refactor:` for code refactoring
- `test:` for adding tests
- `chore:` for maintenance tasks
================================================
FILE: 01-slash-commands/doc-refactor.md
================================================
---
name: Documentation Refactor
description: Restructure project documentation for clarity and accessibility
tags: documentation, refactoring, organization
---
# Documentation Refactor
Refactor project documentation structure adapted to project type:
1. **Analyze project**: Identify type (library/API/web app/CLI/microservices), architecture, and user personas
2. **Centralize docs**: Move technical documentation to `docs/` with proper cross-references
3. **Root README.md**: Streamline as entry point with overview, quickstart, modules/components summary, license, contacts
4. **Component docs**: Add module/package/service-level README files with setup and testing instructions
5. **Organize `docs/`** by relevant categories:
- Architecture, API Reference, Database, Design, Troubleshooting, Deployment, Contributing (adapt to project needs)
6. **Create guides** (select applicable):
- User Guide: End-user documentation for applications
- API Documentation: Endpoints, authentication, examples for APIs
- Development Guide: Setup, testing, contribution workflow
- Deployment Guide: Production deployment for services/apps
7. **Use Mermaid** for all diagrams (architecture, flows, schemas)
Keep docs concise, scannable, and contextual to project type.
================================================
FILE: 01-slash-commands/generate-api-docs.md
================================================
---
description: Create comprehensive API documentation from source code
---
# API Documentation Generator
Generate API documentation by:
1. Scanning all files in `/src/api/`
2. Extracting function signatures and JSDoc comments
3. Organizing by endpoint/module
4. Creating markdown with examples
5. Including request/response schemas
6. Adding error documentation
Output format:
- Markdown file in `/docs/api.md`
- Include curl examples for all endpoints
- Add TypeScript types
================================================
FILE: 01-slash-commands/optimize.md
================================================
---
description: Analyze code for performance issues and suggest optimizations
---
# Code Optimization
Review the provided code for the following issues in order of priority:
1. **Performance bottlenecks** - identify O(n²) operations, inefficient loops
2. **Memory leaks** - find unreleased resources, circular references
3. **Algorithm improvements** - suggest better algorithms or data structures
4. **Caching opportunities** - identify repeated computations
5. **Concurrency issues** - find race conditions or threading problems
Format your response with:
- Issue severity (Critical/High/Medium/Low)
- Location in code
- Explanation
- Recommended fix with code example
================================================
FILE: 01-slash-commands/pr.md
================================================
---
description: Clean up code, stage changes, and prepare a pull request
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git diff:*), Bash(npm test:*), Bash(npm run lint:*)
---
# Pull Request Preparation Checklist
Before creating a PR, execute these steps:
1. Run linting: `prettier --write .`
2. Run tests: `npm test`
3. Review git diff: `git diff HEAD`
4. Stage changes: `git add .`
5. Create commit message following conventional commits:
- `fix:` for bug fixes
- `feat:` for new features
- `docs:` for documentation
- `refactor:` for code restructuring
- `test:` for test additions
- `chore:` for maintenance
6. Generate PR summary including:
- What changed
- Why it changed
- Testing performed
- Potential impacts
================================================
FILE: 01-slash-commands/push-all.md
================================================
---
description: Stage all changes, create commit, and push to remote (use with caution)
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git push:*), Bash(git diff:*), Bash(git log:*), Bash(git pull:*)
---
# Commit and Push Everything
⚠️ **CAUTION**: Stage ALL changes, commit, and push to remote. Use only when confident all changes belong together.
## Workflow
### 1. Analyze Changes
Run in parallel:
- `git status` - Show modified/added/deleted/untracked files
- `git diff --stat` - Show change statistics
- `git log -1 --oneline` - Show recent commit for message style
### 2. Safety Checks
**❌ STOP and WARN if detected:**
- Secrets: `.env*`, `*.key`, `*.pem`, `credentials.json`, `secrets.yaml`, `id_rsa`, `*.p12`, `*.pfx`, `*.cer`
- API Keys: Any `*_API_KEY`, `*_SECRET`, `*_TOKEN` variables with real values (not placeholders like `your-api-key`, `xxx`, `placeholder`)
- Large files: `>10MB` without Git LFS
- Build artifacts: `node_modules/`, `dist/`, `build/`, `__pycache__/`, `*.pyc`, `.venv/`
- Temp files: `.DS_Store`, `thumbs.db`, `*.swp`, `*.tmp`
**API Key Validation:**
Check modified files for patterns like:
```bash
OPENAI_API_KEY=sk-proj-xxxxx # ❌ Real key detected!
AWS_SECRET_KEY=AKIA... # ❌ Real key detected!
STRIPE_API_KEY=sk_live_... # ❌ Real key detected!
# ✅ Acceptable placeholders:
API_KEY=your-api-key-here
SECRET_KEY=placeholder
TOKEN=xxx
API_KEY=<your-key>
SECRET=${YOUR_SECRET}
```
**✅ Verify:**
- `.gitignore` properly configured
- No merge conflicts
- Correct branch (warn if main/master)
- API keys are placeholders only
### 3. Request Confirmation
Present summary:
```
📊 Changes Summary:
- X files modified, Y added, Z deleted
- Total: +AAA insertions, -BBB deletions
🔒 Safety: ✅ No secrets | ✅ No large files | ⚠️ [warnings]
🌿 Branch: [name] → origin/[name]
I will: git add . → commit → push
Type 'yes' to proceed or 'no' to cancel.
```
**WAIT for explicit "yes" before proceeding.**
### 4. Execute (After Confirmation)
Run sequentially:
```bash
git add .
git status # Verify staging
```
### 5. Generate Commit Message
Analyze changes and create conventional commit:
**Format:**
```
[type]: Brief summary (max 72 characters)
- Key change 1
- Key change 2
- Key change 3
```
**Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `build`, `ci`
**Example:**
```
docs: Update concept README files with comprehensive documentation
- Add architecture diagrams and tables
- Include practical examples
- Expand best practices sections
```
### 6. Commit and Push
```bash
git commit -m "$(cat <<'EOF'
[Generated commit message]
EOF
)"
git push # If fails: git pull --rebase && git push
git log -1 --oneline --decorate # Verify
```
### 7. Confirm Success
```
✅ Successfully pushed to remote!
Commit: [hash] [message]
Branch: [branch] → origin/[branch]
Files changed: X (+insertions, -deletions)
```
## Error Handling
- **git add fails**: Check permissions, locked files, verify repo initialized
- **git commit fails**: Fix pre-commit hooks, check git config (user.name/email)
- **git push fails**:
- Non-fast-forward: `git pull --rebase && git push`
- No remote branch: `git push -u origin [branch]`
- Protected branch: Use PR workflow instead
## When to Use
✅ **Good:**
- Multi-file documentation updates
- Feature with tests and docs
- Bug fixes across files
- Project-wide formatting/refactoring
- Configuration changes
❌ **Avoid:**
- Uncertain what's being committed
- Contains secrets/sensitive data
- Protected branches without review
- Merge conflicts present
- Want granular commit history
- Pre-commit hooks failing
## Alternatives
If user wants control, suggest:
1. **Selective staging**: Review/stage specific files
2. **Interactive staging**: `git add -p` for patch selection
3. **PR workflow**: Create branch → push → PR (use `/pr` command)
**⚠️ Remember**: Always review changes before pushing. When in doubt, use individual git commands for more control.
================================================
FILE: 01-slash-commands/setup-ci-cd.md
================================================
---
name: Setup CI/CD Pipeline
description: Implement pre-commit hooks and GitHub Actions for quality assurance
tags: ci-cd, devops, automation
---
# Setup CI/CD Pipeline
Implement comprehensive DevOps quality gates adapted to project type:
1. **Analyze project**: Detect language(s), framework, build system, and existing tooling
2. **Configure pre-commit hooks** with language-specific tools:
- Formatting: Prettier/Black/gofmt/rustfmt/etc.
- Linting: ESLint/Ruff/golangci-lint/Clippy/etc.
- Security: Bandit/gosec/cargo-audit/npm audit/etc.
- Type checking: TypeScript/mypy/flow (if applicable)
- Tests: Run relevant test suites
3. **Create GitHub Actions workflows** (.github/workflows/):
- Mirror pre-commit checks on push/PR
- Multi-version/platform matrix (if applicable)
- Build and test verification
- Deployment steps (if needed)
4. **Verify pipeline**: Test locally, create test PR, confirm all checks pass
Use free/open-source tools. Respect existing configs. Keep execution fast.
================================================
FILE: 01-slash-commands/unit-test-expand.md
================================================
---
name: Expand Unit Tests
description: Increase test coverage by targeting untested branches and edge cases
tags: testing, coverage, unit-tests
---
# Expand Unit Tests
Expand existing unit tests adapted to project's testing framework:
1. **Analyze coverage**: Run coverage report to identify untested branches, edge cases, and low-coverage areas
2. **Identify gaps**: Review code for logical branches, error paths, boundary conditions, null/empty inputs
3. **Write tests** using project's framework:
- Jest/Vitest/Mocha (JavaScript/TypeScript)
- pytest/unittest (Python)
- Go testing/testify (Go)
- Rust test framework (Rust)
4. **Target specific scenarios**:
- Error handling and exceptions
- Boundary values (min/max, empty, null)
- Edge cases and corner cases
- State transitions and side effects
5. **Verify improvement**: Run coverage again, confirm measurable increase
Present new test code blocks only. Follow existing test patterns and naming conventions.
================================================
FILE: 02-memory/README.md
================================================
<picture>
<source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">
<img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">
</picture>
# Memory Guide
Memory enables Claude to retain context across sessions and conversations. It exists in two forms: automatic synthesis in claude.ai, and filesystem-based CLAUDE.md in Claude Code.
## Overview
Memory in Claude Code provides persistent context that carries across multiple sessions and conversations. Unlike temporary context windows, memory files allow you to:
- Share project standards across your team
- Store personal development preferences
- Maintain directory-specific rules and configurations
- Import external documentation
- Version control memory as part of your project
The memory system operates at multiple levels, from global personal preferences down to specific subdirectories, allowing for fine-grained control over what Claude remembers and how it applies that knowledge.
## Memory Commands Quick Reference
| Command | Purpose | Usage | When to Use |
|---------|---------|-------|-------------|
| `/init` | Initialize project memory | `/init` | Starting new project, first-time CLAUDE.md setup |
| `/memory` | Edit memory files in editor | `/memory` | Extensive updates, reorganization, reviewing content |
| `#` prefix | Quick single-line memory add | `# Your rule here` | Adding quick rules during conversation |
| `# new rule into memory` | Explicit memory addition | `# new rule into memory<br/>Your detailed rule` | Adding complex multi-line rules |
| `# remember this` | Natural language memory | `# remember this<br/>Your instruction` | Conversational memory updates |
| `@path/to/file` | Import external content | `@README.md` or `@docs/api.md` | Referencing existing documentation in CLAUDE.md |
## Quick Start: Initializing Memory
### The `/init` Command
The `/init` command is the fastest way to set up project memory in Claude Code. It initializes a CLAUDE.md file with foundational project documentation.
**Usage:**
```bash
/init
```
**What it does:**
- Creates a new CLAUDE.md file in your project (typically at `./CLAUDE.md` or `./.claude/CLAUDE.md`)
- Establishes project conventions and guidelines
- Sets up the foundation for context persistence across sessions
- Provides a template structure for documenting your project standards
**Enhanced interactive mode:** Set `CLAUDE_CODE_NEW_INIT=true` to enable a multi-phase interactive flow that walks you through project setup step by step:
```bash
CLAUDE_CODE_NEW_INIT=true claude
/init
```
**When to use `/init`:**
- Starting a new project with Claude Code
- Establishing team coding standards and conventions
- Creating documentation about your codebase structure
- Setting up memory hierarchy for collaborative development
**Example workflow:**
```markdown
# In your project directory
/init
# Claude creates CLAUDE.md with structure like:
# Project Configuration
## Project Overview
- Name: Your Project
- Tech Stack: [Your technologies]
- Team Size: [Number of developers]
## Development Standards
- Code style preferences
- Testing requirements
- Git workflow conventions
```
### Quick Memory Updates with `#`
You can quickly add information to memory during any conversation by starting your message with `#`:
**Syntax:**
```markdown
# Your memory rule or instruction here
```
**Examples:**
```markdown
# Always use TypeScript strict mode in this project
# Prefer async/await over promise chains
# Run npm test before every commit
# Use kebab-case for file names
```
**How it works:**
1. Start your message with `#` followed by your rule
2. Claude recognizes this as a memory update request
3. Claude asks which memory file to update (project or personal)
4. The rule is added to the appropriate CLAUDE.md file
5. Future sessions automatically load this context
**Alternative patterns:**
```markdown
# new rule into memory
Always validate user input with Zod schemas
# remember this
Use semantic versioning for all releases
# add to memory
Database migrations must be reversible
```
### The `/memory` Command
The `/memory` command provides direct access to edit your CLAUDE.md memory files within Claude Code sessions. It opens your memory files in your system editor for comprehensive editing.
**Usage:**
```bash
/memory
```
**What it does:**
- Opens your memory files in your system's default editor
- Allows you to make extensive additions, modifications, and reorganizations
- Provides direct access to all memory files in the hierarchy
- Enables you to manage persistent context across sessions
**When to use `/memory`:**
- Reviewing existing memory content
- Making extensive updates to project standards
- Reorganizing memory structure
- Adding detailed documentation or guidelines
- Maintaining and updating memory as your project evolves
**Comparison: `/memory` vs `/init`**
| Aspect | `/memory` | `/init` |
|--------|-----------|---------|
| **Purpose** | Edit existing memory files | Initialize new CLAUDE.md |
| **When to use** | Update/modify project context | Begin new projects |
| **Action** | Opens editor for changes | Generates starter template |
| **Workflow** | Ongoing maintenance | One-time setup |
**Example workflow:**
```markdown
# Open memory for editing
/memory
# Claude presents options:
# 1. Managed Policy Memory
# 2. Project Memory (./CLAUDE.md)
# 3. User Memory (~/.claude/CLAUDE.md)
# 4. Local Project Memory
# Choose option 2 (Project Memory)
# Your default editor opens with ./CLAUDE.md content
# Make changes, save, and close editor
# Claude automatically reloads the updated memory
```
**Using Memory Imports:**
CLAUDE.md files support the `@path/to/file` syntax to include external content:
```markdown
# Project Documentation
See @README.md for project overview
See @package.json for available npm commands
See @docs/architecture.md for system design
# Import from home directory using absolute path
@~/.claude/my-project-instructions.md
```
**Import features:**
- Both relative and absolute paths are supported (e.g., `@docs/api.md` or `@~/.claude/my-project-instructions.md`)
- Recursive imports are supported with a maximum depth of 5
- First-time imports from external locations trigger an approval dialog for security
- Import directives are not evaluated inside markdown code spans or code blocks (so documenting them in examples is safe)
- Helps avoid duplication by referencing existing documentation
- Automatically includes referenced content in Claude's context
## Memory Architecture
Memory in Claude Code follows a hierarchical system where different scopes serve different purposes:
```mermaid
graph TB
A["Claude Session"]
B["User Input"]
C["Memory System"]
D["Memory Storage"]
B -->|User provides info| C
C -->|Synthesizes every 24h| D
D -->|Loads automatically| A
A -->|Uses context| C
```
## Memory Hierarchy in Claude Code
Claude Code uses a multi-tier hierarchical memory system. Memory files are automatically loaded when Claude Code launches, with higher-level files taking precedence.
**Complete Memory Hierarchy (in order of precedence):**
1. **Managed Policy** - Organization-wide instructions
- macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`
- Linux/WSL: `/etc/claude-code/CLAUDE.md`
- Windows: `C:\Program Files\ClaudeCode\CLAUDE.md`
2. **Managed Drop-ins** - Alphabetically merged policy files (v2.1.83+)
- `managed-settings.d/` directory alongside the managed policy CLAUDE.md
- Files are merged in alphabetical order for modular policy management
3. **Project Memory** - Team-shared context (version controlled)
- `./.claude/CLAUDE.md` or `./CLAUDE.md` (in repository root)
4. **Project Rules** - Modular, topic-specific project instructions
- `./.claude/rules/*.md`
5. **User Memory** - Personal preferences (all projects)
- `~/.claude/CLAUDE.md`
6. **User-Level Rules** - Personal rules (all projects)
- `~/.claude/rules/*.md`
7. **Local Project Memory** - Personal project-specific preferences
- `./CLAUDE.local.md`
> **Note**: `CLAUDE.local.md` is not mentioned in the [official documentation](https://code.claude.com/docs/en/memory) as of March 2026. It may still work as a legacy feature. For new projects, consider using `~/.claude/CLAUDE.md` (user-level) or `.claude/rules/` (project-level, path-scoped) instead.
8. **Auto Memory** - Claude's automatic notes and learnings
- `~/.claude/projects/<project>/memory/`
**Memory Discovery Behavior:**
Claude searches for memory files in this order, with earlier locations taking precedence:
```mermaid
graph TD
A["Managed Policy<br/>/Library/.../ClaudeCode/CLAUDE.md"] -->|highest priority| A2["Managed Drop-ins<br/>managed-settings.d/"]
A2 --> B["Project Memory<br/>./CLAUDE.md"]
B --> C["Project Rules<br/>./.claude/rules/*.md"]
C --> D["User Memory<br/>~/.claude/CLAUDE.md"]
D --> E["User Rules<br/>~/.claude/rules/*.md"]
E --> F["Local Project Memory<br/>./CLAUDE.local.md"]
F --> G["Auto Memory<br/>~/.claude/projects/.../memory/"]
B -->|imports| H["@docs/architecture.md"]
H -->|imports| I["@docs/api-standards.md"]
style A fill:#fce4ec,stroke:#333,color:#333
style A2 fill:#fce4ec,stroke:#333,color:#333
style B fill:#e1f5fe,stroke:#333,color:#333
style C fill:#e1f5fe,stroke:#333,color:#333
style D fill:#f3e5f5,stroke:#333,color:#333
style E fill:#f3e5f5,stroke:#333,color:#333
style F fill:#e8f5e9,stroke:#333,color:#333
style G fill:#fff3e0,stroke:#333,color:#333
style H fill:#e1f5fe,stroke:#333,color:#333
style I fill:#e1f5fe,stroke:#333,color:#333
```
## Excluding CLAUDE.md Files with `claudeMdExcludes`
In large monorepos, some CLAUDE.md files may be irrelevant to your current work. The `claudeMdExcludes` setting lets you skip specific CLAUDE.md files so they are not loaded into context:
```jsonc
// In ~/.claude/settings.json or .claude/settings.json
{
"claudeMdExcludes": [
"packages/legacy-app/CLAUDE.md",
"vendors/**/CLAUDE.md"
]
}
```
Patterns are matched against paths relative to the project root. This is particularly useful for:
- Monorepos with many sub-projects, where only some are relevant
- Repositories that contain vendored or third-party CLAUDE.md files
- Reducing noise in Claude's context window by excluding stale or unrelated instructions
## Settings File Hierarchy
Claude Code settings (including `autoMemoryDirectory`, `claudeMdExcludes`, and other configuration) are resolved from a five-level hierarchy, with higher levels taking precedence:
| Level | Location | Scope |
|-------|----------|-------|
| 1 (Highest) | Managed policy (system-level) | Organization-wide enforcement |
| 2 | `managed-settings.d/` (v2.1.83+) | Modular policy drop-ins, merged alphabetically |
| 3 | `~/.claude/settings.json` | User preferences |
| 4 | `.claude/settings.json` | Project-level (committed to git) |
| 5 (Lowest) | `.claude/settings.local.json` | Local overrides (git-ignored) |
**Platform-specific configuration (v2.1.51+):**
Settings can also be configured via:
- **macOS**: Property list (plist) files
- **Windows**: Windows Registry
These platform-native mechanisms are read alongside JSON settings files and follow the same precedence rules.
## Modular Rules System
Create organized, path-specific rules using the `.claude/rules/` directory structure. Rules can be defined at both the project level and user level:
```
your-project/
├── .claude/
│ ├── CLAUDE.md
│ └── rules/
│ ├── code-style.md
│ ├── testing.md
│ ├── security.md
│ └── api/ # Subdirectories supported
│ ├── conventions.md
│ └── validation.md
~/.claude/
├── CLAUDE.md
└── rules/ # User-level rules (all projects)
├── personal-style.md
└── preferred-patterns.md
```
Rules are discovered recursively within the `rules/` directory, including any subdirectories. User-level rules at `~/.claude/rules/` are loaded before project-level rules, allowing personal defaults that projects can override.
### Path-Specific Rules with YAML Frontmatter
Define rules that apply only to specific file paths:
```markdown
---
paths: src/api/**/*.ts
---
# API Development Rules
- All API endpoints must include input validation
- Use Zod for schema validation
- Document all parameters and response types
- Include error handling for all operations
```
**Glob Pattern Examples:**
- `**/*.ts` - All TypeScript files
- `src/**/*` - All files under src/
- `src/**/*.{ts,tsx}` - Multiple extensions
- `{src,lib}/**/*.ts, tests/**/*.test.ts` - Multiple patterns
### Subdirectories and Symlinks
Rules in `.claude/rules/` support two organizational features:
- **Subdirectories**: Rules are discovered recursively, so you can organize them into topic-based folders (e.g., `rules/api/`, `rules/testing/`, `rules/security/`)
- **Symlinks**: Symlinks are supported for sharing rules across multiple projects. For example, you can symlink a shared rule file from a central location into each project's `.claude/rules/` directory
## Memory Locations Table
| Location | Scope | Priority | Shared | Access | Best For |
|----------|-------|----------|--------|--------|----------|
| `/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS) | Managed Policy | 1 (Highest) | Organization | System | Company-wide policies |
| `/etc/claude-code/CLAUDE.md` (Linux/WSL) | Managed Policy | 1 (Highest) | Organization | System | Organization standards |
| `C:\Program Files\ClaudeCode\CLAUDE.md` (Windows) | Managed Policy | 1 (Highest) | Organization | System | Corporate guidelines |
| `managed-settings.d/*.md` (alongside policy) | Managed Drop-ins | 1.5 | Organization | System | Modular policy files (v2.1.83+) |
| `./CLAUDE.md` or `./.claude/CLAUDE.md` | Project Memory | 2 | Team | Git | Team standards, shared architecture |
| `./.claude/rules/*.md` | Project Rules | 3 | Team | Git | Path-specific, modular rules |
| `~/.claude/CLAUDE.md` | User Memory | 4 | Individual | Filesystem | Personal preferences (all projects) |
| `~/.claude/rules/*.md` | User Rules | 5 | Individual | Filesystem | Personal rules (all projects) |
| `./CLAUDE.local.md` | Project Local | 6 | Individual | Git (ignored) | Personal project-specific preferences |
| `~/.claude/projects/<project>/memory/` | Auto Memory | 7 (Lowest) | Individual | Filesystem | Claude's automatic notes and learnings |
## Memory Update Lifecycle
Here's how memory updates flow through your Claude Code sessions:
```mermaid
sequenceDiagram
participant User
participant Claude as Claude Code
participant Editor as File System
participant Memory as CLAUDE.md
User->>Claude: "Remember: use async/await"
Claude->>User: "Which memory file?"
User->>Claude: "Project memory"
Claude->>Editor: Open ~/.claude/settings.json
Claude->>Memory: Write to ./CLAUDE.md
Memory-->>Claude: File saved
Claude->>Claude: Load updated memory
Claude-->>User: "Memory saved!"
```
## Auto Memory
Auto memory is a persistent directory where Claude automatically records learnings, patterns, and insights as it works with your project. Unlike CLAUDE.md files which you write and maintain manually, auto memory is written by Claude itself during sessions.
### How Auto Memory Works
- **Location**: `~/.claude/projects/<project>/memory/`
- **Entrypoint**: `MEMORY.md` serves as the main file in the auto memory directory
- **Topic files**: Optional additional files for specific subjects (e.g., `debugging.md`, `api-conventions.md`)
- **Loading behavior**: The first 200 lines of `MEMORY.md` are loaded into the system prompt at session start. Topic files are loaded on demand, not at startup.
- **Read/write**: Claude reads and writes memory files during sessions as it discovers patterns and project-specific knowledge
### Auto Memory Architecture
```mermaid
graph TD
A["Claude Session Starts"] --> B["Load MEMORY.md<br/>(first 200 lines)"]
B --> C["Session Active"]
C --> D["Claude discovers<br/>patterns & insights"]
D --> E{"Write to<br/>auto memory"}
E -->|General notes| F["MEMORY.md"]
E -->|Topic-specific| G["debugging.md"]
E -->|Topic-specific| H["api-conventions.md"]
C --> I["On-demand load<br/>topic files"]
I --> C
style A fill:#e1f5fe,stroke:#333,color:#333
style B fill:#e1f5fe,stroke:#333,color:#333
style C fill:#e8f5e9,stroke:#333,color:#333
style D fill:#f3e5f5,stroke:#333,color:#333
style E fill:#fff3e0,stroke:#333,color:#333
style F fill:#fce4ec,stroke:#333,color:#333
style G fill:#fce4ec,stroke:#333,color:#333
style H fill:#fce4ec,stroke:#333,color:#333
style I fill:#f3e5f5,stroke:#333,color:#333
```
### Auto Memory Directory Structure
```
~/.claude/projects/<project>/memory/
├── MEMORY.md # Entrypoint (first 200 lines loaded at startup)
├── debugging.md # Topic file (loaded on demand)
├── api-conventions.md # Topic file (loaded on demand)
└── testing-patterns.md # Topic file (loaded on demand)
```
### Version Requirement
Auto memory requires **Claude Code v2.1.59 or later**. If you are on an older version, upgrade first:
```bash
npm install -g @anthropic-ai/claude-code@latest
```
### Custom Auto Memory Directory
By default, auto memory is stored in `~/.claude/projects/<project>/memory/`. You can change this location using the `autoMemoryDirectory` setting (available since **v2.1.74**):
```jsonc
// In ~/.claude/settings.json or .claude/settings.local.json (user/local settings only)
{
"autoMemoryDirectory": "/path/to/custom/memory/directory"
}
```
> **Note**: `autoMemoryDirectory` can only be set in user-level (`~/.claude/settings.json`) or local settings (`.claude/settings.local.json`), not in project or managed policy settings.
This is useful when you want to:
- Store auto memory in a shared or synced location
- Separate auto memory from the default Claude configuration directory
- Use a project-specific path outside the default hierarchy
### Worktree and Repository Sharing
All worktrees and subdirectories within the same git repository share a single auto memory directory. This means switching between worktrees or working in different subdirectories of the same repo will read and write to the same memory files.
### Subagent Memory
Subagents (spawned via tools like Task or parallel execution) can have their own memory context. Use the `memory` frontmatter field in the subagent definition to specify which memory scopes to load:
```yaml
memory: user # Load user-level memory only
memory: project # Load project-level memory only
memory: local # Load local memory only
```
This allows subagents to operate with focused context rather than inheriting the full memory hierarchy.
### Controlling Auto Memory
Auto memory can be controlled via the `CLAUDE_CODE_DISABLE_AUTO_MEMORY` environment variable:
| Value | Behavior |
|-------|----------|
| `0` | Force auto memory **on** |
| `1` | Force auto memory **off** |
| *(unset)* | Default behavior (auto memory enabled) |
```bash
# Disable auto memory for a session
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude
# Force auto memory on explicitly
CLAUDE_CODE_DISABLE_AUTO_MEMORY=0 claude
```
## Additional Directories with `--add-dir`
The `--add-dir` flag allows Claude Code to load CLAUDE.md files from additional directories beyond the current working directory. This is useful for monorepos or multi-project setups where context from other directories is relevant.
To enable this feature, set the environment variable:
```bash
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1
```
Then launch Claude Code with the flag:
```bash
claude --add-dir /path/to/other/project
```
Claude will load CLAUDE.md from the specified additional directory alongside the memory files from your current working directory.
## Practical Examples
### Example 1: Project Memory Structure
**File:** `./CLAUDE.md`
```markdown
# Project Configuration
## Project Overview
- **Name**: E-commerce Platform
- **Tech Stack**: Node.js, PostgreSQL, React 18, Docker
- **Team Size**: 5 developers
- **Deadline**: Q4 2025
## Architecture
@docs/architecture.md
@docs/api-standards.md
@docs/database-schema.md
## Development Standards
### Code Style
- Use Prettier for formatting
- Use ESLint with airbnb config
- Maximum line length: 100 characters
- Use 2-space indentation
### Naming Conventions
- **Files**: kebab-case (user-controller.js)
- **Classes**: PascalCase (UserService)
- **Functions/Variables**: camelCase (getUserById)
- **Constants**: UPPER_SNAKE_CASE (API_BASE_URL)
- **Database Tables**: snake_case (user_accounts)
### Git Workflow
- Branch names: `feature/description` or `fix/description`
- Commit messages: Follow conventional commits
- PR required before merge
- All CI/CD checks must pass
- Minimum 1 approval required
### Testing Requirements
- Minimum 80% code coverage
- All critical paths must have tests
- Use Jest for unit tests
- Use Cypress for E2E tests
- Test filenames: `*.test.ts` or `*.spec.ts`
### API Standards
- RESTful endpoints only
- JSON request/response
- Use HTTP status codes correctly
- Version API endpoints: `/api/v1/`
- Document all endpoints with examples
### Database
- Use migrations for schema changes
- Never hardcode credentials
- Use connection pooling
- Enable query logging in development
- Regular backups required
### Deployment
- Docker-based deployment
- Kubernetes orchestration
- Blue-green deployment strategy
- Automatic rollback on failure
- Database migrations run before deploy
## Common Commands
| Command | Purpose |
|---------|---------|
| `npm run dev` | Start development server |
| `npm test` | Run test suite |
| `npm run lint` | Check code style |
| `npm run build` | Build for production |
| `npm run migrate` | Run database migrations |
## Team Contacts
- Tech Lead: Sarah Chen (@sarah.chen)
- Product Manager: Mike Johnson (@mike.j)
- DevOps: Alex Kim (@alex.k)
## Known Issues & Workarounds
- PostgreSQL connection pooling limited to 20 during peak hours
- Workaround: Implement query queuing
- Safari 14 compatibility issues with async generators
- Workaround: Use Babel transpiler
## Related Projects
- Analytics Dashboard: `/projects/analytics`
- Mobile App: `/projects/mobile`
- Admin Panel: `/projects/admin`
```
### Example 2: Directory-Specific Memory
**File:** `./src/api/CLAUDE.md`
```markdown
# API Module Standards
This file overrides root CLAUDE.md for everything in /src/api/
## API-Specific Standards
### Request Validation
- Use Zod for schema validation
- Always validate input
- Return 400 with validation errors
- Include field-level error details
### Authentication
- All endpoints require JWT token
- Token in Authorization header
- Token expires after 24 hours
- Implement refresh token mechanism
### Response Format
All responses must follow this structure:
```json
{
"success": true,
"data": { /* actual data */ },
"timestamp": "2025-11-06T10:30:00Z",
"version": "1.0"
}
```
Error responses:
```json
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "User message",
"details": { /* field errors */ }
},
"timestamp": "2025-11-06T10:30:00Z"
}
```
### Pagination
- Use cursor-based pagination (not offset)
- Include `hasMore` boolean
- Limit max page size to 100
- Default page size: 20
### Rate Limiting
- 1000 requests per hour for authenticated users
- 100 requests per hour for public endpoints
- Return 429 when exceeded
- Include retry-after header
### Caching
- Use Redis for session caching
- Cache duration: 5 minutes default
- Invalidate on write operations
- Tag cache keys with resource type
```
### Example 3: Personal Memory
**File:** `~/.claude/CLAUDE.md`
```markdown
# My Development Preferences
## About Me
- **Experience Level**: 8 years full-stack development
- **Preferred Languages**: TypeScript, Python
- **Communication Style**: Direct, with examples
- **Learning Style**: Visual diagrams with code
## Code Preferences
### Error Handling
I prefer explicit error handling with try-catch blocks and meaningful error messages.
Avoid generic errors. Always log errors for debugging.
### Comments
Use comments for WHY, not WHAT. Code should be self-documenting.
Comments should explain business logic or non-obvious decisions.
### Testing
I prefer TDD (test-driven development).
Write tests first, then implementation.
Focus on behavior, not implementation details.
### Architecture
I prefer modular, loosely-coupled design.
Use dependency injection for testability.
Separate concerns (Controllers, Services, Repositories).
## Debugging Preferences
- Use console.log with prefix: `[DEBUG]`
- Include context: function name, relevant variables
- Use stack traces when available
- Always include timestamps in logs
## Communication
- Explain complex concepts with diagrams
- Show concrete examples before explaining theory
- Include before/after code snippets
- Summarize key points at the end
## Project Organization
I organize my projects as:
project/
├── src/
│ ├── api/
│ ├── services/
│ ├── models/
│ └── utils/
├── tests/
├── docs/
└── docker/
## Tooling
- **IDE**: VS Code with vim keybindings
- **Terminal**: Zsh with Oh-My-Zsh
- **Format**: Prettier (100 char line length)
- **Linter**: ESLint with airbnb config
- **Test Framework**: Jest with React Testing Library
```
_My Test_
Ask Claude to save a new rule
Claude has not save the rule because I did not have any `Claude.md` file anywhere. Then asked Claude to confirm the location.
### Example 4: Memory Update During Session
You can add new rules to memory during an active Claude Code session. There are two ways to do this:
#### Method 1: Direct Request
```markdown
User: Remember that I prefer using React hooks instead of class components
for all new components.
Claude: I'm adding that to your memory. Which memory file should this go in?
1. Project memory (./CLAUDE.md)
2. Personal memory (~/.claude/CLAUDE.md)
User: Project memory
Claude: ✅ Memory saved!
Added to ./CLAUDE.md:
---
### Component Development
- Use functional components with React Hooks
- Prefer hooks over class components
- Custom hooks for reusable logic
- Use useCallback for event handlers
- Use useMemo for expensive computations
```
#### Method 2: Using "# new rule into memory" Pattern
You can also use the explicit pattern "# new rule into memory" to trigger memory updates:
```markdown
User: # new rule into memory
Always validate user input with Zod schemas before processing.
Claude: I'm saving this rule to memory. Which memory file should I use?
1. Project memory (./CLAUDE.md)
2. Personal memory (~/.claude/CLAUDE.md)
User: Project memory
Claude: ✅ Memory saved!
Added to ./CLAUDE.md:
---
### Input Validation
- Always validate user input with Zod schemas before processing
- Define schemas at the top of each API handler file
- Return 400 status with validation errors
```
#### Tips for Adding Memory
- Be specific and actionable in your rules
- Group related rules together under a section header
- Update existing sections instead of duplicating content
- Choose the appropriate memory scope (project vs. personal)
## Memory Features Comparison
| Feature | Claude Web/Desktop | Claude Code (CLAUDE.md) |
|---------|-------------------|------------------------|
| Auto-synthesis | ✅ Every 24h | ❌ Manual |
| Cross-project | ✅ Shared | ❌ Project-specific |
| Team access | ✅ Shared projects | ✅ Git-tracked |
| Searchable | ✅ Built-in | ✅ Through `/memory` |
| Editable | ✅ In-chat | ✅ Direct file edit |
| Import/Export | ✅ Yes | ✅ Copy/paste |
| Persistent | ✅ 24h+ | ✅ Indefinite |
### Memory in Claude Web/Desktop
#### Memory Synthesis Timeline
```mermaid
graph LR
A["Day 1: User<br/>Conversations"] -->|24 hours| B["Day 2: Memory<br/>Synthesis"]
B -->|Automatic| C["Memory Updated<br/>Summarized"]
C -->|Loaded in| D["Day 2-N:<br/>New Conversations"]
D -->|Add to| E["Memory"]
E -->|24 hours later| F["Memory Refreshed"]
```
**Example Memory Summary:**
```markdown
## Claude's Memory of User
### Professional Background
- Senior full-stack developer with 8 years experience
- Focus on TypeScript/Node.js backends and React frontends
- Active open source contributor
- Interested in AI and machine learning
### Project Context
- Currently building e-commerce platform
- Tech stack: Node.js, PostgreSQL, React 18, Docker
- Working with team of 5 developers
- Using CI/CD and blue-green deployments
### Communication Preferences
- Prefers direct, concise explanations
- Likes visual diagrams and examples
- Appreciates code snippets
- Explains business logic in comments
### Current Goals
- Improve API performance
- Increase test coverage to 90%
- Implement caching strategy
- Document architecture
```
## Best Practices
### Do's - What To Include
- **Be specific and detailed**: Use clear, detailed instructions rather than vague guidance
- ✅ Good: "Use 2-space indentation for all JavaScript files"
- ❌ Avoid: "Follow best practices"
- **Keep organized**: Structure memory files with clear markdown sections and headings
- **Use appropriate hierarchy levels**:
- **Managed policy**: Company-wide policies, security standards, compliance requirements
- **Project memory**: Team standards, architecture, coding conventions (commit to git)
- **User memory**: Personal preferences, communication style, tooling choices
- **Directory memory**: Module-specific rules and overrides
- **Leverage imports**: Use `@path/to/file` syntax to reference existing documentation
- Supports up to 5 levels of recursive nesting
- Avoids duplication across memory files
- Example: `See @README.md for project overview`
- **Document frequent commands**: Include commands you use repeatedly to save time
- **Version control project memory**: Commit project-level CLAUDE.md files to git for team benefit
- **Review periodically**: Update memory regularly as projects evolve and requirements change
- **Provide concrete examples**: Include code snippets and specific scenarios
### Don'ts - What To Avoid
- **Don't store secrets**: Never include API keys, passwords, tokens, or credentials
- **Don't include sensitive data**: No PII, private information, or proprietary secrets
- **Don't duplicate content**: Use imports (`@path`) to reference existing documentation instead
- **Don't be vague**: Avoid generic statements like "follow best practices" or "write good code"
- **Don't make it too long**: Keep individual memory files focused and under 500 lines
- **Don't over-organize**: Use hierarchy strategically; don't create excessive subdirectory overrides
- **Don't forget to update**: Stale memory can cause confusion and outdated practices
- **Don't exceed nesting limits**: Memory imports support up to 5 levels of nesting
### Memory Management Tips
**Choose the right memory level:**
| Use Case | Memory Level | Rationale |
|----------|-------------|-----------|
| Company security policy | Managed Policy | Applies to all projects organization-wide |
| Team code style guide | Project | Shared with team via git |
| Your preferred editor shortcuts | User | Personal preference, not shared |
| API module standards | Directory | Specific to that module only |
**Quick update workflow:**
1. For single rules: Use `#` prefix in conversation
2. For multiple changes: Use `/memory` to open editor
3. For initial setup: Use `/init` to create template
**Import best practices:**
```markdown
# Good: Reference existing docs
@README.md
@docs/architecture.md
@package.json
# Avoid: Copying content that exists elsewhere
# Instead of copying README content into CLAUDE.md, just import it
```
## Installation Instructions
### Setup Project Memory
#### Method 1: Using `/init` Command (Recommended)
The fastest way to set up project memory:
1. **Navigate to your project directory:**
```bash
cd /path/to/your/project
```
2. **Run the init command in Claude Code:**
```bash
/init
```
3. **Claude will create and populate CLAUDE.md** with a template structure
4. **Customize the generated file** to match your project needs
5. **Commit to git:**
```bash
git add CLAUDE.md
git commit -m "Initialize project memory with /init"
```
#### Method 2: Manual Creation
If you prefer manual setup:
1. **Create a CLAUDE.md in your project root:**
```bash
cd /path/to/your/project
touch CLAUDE.md
```
2. **Add project standards:**
```bash
cat > CLAUDE.md << 'EOF'
# Project Configuration
## Project Overview
- **Name**: Your Project Name
- **Tech Stack**: List your technologies
- **Team Size**: Number of developers
## Development Standards
- Your coding standards
- Naming conventions
- Testing requirements
EOF
```
3. **Commit to git:**
```bash
git add CLAUDE.md
git commit -m "Add project memory configuration"
```
#### Method 3: Quick Updates with `#`
Once CLAUDE.md exists, add rules quickly during conversations:
```markdown
# Use semantic versioning for all releases
# Always run tests before committing
# Prefer composition over inheritance
```
Claude will prompt you to choose which memory file to update.
### Setup Personal Memory
1. **Create ~/.claude directory:**
```bash
mkdir -p ~/.claude
```
2. **Create personal CLAUDE.md:**
```bash
touch ~/.claude/CLAUDE.md
```
3. **Add your preferences:**
```bash
cat > ~/.claude/CLAUDE.md << 'EOF'
# My Development Preferences
## About Me
- Experience Level: [Your level]
- Preferred Languages: [Your languages]
- Communication Style: [Your style]
## Code Preferences
- [Your preferences]
EOF
```
### Setup Directory-Specific Memory
1. **Create memory for specific directories:**
```bash
mkdir -p /path/to/directory/.claude
touch /path/to/directory/CLAUDE.md
```
2. **Add directory-specific rules:**
```bash
cat > /path/to/directory/CLAUDE.md << 'EOF'
# [Directory Name] Standards
This file overrides root CLAUDE.md for this directory.
## [Specific Standards]
EOF
```
3. **Commit to version control:**
```bash
git add /path/to/directory/CLAUDE.md
git commit -m "Add [directory] memory configuration"
```
### Verify Setup
1. **Check memory locations:**
```bash
# Project root memory
ls -la ./CLAUDE.md
# Personal memory
ls -la ~/.claude/CLAUDE.md
```
2. **Claude Code will automatically load** these files when starting a session
3. **Test with Claude Code** by starting a new session in your project
## Official Documentation
For the most up-to-date information, refer to the official Claude Code documentation:
- **[Memory Documentation](https://code.claude.com/docs/en/memory)** - Complete memory system reference
- **[Slash Commands Reference](https://code.claude.com/docs/en/interactive-mode)** - All built-in commands including `/init` and `/memory`
- **[CLI Reference](https://code.claude.com/docs/en/cli-reference)** - Command-line interface documentation
### Key Technical Details from Official Docs
**Memory Loading:**
- All memory files are automatically loaded when Claude Code launches
- Claude traverses upward from the current working directory to discover CLAUDE.md files
- Subtree files are discovered and loaded contextually when accessing those directories
**Import Syntax:**
- Use `@path/to/file` to include external content (e.g., `@~/.claude/my-project-instructions.md`)
- Supports both relative and absolute paths
- Recursive imports supported with a maximum depth of 5
- First-time external imports trigger an approval dialog
- Not evaluated inside markdown code spans or code blocks
- Automatically includes referenced content in Claude's context
**Memory Hierarchy Precedence:**
1. Managed Policy (highest precedence)
2. Managed Drop-ins (`managed-settings.d/`, v2.1.83+)
3. Project Memory
4. Project Rules (`.claude/rules/`)
5. User Memory
6. User-Level Rules (`~/.claude/rules/`)
7. Local Project Memory
8. Auto Memory (lowest precedence)
## Related Concepts Links
### Integration Points
- [MCP Protocol](../05-mcp/) - Live data access alongside memory
- [Slash Commands](../01-slash-commands/) - Session-specific shortcuts
- [Skills](../03-skills/) - Automated workflows with memory context
### Related Claude Features
- [Claude Web Memory](https://claude.ai) - Automatic synthesis
- [Official Memory Docs](https://code.claude.com/docs/en/memory) - Anthropic documentation
================================================
FILE: 02-memory/directory-api-CLAUDE.md
================================================
# API Module Standards
This file overrides root CLAUDE.md for everything in /src/api/
## API-Specific Standards
### Request Validation
- Use Zod for schema validation
- Always validate input
- Return 400 with validation errors
- Include field-level error details
### Authentication
- All endpoints require JWT token
- Token in Authorization header
- Token expires after 24 hours
- Implement refresh token mechanism
### Response Format
All responses must follow this structure:
```json
{
"success": true,
"data": { /* actual data */ },
"timestamp": "2025-11-06T10:30:00Z",
"version": "1.0"
}
```
Error responses:
```json
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "User message",
"details": { /* field errors */ }
},
"timestamp": "2025-11-06T10:30:00Z"
}
```
### Pagination
- Use cursor-based pagination (not offset)
- Include `hasMore` boolean
- Limit max page size to 100
- Default page size: 20
### Rate Limiting
- 1000 requests per hour for authenticated users
- 100 requests per hour for public endpoints
- Return 429 when exceeded
- Include retry-after header
### Caching
- Use Redis for session caching
- Cache duration: 5 minutes default
- Invalidate on write operations
- Tag cache keys with resource type
================================================
FILE: 02-memory/personal-CLAUDE.md
================================================
# My Development Preferences
## About Me
- **Experience Level**: 8 years full-stack development
- **Preferred Languages**: TypeScript, Python
- **Communication Style**: Direct, with examples
- **Learning Style**: Visual diagrams with code
## Code Preferences
### Error Handling
I prefer explicit error handling with try-catch blocks and meaningful error messages.
Avoid generic errors. Always log errors for debugging.
### Comments
Use comments for WHY, not WHAT. Code should be self-documenting.
Comments should explain business logic or non-obvious decisions.
### Testing
I prefer TDD (test-driven development).
Write tests first, then implementation.
Focus on behavior, not implementation details.
### Architecture
I prefer modular, loosely-coupled design.
Use dependency injection for testability.
Separate concerns (Controllers, Services, Repositories).
## Debugging Preferences
- Use console.log with prefix: `[DEBUG]`
- Include context: function name, relevant variables
- Use stack traces when available
- Always include timestamps in logs
## Communication
- Explain complex concepts with diagrams
- Show concrete examples before explaining theory
- Include before/after code snippets
- Summarize key points at the end
## Project Organization
I organize my projects as:
```
project/
├── src/
│ ├── api/
│ ├── services/
│ ├── models/
│ └── utils/
├── tests/
├── docs/
└── docker/
```
## Tooling
- **IDE**: VS Code with vim keybindings
- **Terminal**: Zsh with Oh-My-Zsh
- **Format**: Prettier (100 char line length)
- **Linter**: ESLint with airbnb config
- **Test Framework**: Jest with React Testing Library
================================================
FILE: 02-memory/project-CLAUDE.md
================================================
# Project Configuration
## Project Overview
- **Name**: E-commerce Platform
- **Tech Stack**: Node.js, PostgreSQL, React 18, Docker
- **Team Size**: 5 developers
- **Deadline**: Q4 2025
## Architecture
@docs/architecture.md
@docs/api-standards.md
@docs/database-schema.md
## Development Standards
### Code Style
- Use Prettier for formatting
- Use ESLint with airbnb config
- Maximum line length: 100 characters
- Use 2-space indentation
### Naming Conventions
- **Files**: kebab-case (user-controller.js)
- **Classes**: PascalCase (UserService)
- **Functions/Variables**: camelCase (getUserById)
- **Constants**: UPPER_SNAKE_CASE (API_BASE_URL)
- **Database Tables**: snake_case (user_accounts)
### Git Workflow
- Branch names: `feature/description` or `fix/description`
- Commit messages: Follow conventional commits
- PR required before merge
- All CI/CD checks must pass
- Minimum 1 approval required
### Testing Requirements
- Minimum 80% code coverage
- All critical paths must have tests
- Use Jest for unit tests
- Use Cypress for E2E tests
- Test filenames: `*.test.ts` or `*.spec.ts`
### API Standards
- RESTful endpoints only
- JSON request/response
- Use HTTP status codes correctly
- Version API endpoints: `/api/v1/`
- Document all endpoints with examples
### Database
- Use migrations for schema changes
- Never hardcode credentials
- Use connection pooling
- Enable query logging in development
- Regular backups required
### Deployment
- Docker-based deployment
- Kubernetes orchestration
- Blue-green deployment strategy
- Automatic rollback on failure
- Database migrations run before deploy
## Common Commands
| Command | Purpose |
|---------|---------|
| `npm run dev` | Start development server |
| `npm test` | Run test suite |
| `npm run lint` | Check code style |
| `npm run build` | Build for production |
| `npm run migrate` | Run database migrations |
## Team Contacts
- Tech Lead: Sarah Chen (@sarah.chen)
- Product Manager: Mike Johnson (@mike.j)
- DevOps: Alex Kim (@alex.k)
## Known Issues & Workarounds
- PostgreSQL connection pooling limited to 20 during peak hours
- Workaround: Implement query queuing
- Safari 14 compatibility issues with async generators
- Workaround: Use Babel transpiler
## Related Projects
- Analytics Dashboard: `/projects/analytics`
- Mobile App: `/projects/mobile`
- Admin Panel: `/projects/admin`
================================================
FILE: 03-skills/.gitignore
================================================
# Local skill testing
.claude/
# Blog post outputs
blog-posts/
================================================
FILE: 03-skills/README.md
================================================
<picture>
<source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">
<img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">
</picture>
# Agent Skills Guide
Agent Skills are reusable, filesystem-based capabilities that extend Claude's functionality. They package domain-specific expertise, workflows, and best practices into discoverable components that Claude automatically uses when relevant.
## Overview
**Agent Skills** are modular capabilities that transform general-purpose agents into specialists. Unlike prompts (conversation-level instructions for one-off tasks), Skills load on-demand and eliminate the need to repeatedly provide the same guidance across multiple conversations.
### Key Benefits
- **Specialize Claude**: Tailor capabilities for domain-specific tasks
- **Reduce repetition**: Create once, use automatically across conversations
- **Compose capabilities**: Combine Skills to build complex workflows
- **Scale workflows**: Reuse skills across multiple projects and teams
- **Maintain quality**: Embed best practices directly into your workflow
Skills follow the [Agent Skills](https://agentskills.io) open standard, which works across multiple AI tools. Claude Code extends the standard with additional features like invocation control, subagent execution, and dynamic context injection.
> **Note**: Custom slash commands have been merged into skills. `.claude/commands/` files still work and support the same frontmatter fields. Skills are recommended for new development. When both exist at the same path (e.g., `.claude/commands/review.md` and `.claude/skills/review/SKILL.md`), the skill takes precedence.
## How Skills Work: Progressive Disclosure
Skills leverage a **progressive disclosure** architecture—Claude loads information in stages as needed, rather than consuming context upfront. This enables efficient context management while maintaining unlimited scalability.
### Three Levels of Loading
```mermaid
graph TB
subgraph "Level 1: Metadata (Always Loaded)"
A["YAML Frontmatter"]
A1["~100 tokens per skill"]
A2["name + description"]
end
subgraph "Level 2: Instructions (When Triggered)"
B["SKILL.md Body"]
B1["Under 5k tokens"]
B2["Workflows & guidance"]
end
subgraph "Level 3: Resources (As Needed)"
C["Bundled Files"]
C1["Effectively unlimited"]
C2["Scripts, templates, docs"]
end
A --> B
B --> C
```
| Level | When Loaded | Token Cost | Content |
|-------|------------|------------|---------|
| **Level 1: Metadata** | Always (at startup) | ~100 tokens per Skill | `name` and `description` from YAML frontmatter |
| **Level 2: Instructions** | When Skill is triggered | Under 5k tokens | SKILL.md body with instructions and guidance |
| **Level 3+: Resources** | As needed | Effectively unlimited | Bundled files executed via bash without loading contents into context |
This means you can install many Skills without context penalty—Claude only knows each Skill exists and when to use it until actually triggered.
## Skill Loading Process
```mermaid
sequenceDiagram
participant User
participant Claude as Claude
participant System as System
participant Skill as Skill
User->>Claude: "Review this code for security issues"
Claude->>System: Check available skills (metadata)
System-->>Claude: Skill descriptions loaded at startup
Claude->>Claude: Match request to skill description
Claude->>Skill: bash: read code-review/SKILL.md
Skill-->>Claude: Instructions loaded into context
Claude->>Claude: Determine: Need templates?
Claude->>Skill: bash: read templates/checklist.md
Skill-->>Claude: Template loaded
Claude->>Claude: Execute skill instructions
Claude->>User: Comprehensive code review
```
## Skill Types & Locations
| Type | Location | Scope | Shared | Best For |
|------|----------|-------|--------|----------|
| **Enterprise** | Managed settings | All org users | Yes | Organization-wide standards |
| **Personal** | `~/.claude/skills/<skill-name>/SKILL.md` | Individual | No | Personal workflows |
| **Project** | `.claude/skills/<skill-name>/SKILL.md` | Team | Yes (via git) | Team standards |
| **Plugin** | `<plugin>/skills/<skill-name>/SKILL.md` | Where enabled | Depends | Bundled with plugins |
When skills share the same name across levels, higher-priority locations win: **enterprise > personal > project**. Plugin skills use a `plugin-name:skill-name` namespace, so they cannot conflict.
### Automatic Discovery
**Nested directories**: When you work with files in subdirectories, Claude Code automatically discovers skills from nested `.claude/skills/` directories. For example, if you're editing a file in `packages/frontend/`, Claude Code also looks for skills in `packages/frontend/.claude/skills/`. This supports monorepo setups where packages have their own skills.
**`--add-dir` directories**: Skills from directories added via `--add-dir` are loaded automatically with live change detection. Any edits to skill files in those directories take effect immediately without restarting Claude Code.
**Description budget**: Skill descriptions (Level 1 metadata) are capped at **2% of the context window** (fallback: **16,000 characters**). If you have many skills installed, some may be excluded. Run `/context` to check for warnings. Override the budget with the `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable.
## Creating Custom Skills
### Basic Directory Structure
```
my-skill/
├── SKILL.md # Main instructions (required)
├── template.md # Template for Claude to fill in
├── examples/
│ └── sample.md # Example output showing expected format
└── scripts/
└── validate.sh # Script Claude can execute
```
### SKILL.md Format
```yaml
---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---
# Your Skill Name
## Instructions
Provide clear, step-by-step guidance for Claude.
## Examples
Show concrete examples of using this Skill.
```
### Required Fields
- **name**: lowercase letters, numbers, hyphens only (max 64 characters). Cannot contain "anthropic" or "claude".
- **description**: what the Skill does AND when to use it (max 1024 characters). This is critical for Claude to know when to activate the skill.
### Optional Frontmatter Fields
```yaml
---
name: my-skill
description: What this skill does and when to use it
argument-hint: "[filename] [format]" # Hint for autocomplete
disable-model-invocation: true # Only user can invoke
user-invocable: false # Hide from slash menu
allowed-tools: Read, Grep, Glob # Restrict tool access
model: opus # Specific model to use
effort: high # Effort level override (low, medium, high, max)
context: fork # Run in isolated subagent
agent: Explore # Which agent type (with context: fork)
shell: bash # Shell for commands: bash (default) or powershell
hooks: # Skill-scoped hooks
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate.sh"
---
```
| Field | Description |
|-------|-------------|
| `name` | Lowercase letters, numbers, hyphens only (max 64 chars). Cannot contain "anthropic" or "claude". |
| `description` | What the Skill does AND when to use it (max 1024 chars). Critical for auto-invocation matching. |
| `argument-hint` | Hint shown in the `/` autocomplete menu (e.g., `"[filename] [format]"`). |
| `disable-model-invocation` | `true` = only the user can invoke via `/name`. Claude will never auto-invoke. |
| `user-invocable` | `false` = hidden from the `/` menu. Only Claude can invoke it automatically. |
| `allowed-tools` | Comma-separated list of tools the skill may use without permission prompts. |
| `model` | Model override while the skill is active (e.g., `opus`, `sonnet`). |
| `effort` | Effort level override while the skill is active: `low`, `medium`, `high`, or `max`. |
| `context` | `fork` to run the skill in a forked subagent context with its own context window. |
| `agent` | Subagent type when `context: fork` (e.g., `Explore`, `Plan`, `general-purpose`). |
| `shell` | Shell used for `!`command`` substitutions and scripts: `bash` (default) or `powershell`. |
| `hooks` | Hooks scoped to this skill's lifecycle (same format as global hooks). |
## Skill Content Types
Skills can contain two types of content, each suited for different purposes:
### Reference Content
Adds knowledge Claude applies to your current work—conventions, patterns, style guides, domain knowledge. Runs inline with your conversation context.
```yaml
---
name: api-conventions
description: API design patterns for this codebase
---
When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation
```
### Task Content
Step-by-step instructions for specific actions. Often invoked directly with `/skill-name`.
```yaml
---
name: deploy
description: Deploy the application to production
context: fork
disable-model-invocation: true
---
Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment target
```
## Controlling Skill Invocation
By default, both you and Claude can invoke any skill. Two frontmatter fields control the three invocation modes:
| Frontmatter | You can invoke | Claude can invoke |
|---|---|---|
| (default) | Yes | Yes |
| `disable-model-invocation: true` | Yes | No |
| `user-invocable: false` | No | Yes |
**Use `disable-model-invocation: true`** for workflows with side effects: `/commit`, `/deploy`, `/send-slack-message`. You don't want Claude deciding to deploy because your code looks ready.
**Use `user-invocable: false`** for background knowledge that isn't actionable as a command. A `legacy-system-context` skill explains how an old system works—useful for Claude, but not a meaningful action for users.
## String Substitutions
Skills support dynamic values that are resolved before the skill content reaches Claude:
| Variable | Description |
|----------|-------------|
| `$ARGUMENTS` | All arguments passed when invoking the skill |
| `$ARGUMENTS[N]` or `$N` | Access specific argument by index (0-based) |
| `${CLAUDE_SESSION_ID}` | Current session ID |
| `${CLAUDE_SKILL_DIR}` | Directory containing the skill's SKILL.md file |
| `` !`command` `` | Dynamic context injection — runs a shell command and inlines the output |
**Example:**
```yaml
---
name: fix-issue
description: Fix a GitHub issue
---
Fix GitHub issue $ARGUMENTS following our coding standards.
1. Read the issue description
2. Implement the fix
3. Write tests
4. Create a commit
```
Running `/fix-issue 123` replaces `$ARGUMENTS` with `123`.
## Injecting Dynamic Context
The `!`command`` syntax runs shell commands before the skill content is sent to Claude:
```yaml
---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
---
## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`
## Your task
Summarize this pull request...
```
Commands execute immediately; Claude only sees the final output. By default, commands run in `bash`. Set `shell: powershell` in frontmatter to use PowerShell instead.
## Running Skills in Subagents
Add `context: fork` to run a skill in an isolated subagent context. The skill content becomes the task for a dedicated subagent with its own context window, keeping the main conversation uncluttered.
The `agent` field specifies which agent type to use:
| Agent Type | Best For |
|---|---|
| `Explore` | Read-only research, codebase analysis |
| `Plan` | Creating implementation plans |
| `general-purpose` | Broad tasks requiring all tools |
| Custom agents | Specialized agents defined in your configuration |
**Example frontmatter:**
```yaml
---
context: fork
agent: Explore
---
```
**Full skill example:**
```yaml
---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---
Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references
```
## Practical Examples
### Example 1: Code Review Skill
**Directory Structure:**
```
~/.claude/skills/code-review/
├── SKILL.md
├── templates/
│ ├── review-checklist.md
│ └── finding-template.md
└── scripts/
├── analyze-metrics.py
└── compare-complexity.py
```
**File:** `~/.claude/skills/code-review/SKILL.md`
```yaml
---
name: code-review-specialist
description: Comprehensive code review with security, performance, and quality analysis. Use when users ask to review code, analyze code quality, evaluate pull requests, or mention code review, security analysis, or performance optimization.
---
# Code Review Skill
This skill provides comprehensive code review capabilities focusing on:
1. **Security Analysis**
- Authentication/authorization issues
- Data exposure risks
- Injection vulnerabilities
- Cryptographic weaknesses
2. **Performance Review**
- Algorithm efficiency (Big O analysis)
- Memory optimization
- Database query optimization
- Caching opportunities
3. **Code Quality**
- SOLID principles
- Design patterns
- Naming conventions
- Test coverage
4. **Maintainability**
- Code readability
- Function size (should be < 50 lines)
- Cyclomatic complexity
- Type safety
## Review Template
For each piece of code reviewed, provide:
### Summary
- Overall quality assessment (1-5)
- Key findings count
- Recommended priority areas
### Critical Issues (if any)
- **Issue**: Clear description
- **Location**: File and line number
- **Impact**: Why this matters
- **Severity**: Critical/High/Medium
- **Fix**: Code example
For detailed checklists, see [templates/review-checklist.md](templates/review-checklist.md).
```
### Example 2: Codebase Visualizer Skill
A skill that generates interactive HTML visualizations:
**Directory Structure:**
```
~/.claude/skills/codebase-visualizer/
├── SKILL.md
└── scripts/
└── visualize.py
```
**File:** `~/.claude/skills/codebase-visualizer/SKILL.md`
```yaml
---
name: codebase-visualizer
description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.
allowed-tools: Bash(python *)
---
# Codebase Visualizer
Generate an interactive HTML tree view showing your project's file structure.
## Usage
Run the visualization script from your project root:
```bash
python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .
```
This creates `codebase-map.html` and opens it in your default browser.
## What the visualization shows
- **Collapsible directories**: Click folders to expand/collapse
- **File sizes**: Displayed next to each file
- **Colors**: Different colors for different file types
- **Directory totals**: Shows aggregate size of each folder
```
The bundled Python script does the heavy lifting while Claude handles orchestration.
### Example 3: Deploy Skill (User-Invoked Only)
```yaml
---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
allowed-tools: Bash(npm *), Bash(git *)
---
Deploy $ARGUMENTS to production:
1. Run the test suite: `npm test`
2. Build the application: `npm run build`
3. Push to the deployment target
4. Verify the deployment succeeded
5. Report deployment status
```
### Example 4: Brand Voice Skill (Background Knowledge)
```yaml
---
name: brand-voice
description: Ensure all communication matches brand voice and tone guidelines. Use when creating marketing copy, customer communications, or public-facing content.
user-invocable: false
---
## Tone of Voice
- **Friendly but professional** - approachable without being casual
- **Clear and concise** - avoid jargon
- **Confident** - we know what we're doing
- **Empathetic** - understand user needs
## Writing Guidelines
- Use "you" when addressing readers
- Use active voice
- Keep sentences under 20 words
- Start with value proposition
For templates, see [templates/](templates/).
```
### Example 5: CLAUDE.md Generator Skill
```yaml
---
name: claude-md
description: Create or update CLAUDE.md files following best practices for optimal AI agent onboarding. Use when users mention CLAUDE.md, project documentation, or AI onboarding.
---
## Core Principles
**LLMs are stateless**: CLAUDE.md is the only file automatically included in every conversation.
### The Golden Rules
1. **Less is More**: Keep under 300 lines (ideally under 100)
2. **Universal Applicability**: Only include information relevant to EVERY session
3. **Don't Use Claude as a Linter**: Use deterministic tools instead
4. **Never Auto-Generate**: Craft it manually with careful consideration
## Essential Sections
- **Project Name**: Brief one-line description
- **Tech Stack**: Primary language, frameworks, database
- **Development Commands**: Install, test, build commands
- **Critical Conventions**: Only non-obvious, high-impact conventions
- **Known Issues / Gotchas**: Things that trip up developers
```
### Example 6: Refactoring Skill with Scripts
**Directory Structure:**
```
refactor/
├── SKILL.md
├── references/
│ ├── code-smells.md
│ └── refactoring-catalog.md
├── templates/
│ └── refactoring-plan.md
└── scripts/
├── analyze-complexity.py
└── detect-smells.py
```
**File:** `refactor/SKILL.md`
```yaml
---
name: code-refactor
description: Systematic code refactoring based on Martin Fowler's methodology. Use when users ask to refactor code, improve code structure, reduce technical debt, or eliminate code smells.
---
# Code Refactoring Skill
A phased approach emphasizing safe, incremental changes backed by tests.
## Workflow
Phase 1: Research & Analysis → Phase 2: Test Coverage Assessment →
Phase 3: Code Smell Identification → Phase 4: Refactoring Plan Creation →
Phase 5: Incremental Implementation → Phase 6: Review & Iteration
## Core Principles
1. **Behavior Preservation**: External behavior must remain unchanged
2. **Small Steps**: Make tiny, testable changes
3. **Test-Driven**: Tests are the safety net
4. **Continuous**: Refactoring is ongoing, not a one-time event
For code smell catalog, see [references/code-smells.md](references/code-smells.md).
For refactoring techniques, see [references/refactoring-catalog.md](references/refactoring-catalog.md).
```
## Supporting Files
Skills can include multiple files in their directory beyond `SKILL.md`. These supporting files (templates, examples, scripts, reference documents) let you keep the main skill file focused while providing Claude with additional resources it can load as needed.
```
my-skill/
├── SKILL.md # Main instructions (required, keep under 500 lines)
├── templates/ # Templates for Claude to fill in
│ └── output-format.md
├── examples/ # Example outputs showing expected format
│ └── sample-output.md
├── references/ # Domain knowledge and specifications
│ └── api-spec.md
└── scripts/ # Scripts Claude can execute
└── validate.sh
```
Guidelines for supporting files:
- Keep `SKILL.md` under **500 lines**. Move detailed reference material, large examples, and specifications to separate files.
- Reference additional files from `SKILL.md` using **relative paths** (e.g., `[API reference](references/api-spec.md)`).
- Supporting files are loaded at Level 3 (as needed), so they do not consume context until Claude actually reads them.
## Managing Skills
### Viewing Available Skills
Ask Claude directly:
```
What Skills are available?
```
Or check the filesystem:
```bash
# List personal Skills
ls ~/.claude/skills/
# List project Skills
ls .claude/skills/
```
### Testing a Skill
Two ways to test:
**Let Claude invoke it automatically** by asking something that matches the description:
```
Can you help me review this code for security issues?
```
**Or invoke it directly** with the skill name:
```
/code-review src/auth/login.ts
```
### Updating a Skill
Edit the `SKILL.md` file directly. Changes take effect on next Claude Code startup.
```bash
# Personal Skill
code ~/.claude/skills/my-skill/SKILL.md
# Project Skill
code .claude/skills/my-skill/SKILL.md
```
### Restricting Claude's Skill Access
Three ways to control which skills Claude can invoke:
**Disable all skills** in `/permissions`:
```
# Add to deny rules:
Skill
```
**Allow or deny specific skills**:
```
# Allow only specific skills
Skill(commit)
Skill(review-pr *)
# Deny specific skills
Skill(deploy *)
```
**Hide individual skills** by adding `disable-model-invocation: true` to their frontmatter.
## Best Practices
### 1. Make Descriptions Specific
- **Bad (Vague)**: "Helps with documents"
- **Good (Specific)**: "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."
### 2. Keep Skills Focused
- One Skill = one capability
- ✅ "PDF form filling"
- ❌ "Document processing" (too broad)
### 3. Include Trigger Terms
Add keywords in descriptions that match user requests:
```yaml
description: Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with Excel files, spreadsheets, or .xlsx files.
```
### 4. Keep SKILL.md Under 500 Lines
Move detailed reference material to separate files that Claude loads as needed.
### 5. Reference Supporting Files
```markdown
## Additional resources
- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)
```
### Do's
- Use clear, descriptive names
- Include comprehensive instructions
- Add concrete examples
- Package related scripts and templates
- Test with real scenarios
- Document dependencies
### Don'ts
- Don't create skills for one-time tasks
- Don't duplicate existing functionality
- Don't make skills too broad
- Don't skip the description field
- Don't install skills from untrusted sources without auditing
## Troubleshooting
### Quick Reference
| Issue | Solution |
|-------|----------|
| Claude doesn't use Skill | Make description more specific with trigger terms |
| Skill file not found | Verify path: `~/.claude/skills/name/SKILL.md` |
| YAML errors | Check `---` markers, indentation, no tabs |
| Skills conflict | Use distinct trigger terms in descriptions |
| Scripts not running | Check permissions: `chmod +x scripts/*.py` |
| Claude doesn't see all skills | Too many skills; check `/context` for warnings |
### Skill Not Triggering
If Claude doesn't use your skill when expected:
1. Check the description includes keywords users would naturally say
2. Verify the skill appears when asking "What skills are available?"
3. Try rephrasing your request to match the description
4. Invoke directly with `/skill-name` to test
### Skill Triggers Too Often
If Claude uses your skill when you don't want it:
1. Make the description more specific
2. Add `disable-model-invocation: true` for manual-only invocation
### Claude Doesn't See All Skills
Skill descriptions are loaded at **2% of the context window** (fallback: **16,000 characters**). Run `/context` to check for warnings about excluded skills. Override the budget with the `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable.
## Security Considerations
**Only use Skills from trusted sources.** Skills provide Claude with capabilities through instructions and code—a malicious Skill can direct Claude to invoke tools or execute code in harmful ways.
**Key security considerations:**
- **Audit thoroughly**: Review all files in the Skill directory
- **External sources are risky**: Skills that fetch from external URLs can be compromised
- **Tool misuse**: Malicious Skills can invoke tools in harmful ways
- **Treat like installing software**: Only use Skills from trusted sources
## Skills vs Other Features
| Feature | Invocation | Best For |
|---------|------------|----------|
| **Skills** | Auto or `/name` | Reusable expertise, workflows |
| **Slash Commands** | User-initiated `/name` | Quick shortcuts (merged into skills) |
| **Subagents** | Auto-delegated | Isolated task execution |
| **Memory (CLAUDE.md)** | Always loaded | Persistent project context |
| **MCP** | Real-time | External data/service access |
| **Hooks** | Event-driven | Automated side effects |
## Bundled Skills
Claude Code ships with several built-in skills that are always available without installation:
| Skill | Description |
|-------|-------------|
| `/simplify` | Review changed files for reuse, quality, and efficiency; spawns 3 parallel review agents |
| `/batch <instruction>` | Orchestrate large-scale parallel changes across codebase using git worktrees |
| `/debug [description]` | Troubleshoot current session by reading debug log |
| `/loop [interval] <prompt>` | Run prompt repeatedly on interval (e.g., `/loop 5m check the deploy`) |
| `/claude-api` | Load Claude API/SDK reference; auto-activates on `anthropic`/`@anthropic-ai/sdk` imports |
These skills are available out-of-the-box and do not need to be installed or configured. They follow the same SKILL.md format as custom skills.
## Sharing Skills
### Project Skills (Team Sharing)
1. Create Skill in `.claude/skills/`
2. Commit to git
3. Team members pull changes — Skills available immediately
### Personal Skills
```bash
# Copy to personal directory
cp -r my-skill ~/.claude/skills/
# Make scripts executable
chmod +x ~/.claude/skills/my-skill/scripts/*.py
```
### Plugin Distribution
Package skills in a plugin's `skills/` directory for broader distribution.
## Going Further: A Skill Collection and a Skill Manager
Once you start building skills seriously, two things become essential: a library of proven skills and a tool to manage them.
**[luongnv89/skills](https://github.com/luongnv89/skills)** — A collection of skills I use daily across almost all my projects. Highlights include `logo-designer` (generates project logos on the fly) and `ollama-optimizer` (tunes local LLM performance for your hardware). Great starting point if you want ready-to-use skills.
**[luongnv89/asm](https://github.com/luongnv89/asm)** — Agent Skill Manager. Handles skill development, duplicate detection, and testing. The `asm link` command lets you test a skill in any project without copying files around — essential once you have more than a handful of skills.
## Additional Resources
- [Official Skills Documentation](https://code.claude.com/docs/en/skills)
- [Agent Skills Architecture Blog](https://claude.com/blog/equipping-agents-for-the-real-world-with-agent-skills)
- [Skills Repository](https://github.com/luongnv89/skills) - Collection of ready-to-use skills
- [Slash Commands Guide](../01-slash-commands/) - User-initiated shortcuts
- [Subagents Guide](../04-subagents/) - Delegated AI agents
- [Memory Guide](../02-memory/) - Persistent context
- [MCP (Model Context Protocol)](../05-mcp/) - Real-time external data
- [Hooks Guide](../06-hooks/) - Event-driven automation
================================================
FILE: 03-skills/blog-draft/SKILL.md
================================================
---
name: blog-draft
description: Draft a blog post from ideas and resources. Use when users want to write a blog post, create content from research, or draft articles. Guides through research, brainstorming, outlining, and iterative drafting with version control.
---
## User Input
```text
$ARGUMENTS
```
You **MUST** consider the user input before proceeding. User should provide:
- **Idea/Topic**: The main concept or theme for the blog post
- **Resources**: URLs, files, or references to research (optional but recommended)
- **Target audience**: Who the blog post is for (optional)
- **Tone/Style**: Formal, casual, technical, etc. (optional)
**IMPORTANT**: If the user is requesting updates to an **existing blog post**, skip steps 0-8 and start directly at **Step 9**. Read the existing draft file(s) first, then proceed with the iteration process.
## Execution Flow
Follow these steps sequentially. **Do not skip steps or proceed without user approval where indicated.**
### Step 0: Create Project Folder
1. Generate a folder name using format: `YYYY-MM-DD-short-topic-name`
- Use today's date
- Create a short, URL-friendly slug from the topic (lowercase, hyphens, max 5 words)
2. Create the folder structure:
```
blog-posts/
└── YYYY-MM-DD-short-topic-name/
└── resources/
```
3. Confirm folder creation with user before proceeding.
### Step 1: Research & Resource Collection
1. Create `resources/` subfolder in the blog post directory
2. For each provided resource:
- **URLs**: Fetch and save key information to `resources/` as markdown files
- **Files**: Read and summarize in `resources/`
- **Topics**: Use web search to gather up-to-date information
3. For each resource, create a summary file in `resources/`:
- `resources/source-1-[short-name].md`
- `resources/source-2-[short-name].md`
- etc.
4. Each summary should include:
```markdown
# Source: [Title/URL]
## Key Points
- Point 1
- Point 2
## Relevant Quotes/Data
- Quote or statistic 1
- Quote or statistic 2
## How This Relates to Topic
Brief explanation of relevance
```
5. Present research summary to user.
### Step 2: Brainstorm & Clarify
1. Based on the idea and researched resources, present:
- **Main themes** identified from research
- **Potential angles** for the blog post
- **Key points** that should be covered
- **Gaps** in information that need clarification
2. Ask clarifying questions:
- What is the main takeaway you want readers to have?
- Are there specific points from the research you want to emphasize?
- What's the target length? (short: 500-800 words, medium: 1000-1500, long: 2000+)
- Any points you want to exclude?
3. **Wait for user responses before proceeding.**
### Step 3: Propose Outline
1. Create a structured outline including:
```markdown
# Blog Post Outline: [Title]
## Meta Information
- **Target Audience**: [who]
- **Tone**: [style]
- **Target Length**: [word count]
- **Main Takeaway**: [key message]
## Proposed Structure
### Hook/Introduction
- Opening hook idea
- Context setting
- Thesis statement
### Section 1: [Title]
- Key point A
- Key point B
- Supporting evidence from [source]
### Section 2: [Title]
- Key point A
- Key point B
[Continue for all sections...]
### Conclusion
- Summary of key points
- Call to action or final thought
## Sources to Cite
- Source 1
- Source 2
```
2. Present outline to user and **ask for approval or modifications**.
### Step 4: Save Approved Outline
1. Once user approves the outline, save it to `OUTLINE.md` in the blog post folder.
2. Confirm the outline has been saved.
### Step 5: Commit Outline (if in git repo)
1. Check if current directory is a git repository.
2. If yes:
- Stage the new files: blog post folder, resources, and OUTLINE.md
- Create commit with message: `docs: Add outline for blog post - [topic-name]`
- Push to remote
3. If not a git repo, skip this step and inform user.
### Step 6: Write Draft
1. Based on the approved outline, write the full blog post draft.
2. Follow the structure from OUTLINE.md exactly.
3. Include:
- Engaging introduction with hook
- Clear section headers
- Supporting evidence and examples from research
- Smooth transitions between sections
- Strong conclusion with takeaway
- **Citations**: All comparisons, statistics, data points, and factual claims MUST cite the original source
4. Save the draft as `draft-v0.1.md` in the blog post folder.
5. Format:
```markdown
# [Blog Post Title]
*[Optional: subtitle or tagline]*
[Full content with inline citations...]
---
## References
- [1] Source 1 Title - URL or Citation
- [2] Source 2 Title - URL or Citation
- [3] Source 3 Title - URL or Citation
```
6. **Citation Requirements**:
- Every data point, statistic, or comparison MUST have an inline citation
- Use numbered references [1], [2], etc., or named citations [Source Name]
- Link citations to the References section at the end
- Example: "Studies show that 65% of developers prefer TypeScript [1]"
- Example: "React outperforms Vue in rendering speed by 20% [React Benchmarks 2024]"
### Step 7: Commit Draft (if in git repo)
1. Check if in git repository.
2. If yes:
- Stage the draft file
- Create commit with message: `docs: Add draft v0.1 for blog post - [topic-name]`
- Push to remote
3. If not a git repo, skip and inform user.
### Step 8: Present Draft for Review
1. Present the draft content to user.
2. Ask for feedback:
- Overall impression?
- Sections that need expansion or reduction?
- Tone adjustments needed?
- Missing information?
- Specific edits or rewrites?
3. **Wait for user response.**
### Step 9: Iterate or Finalize
**If user requests changes:**
1. Note all requested modifications
2. Return to Step 6 with the following adjustments:
- Increment version number (v0.2, v0.3, etc.)
- Incorporate all feedback
- Save as `draft-v[X.Y].md`
- Repeat Steps 7-8
**If user approves:**
1. Confirm the final draft version
2. Optionally rename to `final.md` if user requests
3. Summarize the blog post creation process:
- Total versions created
- Key changes between versions
- Final word count
- Files created
## Version Tracking
All drafts are preserved with incremental versioning:
- `draft-v0.1.md` - Initial draft
- `draft-v0.2.md` - After first round of feedback
- `draft-v0.3.md` - After second round of feedback
- etc.
This allows tracking the evolution of the blog post and reverting if needed.
## Output Files Structure
```
blog-posts/
└── YYYY-MM-DD-topic-name/
├── resources/
│ ├── source-1-name.md
│ ├── source-2-name.md
│ └── ...
├── OUTLINE.md
├── draft-v0.1.md
├── draft-v0.2.md (if iterations)
└── draft-v0.3.md (if more iterations)
```
## Tips for Quality
- **Hook**: Start with a question, surprising fact, or relatable scenario
- **Flow**: Each paragraph should connect to the next
- **Evidence**: Support claims with data from research
- **Citations**: ALWAYS cite sources for:
- All statistics and data points (e.g., "According to [Source], 75% of...")
- Comparisons between products, services, or approaches (e.g., "X performs 2x faster than Y [Source]")
- Factual claims about market trends, research findings, or benchmarks
- Use inline citations with format: [Source Name] or [Author, Year]
- **Voice**: Maintain consistent tone throughout
- **Length**: Respect the target word count
- **Readability**: Use short paragraphs, bullet points where appropriate
- **CTA**: End with a clear call-to-action or thought-provoking question
## Notes
- Always wait for user approval at outlined checkpoints
- Preserve all draft versions for history
- Use web search for up-to-date information when URLs are provided
- If resources are insufficient, ask user for more or suggest additional research
- Adapt tone based on target audience (technical, general, business, etc.)
================================================
FILE: 03-skills/blog-draft/templates/draft-template.md
================================================
# [Blog Post Title]
*[Subtitle or tagline - optional]*
**[Author Name]** | [Date]
---
[Opening hook - grab attention immediately]
[Context and background - why this matters]
[Thesis statement - what this post will cover]
---
## [Section 1 Title]
[Section content with clear, engaging prose]
[Include evidence, examples, or data to support points]
> "Relevant quote from research" - Source
[Transition to next section]
---
## [Section 2 Title]
[Continue with main content]
**Key takeaway:** [Highlight important points in bold or callout boxes]
[More supporting content]
---
## [Section 3 Title]
[Additional sections as needed]
### Subsection (if needed)
[Subsection content]
---
## Conclusion
[Summarize the key points covered]
[Reinforce the main takeaway]
[Call to action or thought-provoking final statement]
---
## References
1. [Source Title](#)
2. [Source Title](#)
3. [Source Title](#)
---
*[Optional: Author bio or related posts suggestion]*
================================================
FILE: 03-skills/blog-draft/templates/outline-template.md
================================================
# Blog Post Outline: [Title]
## Meta Information
| Attribute | Value |
|-----------|-------|
| **Target Audience** | [Who is this for?] |
| **Tone** | [Formal/Casual/Technical/Conversational] |
| **Target Length** | [Word count range] |
| **Main Takeaway** | [One sentence: what should readers remember?] |
| **Keywords** | [SEO keywords if relevant] |
---
## Proposed Structure
### 1. Introduction / Hook
**Opening Hook Options:**
- [ ] Question that resonates with reader
- [ ] Surprising statistic or fact
- [ ] Brief story or scenario
- [ ] Bold statement
**Context Setting:**
- Background information needed
- Why this topic matters now
**Thesis Statement:**
- Clear statement of what the post will cover
---
### 2. [Section Title]
**Key Points:**
- Point A: [description]
- Point B: [description]
**Supporting Evidence:**
- From [source]: [relevant data/quote]
**Transition to next section:**
- [How this connects to what's next]
---
### 3. [Section Title]
**Key Points:**
- Point A: [description]
- Point B: [description]
**Supporting Evidence:**
- From [source]: [relevant data/quote]
**Transition to next section:**
- [How this connects to what's next]
---
### 4. [Section Title] (add more sections as needed)
**Key Points:**
- Point A: [description]
- Point B: [description]
**Supporting Evidence:**
- From [source]: [relevant data/quote]
---
### 5. Conclusion
**Summary of Key Points:**
- Recap point 1
- Recap point 2
- Recap point 3
**Final Thought / Call to Action:**
- [What should readers do or think about next?]
---
## Sources to Cite
1. [Source Name](#) - Used for: [what information]
2. [Source Name](#) - Used for: [what information]
3. [Source Name](#) - Used for: [what information]
---
## Notes for Drafting
- [Any specific requirements or constraints]
- [Things to emphasize]
- [Things to avoid]
================================================
FILE: 03-skills/brand-voice/SKILL.md
================================================
---
name: brand-voice-consistency
description: Ensure all communication matches brand voice and tone guidelines. Use when creating marketing copy, customer communications, public-facing content, or when users mention brand voice, tone, or writing style.
---
# Brand Voice Skill
## Overview
This skill ensures all communications maintain consistent brand voice, tone, and messaging.
## Brand Identity
### Mission
Help teams automate their development workflows with AI
### Values
- **Simplicity**: Make complex things simple
- **Reliability**: Rock-solid execution
- **Empowerment**: Enable human creativity
### Tone of Voice
- **Friendly but professional** - approachable without being casual
- **Clear and concise** - avoid jargon, explain technical concepts simply
- **Confident** - we know what we're doing
- **Empathetic** - understand user needs and pain points
## Writing Guidelines
### Do's ✅
- Use "you" when addressing readers
- Use active voice: "Claude generates reports" not "Reports are generated by Claude"
- Start with value proposition
- Use concrete examples
- Keep sentences under 20 words
- Use lists for clarity
- Include calls-to-action
### Don'ts ❌
- Don't use corporate jargon
- Don't patronize or oversimplify
- Don't use "we believe" or "we think"
- Don't use ALL CAPS except for emphasis
- Don't create walls of text
- Don't assume technical knowledge
## Vocabulary
### ✅ Preferred Terms
- Claude (not "the Claude AI")
- Code generation (not "auto-coding")
- Agent (not "bot")
- Streamline (not "revolutionize")
- Integrate (not "synergize")
### ❌ Avoid Terms
- "Cutting-edge" (overused)
- "Game-changer" (vague)
- "Leverage" (corporate-speak)
- "Utilize" (use "use")
- "Paradigm shift" (unclear)
## Examples
### ✅ Good Example
"Claude automates your code review process. Instead of manually checking each PR, Claude reviews security, performance, and quality—saving your team hours every week."
Why it works: Clear value, specific benefits, action-oriented
### ❌ Bad Example
"Claude leverages cutting-edge AI to provide comprehensive software development solutions."
Why it doesn't work: Vague, corporate jargon, no specific value
================================================
FILE: 03-skills/brand-voice/templates/email-template.txt
================================================
Subject: [Clear, benefit-driven subject]
Hi [Name],
[Opening: What's the value for them]
[Body: How it works / What they'll get]
[Specific example or benefit]
[Call to action: Clear next step]
Best regards,
[Name]
================================================
FILE: 03-skills/brand-voice/templates/social-post-template.txt
================================================
[Hook: Grab attention in first line]
[2-3 lines: Value or interesting fact]
[Call to action: Link, question, or engagement]
[Emoji: 1-2 max for visual interest]
================================================
FILE: 03-skills/brand-voice/tone-examples.md
================================================
# Brand Voice Tone Examples
## Exciting Announcement
"Save 8 hours per week on code reviews. Claude reviews your PRs automatically."
## Empathetic Support
"We know deployments can be stressful. Claude handles testing so you don't have to worry."
## Confident Product Feature
"Claude doesn't just suggest code. It understands your architecture and maintains consistency."
## Educational Blog Post
"Let's explore how agents improve code review workflows. Here's what we learned..."
================================================
FILE: 03-skills/claude-md/SKILL.md
================================================
---
name: claude-md
description: Create or update CLAUDE.md files following best practices for optimal AI agent onboarding
---
## User Input
```text
$ARGUMENTS
```
You **MUST** consider the user input before proceeding (if not empty). User may specify:
- `create` - Create new CLAUDE.md from scratch
- `update` - Improve existing CLAUDE.md
- `audit` - Analyze and report on current CLAUDE.md quality
- A specific path to create/update (e.g., `src/api/CLAUDE.md` for directory-specific instructions)
## Core Principles
**LLMs are stateless**: CLAUDE.md is the only file automatically included in every conversation. It serves as the primary onboarding document for AI agents into your codebase.
### The Golden Rules
1. **Less is More**: Frontier LLMs can follow ~150-200 instructions. Claude Code's system prompt already uses ~50. Keep your CLAUDE.md focused and concise.
2. **Universal Applicability**: Only include information relevant to EVERY session. Task-specific instructions belong in separate files.
3. **Don't Use Claude as a Linter**: Style guidelines bloat context and degrade instruction-following. Use deterministic tools (prettier, eslint, etc.) instead.
4. **Never Auto-Generate**: CLAUDE.md is the highest leverage point of the AI harness. Craft it manually with careful consideration.
## Execution Flow
### 1. Project Analysis
First, analyze the current project state:
1. Check for existing CLAUDE.md files:
- Root level: `./CLAUDE.md` or `.claude/CLAUDE.md`
- Directory-specific: `**/CLAUDE.md`
- Global user config: `~/.claude/CLAUDE.md`
2. Identify the project structure:
- Technology stack (languages, frameworks)
- Project type (monorepo, single app, library)
- Development tools (package manager, build system, test runner)
3. Review existing documentation:
- README.md
- CONTRIBUTING.md
- package.json, pyproject.toml, Cargo.toml, etc.
### 2. Content Strategy (WHAT, WHY, HOW)
Structure CLAUDE.md around three dimensions:
#### WHAT - Technology & Structure
- Technology stack overview
- Project organization (especially important for monorepos)
- Key directories and their purposes
#### WHY - Purpose & Context
- What the project does
- Why certain architectural decisions were made
- What each major component is responsible for
#### HOW - Workflow & Conventions
- Development workflow (bun vs node, pip vs uv, etc.)
- Testing procedures and commands
- Verification and build methods
- Critical "gotchas" or non-obvious requirements
### 3. Progressive Disclosure Strategy
For larger projects, recommend creating an `agent_docs/` folder:
```
agent_docs/
|- building_the_project.md
|- running_tests.md
|- code_conventions.md
|- architecture_decisions.md
```
In CLAUDE.md, reference these files with instructions like:
```markdown
For detailed build instructions, refer to `agent_docs/building_the_project.md`
```
**Important**: Use `file:line` references instead of code snippets to avoid outdated context.
### 4. Quality Constraints
When creating or updating CLAUDE.md:
1. **Target Length**: Under 300 lines (ideally under 100)
2. **No Style Rules**: Remove any linting/formatting instructions
3. **No Task-Specific Instructions**: Move to separate files
4. **No Code Snippets**: Use file references instead
5. **No Redundant Information**: Don't repeat what's in package.json or README
### 5. Essential Sections
A well-structured CLAUDE.md should include:
```markdown
# Project Name
Brief one-line description.
## Tech Stack
- Primary language and version
- Key frameworks/libraries
- Database/storage (if any)
## Project Structure
[Only for monorepos or complex structures]
- `apps/` - Application entry points
- `packages/` - Shared libraries
## Development Commands
- Install: `command`
- Test: `command`
- Build: `command`
## Critical Conventions
[Only non-obvious, high-impact conventions]
- Convention 1 with brief explanation
- Convention 2 with brief explanation
## Known Issues / Gotchas
[Things that consistently trip up developers]
- Issue 1
- Issue 2
```
### 6. Anti-Patterns to Avoid
**DO NOT include:**
- Code style guidelines (use linters)
- Documentation on how to use Claude
- Long explanations of obvious patterns
- Copy-pasted code examples
- Generic best practices ("write clean code")
- Instructions for specific tasks
- Auto-generated content
- Extensive TODO lists
### 7. Validation Checklist
Before finalizing, verify:
- [ ] Under 300 lines (preferably under 100)
- [ ] Every line applies to ALL sessions
- [ ] No style/formatting rules
- [ ] No code snippets (use file references)
- [ ] Commands are verified to work
- [ ] Progressive disclosure used for complex projects
- [ ] Critical gotchas are documented
- [ ] No redundancy with README.md
## Output Format
### For `create` or default:
1. Analyze the project
2. Draft a CLAUDE.md following the structure above
3. Present the draft for review
4. Write to the appropriate location after approval
### For `update`:
1. Read existing CLAUDE.md
2. Audit against best practices
3. Identify:
- Content to remove (style rules, code snippets, task-specific)
- Content to condense
- Missing essential information
4. Present changes for review
5. Apply changes after approval
### For `audit`:
1. Read existing CLAUDE.md
2. Generate a report with:
- Current line count vs target
- Percentage of universally-applicable content
- List of anti-patterns found
- Recommendations for improvement
3. Do NOT modify the file, only report
## AGENTS.md Handling
If the user requests AGENTS.md creation/update:
AGENTS.md is used for defining specialized agent behaviors. Unlike CLAUDE.md (which is for project context), AGENTS.md defines:
- Custom agent roles and capabilities
- Agent-specific instructions and constraints
- Workflow definitions for multi-agent scenarios
Apply similar principles:
- Keep focused and concise
- Use progressive disclosure
- Reference external docs instead of embedding content
## Notes
- Always verify commands work before including them
- When in doubt, leave it out - less is more
- The system reminder tells Claude that CLAUDE.md "may or may not be relevant" - the more noise, the more it gets ignored
- Monorepos benefit most from clear WHAT/WHY/HOW structure
- Directory-specific CLAUDE.md files should be even more focused
================================================
FILE: 03-skills/code-review/SKILL.md
================================================
---
name: code-review-specialist
description: Comprehensive code review with security, performance, and quality analysis. Use when users ask to review code, analyze code quality, evaluate pull requests, or mention code review, security analysis, or performance optimization.
---
# Code Review Skill
This skill provides comprehensive code review capabilities focusing on:
1. **Security Analysis**
- Authentication/authorization issues
- Data exposure risks
- Injection vulnerabilities
- Cryptographic weaknesses
- Sensitive data logging
2. **Performance Review**
- Algorithm efficiency (Big O analysis)
- Memory optimization
- Database query optimization
- Caching opportunities
- Concurrency issues
3. **Code Quality**
- SOLID principles
- Design patterns
- Naming conventions
- Documentation
- Test coverage
4. **Maintainability**
- Code readability
- Function size (should be < 50 lines)
- Cyclomatic complexity
- Dependency management
- Type safety
## Review Template
For each piece of code reviewed, provide:
### Summary
- Overall quality assessment (1-5)
- Key findings count
- Recommended priority areas
### Critical Issues (if any)
- **Issue**: Clear description
- **Location**: File and line number
- **Impact**: Why this matters
- **Severity**: Critical/High/Medium
- **Fix**: Code example
### Findings by Category
#### Security (if issues found)
List security vulnerabilities with examples
#### Performance (if issues found)
List performance problems with complexity analysis
#### Quality (if issues found)
List code quality issues with refactoring suggestions
#### Maintainability (if issues found)
List maintainability problems with improvements
## Version History
- v1.0.0 (2024-12-10): Initial release with security, performance, quality, and maintainability analysis
================================================
FILE: 03-skills/code-review/scripts/analyze-metrics.py
================================================
#!/usr/bin/env python3
import re
import sys
def analyze_code_metrics(code):
"""Analyze code for common metrics."""
# Count functions
functions = len(re.findall(r"^def\s+\w+", code, re.MULTILINE))
# Count classes
classes = len(re.findall(r"^class\s+\w+", code, re.MULTILINE))
# Average line length
lines = code.split("\n")
avg_length = sum(len(l) for l in lines) / len(lines) if lines else 0
# Estimate complexity
complexity = len(re.findall(r"\b(if|elif|else|for|while|and|or)\b", code))
return {
"functions": functions,
"classes": classes,
"avg_line_length": avg_length,
"complexity_score": complexity,
}
if __name__ == "__main__":
with open(sys.argv[1]) as f:
code = f.read()
metrics = analyze_code_metrics(code)
for key, value in metrics.items():
print(f"{key}: {value:.2f}")
================================================
FILE: 03-skills/code-review/scripts/compare-complexity.py
================================================
#!/usr/bin/env python3
"""
Compare cyclomatic complexity of code before and after changes.
Helps identify if refactoring actually simplifies code structure.
"""
import re
import sys
class ComplexityAnalyzer:
"""Analyze code complexity metrics."""
def __init__(self, code: str):
self.code = code
self.lines = code.split("\n")
def calculate_cyclomatic_complexity(self) -> int:
"""
Calculate cyclomatic complexity using McCabe's method.
Count decision points: if, elif, else, for, while, except, and, or
"""
complexity = 1 # Base complexity
# Count decision points
decision_patterns = [
r"\bif\b",
r"\belif\b",
r"\bfor\b",
r"\bwhile\b",
r"\bexcept\b",
r"\band\b(?!$)",
r"\bor\b(?!$)",
]
for pattern in decision_patterns:
matches = re.findall(pattern, self.code)
complexity += len(matches)
return complexity
def calculate_cognitive_complexity(self) -> int:
"""
Calculate cognitive complexity - how hard is it to understand?
Based on nesting depth and control flow.
"""
cognitive = 0
nesting_depth = 0
for line in self.lines:
# Track nesting depth
if re.search(r"^\s*(if|for|while|def|class|try)\b", line):
nesting_depth += 1
cognitive += nesting_depth
elif re.search(r"^\s*(elif|else|except|finally)\b", line):
cognitive += nesting_depth
# Reduce nesting when unindenting
if line and not line[0].isspace():
nesting_depth = 0
return cognitive
def calculate_maintainability_index(self) -> float:
"""
Maintainability Index ranges from 0-100.
> 85: Excellent
> 65: Good
> 50: Fair
< 50: Poor
"""
lines = len(self.lines)
cyclomatic = self.calculate_cyclomatic_complexity()
cognitive = self.calculate_cognitive_complexity()
# Simplified MI calculation
mi = (
171
- 5.2 * (cyclomatic / lines)
- 0.23 * (cognitive)
- 16.2 * (lines / 1000)
)
return max(0, min(100, mi))
def get_complexity_report(self) -> dict:
"""Generate comprehensive complexity report."""
return {
"cyclomatic_complexity": self.calculate_cyclomatic_complexity(),
"cognitive_complexity": self.calculate_cognitive_complexity(),
"maintainability_index": round(self.calculate_maintainability_index(), 2),
"lines_of_code": len(self.lines),
"avg_line_length": round(
sum(len(l) for l in self.lines) / len(self.lines), 2
)
if self.lines
else 0,
}
def compare_files(before_file: str, after_file: str) -> None:
"""Compare complexity metrics between two code versions."""
with open(before_file) as f:
before_code = f.read()
with open(after_file) as f:
after_code = f.read()
before_analyzer = ComplexityAnalyzer(before_code)
after_analyzer = ComplexityAnalyzer(after_code)
before_metrics = before_analyzer.get_complexity_report()
after_metrics = after_analyzer.get_complexity_report()
print("=" * 60)
print("CODE COMPLEXITY COMPARISON")
print("=" * 60)
print("\nBEFORE:")
print(f" Cyclomatic Complexity: {before_metrics['cyclomatic_complexity']}")
print(f" Cognitive Complexity: {before_metrics['cognitive_complexity']}")
print(f" Maintainability Index: {before_metrics['maintainability_index']}")
print(f" Lines of Code: {before_metrics['lines_of_code']}")
print(f" Avg Line Length: {before_metrics['avg_line_length']}")
print("\nAFTER:")
print(f" Cyclomatic Complexity: {after_metrics['cyclomatic_complexity']}")
print(f" Cognitive Complexity: {after_metrics['cognitive_complexity']}")
print(f" Maintainability Index: {after_metrics['maintainability_index']}")
print(f" Lines of Code: {after_metrics['lines_of_code']}")
print(f" Avg Line Length: {after_metrics['avg_line_length']}")
print("\nCHANGES:")
cyclomatic_change = (
after_metrics["cyclomatic_complexity"] - before_metrics["cyclomatic_complexity"]
)
cognitive_change = (
after_metrics["cognitive_complexity"] - before_metrics["cognitive_complexity"]
)
mi_change = (
after_metrics["maintainability_index"] - before_metrics["maintainability_index"]
)
loc_change = after_metrics["lines_of_code"] - before_metrics["lines_of_code"]
print(f" Cyclomatic Complexity: {cyclomatic_change:+d}")
print(f" Cognitive Complexity: {cognitive_change:+d}")
print(f" Maintainability Index: {mi_change:+.2f}")
print(f" Lines of Code: {loc_change:+d}")
print("\nASSESSMENT:")
if mi_change > 0:
print(" ✅ Code is MORE maintainable")
elif mi_change < 0:
print(" ⚠️ Code is LESS maintainable")
else:
print(" ➡️ Maintainability unchanged")
if cyclomatic_change < 0:
print(" ✅ Complexity DECREASED")
elif cyclomatic_change > 0:
print(" ⚠️ Complexity INCREASED")
else:
print(" ➡️ Complexity unchanged")
print("=" * 60)
if __name__ == "__main__":
if len(sys.argv) != 3:
print("Usage: python compare-complexity.py <before_file> <after_file>")
sys.exit(1)
compare_files(sys.argv[1], sys.argv[2])
================================================
FILE: 03-skills/code-review/templates/finding-template.md
================================================
# Code Review Finding Template
Use this template when documenting each issue found during code review.
---
## Issue: [TITLE]
### Severity
- [ ] Critical (blocks deployment)
- [ ] High (should fix before merge)
- [ ] Medium (should fix soon)
- [ ] Low (nice to have)
### Category
- [ ] Security
- [ ] Performance
- [ ] Code Quality
- [ ] Maintainability
- [ ] Testing
- [ ] Design Pattern
- [ ] Documentation
### Location
**File:** `src/components/UserCard.tsx`
**Lines:** 45-52
**Function/Method:** `renderUserDetails()`
### Issue Description
**What:** Describe what the issue is.
**Why it matters:** Explain the impact and why this needs to be fixed.
**Current behavior:** Show the problematic code or behavior.
**Expected behavior:** Describe what should happen instead.
### Code Example
#### Current (Problematic)
```typescript
// Shows the N+1 query problem
const users = fetchUsers();
users.forEach(user => {
const posts = fetchUserPosts(user.id); // Query per user!
renderUserPosts(posts);
});
```
#### Suggested Fix
```typescript
// Optimized with JOIN query
const usersWithPosts = fetchUsersWithPosts();
usersWithPosts.forEach(({ user, posts }) => {
renderUserPosts(posts);
});
```
### Impact Analysis
| Aspect | Impact | Severity |
|--------|--------|----------|
| Performance | 100+ queries for 20 users | High |
| User Experience | Slow page load | High |
| Scalability | Breaks at scale | Critical |
| Maintainability | Hard to debug | Medium |
### Related Issues
- Similar issue in `AdminUserList.tsx` line 120
- Related PR: #456
- Related issue: #789
### Additional Resources
- [N+1 Query Problem](https://en.wikipedia.org/wiki/N%2B1_problem)
- [Database Join Documentation](https://docs.example.com/joins)
- [Performance Optimization Guide](./docs/performance.md)
### Reviewer Notes
- This is a common pattern in this codebase
- Consider adding this to the code style guide
- Might be worth creating a helper function
### Author Response (for feedback)
*To be filled by the code author:*
- [ ] Fix implemented in commit: `abc123`
- [ ] Fix status: Complete / In Progress / Needs Discussion
- [ ] Questions or concerns: (describe)
---
## Finding Statistics (for Reviewer)
When reviewing multiple findings, track:
- **Total Issues Found:** X
- **Critical:** X
- **High:** X
- **Medium:** X
- **Low:** X
**Recommendation:** ✅ Approve / ⚠️ Request Changes / 🔄 Needs Discussion
**Overall Code Quality:** 1-5 stars
================================================
FILE: 03-skills/code-review/templates/review-checklist.md
================================================
# Code Review Checklist
## Security Checklist
- [ ] No hardcoded credentials or secrets
- [ ] Input validation on all user inputs
- [ ] SQL injection prevention (parameterized queries)
- [ ] CSRF protection on state-changing operations
- [ ] XSS prevention with proper escaping
- [ ] Authentication checks on protected endpoints
- [ ] Authorization checks on resources
- [ ] Secure password hashing (bcrypt, argon2)
- [ ] No sensitive data in logs
- [ ] HTTPS enforced
## Performance Checklist
- [ ] No N+1 queries
- [ ] Appropriate use of indexes
- [ ] Caching implemented where beneficial
- [ ] No blocking operations on main thread
- [ ] Async/await used correctly
- [ ] Large datasets paginated
- [ ] Database connections pooled
- [ ] Regular expressions optimized
- [ ] No unnecessary object creation
- [ ] Memory leaks prevented
## Quality Checklist
- [ ] Functions < 50 lines
- [ ] Clear variable naming
- [ ] No duplicate code
- [ ] Proper error handling
- [ ] Comments explain WHY, not WHAT
- [ ] No console.logs in production
- [ ] Type checking (TypeScript/JSDoc)
- [ ] SOLID principles followed
- [ ] Design patterns applied correctly
- [ ] Self-documenting code
## Testing Checklist
- [ ] Unit tests written
- [ ] Edge cases covered
- [ ] Error scenarios tested
- [ ] Integration tests present
- [ ] Coverage > 80%
- [ ] No flaky tests
- [ ] Mock external dependencies
- [ ] Clear test names
================================================
FILE: 03-skills/doc-generator/SKILL.md
================================================
---
name: api-documentation-generator
description: Generate comprehensive, accurate API documentation from source code. Use when creating or updating API documentation, generating OpenAPI specs, or when users mention API docs, endpoints, or documentation.
---
# API Documentation Generator Skill
## Generates
- OpenAPI/Swagger specifications
- API endpoint documentation
- SDK usage examples
- Integration guides
- Error code references
- Authentication guides
## Documentation Structure
### For Each Endpoint
```markdown
## GET /api/v1/users/:id
### Description
Brief explanation of what this endpoint does
### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | Yes | User ID |
### Response
**200 Success**
```json
{
"id": "usr_123",
"name": "John Doe",
"email": "john@example.com",
"created_at": "2025-01-15T10:30:00Z"
}
```
**404 Not Found**
```json
{
"error": "USER_NOT_FOUND",
"message": "User does not exist"
}
```
### Examples
**cURL**
```bash
curl -X GET "https://api.example.com/api/v1/users/usr_123" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**JavaScript**
```javascript
const user = await fetch('/api/v1/users/usr_123', {
headers: { 'Authorization': 'Bearer token' }
}).then(r => r.json());
```
**Python**
```python
response = requests.get(
'https://api.example.com/api/v1/users/usr_123',
headers={'Authorization': 'Bearer token'}
)
user = response.json()
```
```
================================================
FILE: 03-skills/doc-generator/generate-docs.py
================================================
#!/usr/bin/env python3
import ast
class APIDocExtractor(ast.NodeVisitor):
"""Extract API documentation from Python source code."""
def __init__(self):
self.endpoints = []
def visit_FunctionDef(self, node):
"""Extract function documentation."""
if node.name.startswith("get_") or node.name.startswith("post_"):
doc = ast.get_docstring(node)
endpoint = {
"name": node.name,
"docstring": doc,
"params": [arg.arg for arg in node.args.args],
"returns": self._extract_return_type(node),
}
self.endpoints.append(endpoint)
self.generic_visit(node)
def _extract_return_type(self, node):
"""Extract return type from function annotation."""
if node.returns:
return ast.unparse(node.returns)
return "Any"
def generate_markdown_docs(endpoints: list[dict]) -> str:
"""Generate markdown documentation from endpoints."""
docs = "# API Documentation\n\n"
for endpoint in endpoints:
docs += f"## {endpoint['name']}\n\n"
docs += f"{endpoint['docstring']}\n\n"
docs += f"**Parameters**: {', '.join(endpoint['params'])}\n\n"
docs += f"**Returns**: {endpoint['returns']}\n\n"
docs += "---\n\n"
return docs
if __name__ == "__main__":
import sys
with open(sys.argv[1]) as f:
tree = ast.parse(f.read())
extractor = APIDocExtractor()
extractor.visit(tree)
markdown = generate_markdown_docs(extractor.endpoints)
print(markdown)
================================================
FILE: 03-skills/refactor/SKILL.md
================================================
---
name: code-refactor
description: Systematic code refactoring based on Martin Fowler's methodology. Use when users ask to refactor code, improve code structure, reduce technical debt, clean up legacy code, eliminate code smells, or improve code maintainability. This skill guides through a phased approach with research, planning, and safe incremental implementation.
---
# Code Refactoring Skill
A systematic approach to refactoring code based on Martin Fowler's *Refactoring: Improving the Design of Existing Code* (2nd Edition). This skill emphasizes safe, incremental changes backed by tests.
> "Refactoring is the process of changing a software system in such a way that it does not alter the external behavior of the code yet improves its internal structure." — Martin Fowler
## Core Principles
1. **Behavior Preservation**: External behavior must remain unchanged
2. **Small Steps**: Make tiny, testable changes
3. **Test-Driven**: Tests are the safety net
4. **Continuous**: Refactoring is ongoing, not a one-time event
5. **Collaborative**: User approval required at each phase
## Workflow Overview
```
Phase 1: Research & Analysis
↓
Phase 2: Test Coverage Assessment
↓
Phase 3: Code Smell Identification
↓
Phase 4: Refactoring Plan Creation
↓
Phase 5: Incremental Implementation
↓
Phase 6: Review & Iteration
```
---
## Phase 1: Research & Analysis
### Objectives
- Understand the codebase structure and purpose
- Identify the scope of refactoring
- Gather context about business requirements
### Questions to Ask User
Before starting, clarify:
1. **Scope**: Which files/modules/functions need refactoring?
2. **Goals**: What problems are you trying to solve? (readability, performance, maintainability)
3. **Constraints**: Are there any areas that should NOT be changed?
4. **Timeline pressure**: Is this blocking other work?
5. **Test status**: Do tests exist? Are they passing?
### Actions
- [ ] Read and understand the target code
- [ ] Identify dependencies and integrations
- [ ] Document current architecture
- [ ] Note any existing technical debt markers (TODOs, FIXMEs)
### Output
Present findings to user:
- Code structure summary
- Identified problem areas
- Initial recommendations
- **Request approval to proceed**
---
## Phase 2: Test Coverage Assessment
### Why Tests Matter
> "Refactoring without tests is like driving without a seatbelt." — Martin Fowler
Tests are the **key enabler** of safe refactoring. Without them, you risk introducing bugs.
### Assessment Steps
1. **Check for existing tests**
```bash
# Look for test files
find . -name "*test*" -o -name "*spec*" | head -20
```
2. **Run existing tests**
```bash
# JavaScript/TypeScript
npm test
# Python
pytest -v
# Java
mvn test
```
3. **Check coverage (if available)**
```bash
# JavaScript
npm run test:coverage
# Python
pytest --cov=.
```
### Decision Point: Ask User
**If tests exist and pass:**
- Proceed to Phase 3
**If tests are missing or incomplete:**
Present options:
1. Write tests first (recommended)
2. Add tests incrementally during refactoring
3. Proceed without tests (risky - requires user acknowledgment)
**If tests are failing:**
- STOP. Fix failing tests before refactoring
- Ask user: Should we fix tests first?
### Test Writing Guidelines (if needed)
For each function being refactored, ensure tests cover:
- Happy path (normal operation)
- Edge cases (empty inputs, null, boundaries)
- Error scenarios (invalid inputs, exceptions)
Use the "red-green-refactor" cycle:
1. Write failing test (red)
2. Make it pass (green)
3. Refactor
---
## Phase 3: Code Smell Identification
### What Are Code Smells?
Symptoms of deeper problems in code. They're not bugs, but indicators that the code could be improved.
### Common Code Smells to Check
See [references/code-smells.md](references/code-smells.md) for the complete catalog.
#### Quick Reference
| Smell | Signs | Impact |
|-------|-------|--------|
| **Long Method** | Methods > 30-50 lines | Hard to understand, test, maintain |
| **Duplicated Code** | Same logic in multiple places | Bug fixes needed in multiple places |
| **Large Class** | Class with too many responsibilities | Violates Single Responsibility |
| **Feature Envy** | Method uses another class's data more | Poor encapsulation |
| **Primitive Obsession** | Overuse of primitives instead of objects | Missing domain concepts |
| **Long Parameter List** | Methods with 4+ parameters | Hard to call correctly |
| **Data Clumps** | Same data items appearing together | Missing abstraction |
| **Switch Statements** | Complex switch/if-else chains | Hard to extend |
| **Speculative Generality** | Code "just in case" | Unnecessary complexity |
| **Dead Code** | Unused code | Confusion, maintenance burden |
### Analysis Steps
1. **Automated Analysis** (if scripts available)
```bash
python scripts/detect-smells.py <file>
```
2. **Manual Review**
- Walk through code systematically
- Note each smell with location and severity
- Categorize by impact (Critical/High/Medium/Low)
3. **Prioritization**
Focus on smells that:
- Block current development
- Cause bugs or confusion
- Affect most-changed code paths
### Output: Smell Report
Present to user:
- List of identified smells with locations
- Severity assessment for each
- Recommended priority order
- **Request approval on priorities**
---
## Phase 4: Refactoring Plan Creation
### Selecting Refactorings
For each smell, select an appropriate refactoring from the catalog.
See [references/refactoring-catalog.md](references/refactoring-catalog.md) for the complete list.
#### Smell-to-Refactoring Mapping
| Code Smell | Recommended Refactoring(s) |
|------------|---------------------------|
| Long Method | Extract Method, Replace Temp with Query |
| Duplicated Code | Extract Method, Pull Up Method, Form Template Method |
| Large Class | Extract Class, Extract Subclass |
| Feature Envy | Move Method, Move Field |
| Primitive Obsession | Replace Primitive with Object, Replace Type Code with Class |
| Long Parameter List | Introduce Parameter Object, Preserve Whole Object |
| Data Clumps | Extract Class, Introduce Parameter Object |
| Switch Statements | Replace Conditional with Polymorphism |
| Speculative Generality | Collapse Hierarchy, Inline Class, Remove Dead Code |
| Dead Code | Remove Dead Code |
### Plan Structure
Use the template at [templates/refactoring-plan.md](templates/refactoring-plan.md).
For each refactoring:
1. **Target**: What code will change
2. **Smell**: What problem it addresses
3. **Refactoring**: Which technique to apply
4. **Steps**: Detailed micro-steps
5. **Risks**: What could go wrong
6. **Rollback**: How to undo if needed
### Phased Approach
**CRITICAL**: Introduce refactoring gradually in phases.
**Phase A: Quick Wins** (Low risk, high value)
- Rename variables for clarity
- Extract obvious duplicate code
- Remove dead code
**Phase B: Structural Improvements** (Medium risk)
- Extract methods from long functions
- Introduce parameter objects
- Move methods to appropriate classes
**Phase C: Architectural Changes** (Higher risk)
- Replace conditionals with polymorphism
- Extract classes
- Introduce design patterns
### Decision Point: Present Plan to User
Before implementation:
- Show complete refactoring plan
- Explain each phase and its risks
- Get explicit approval for each phase
- **Ask**: "Should I proceed with Phase A?"
---
## Phase 5: Incremental Implementation
### The Golden Rule
> "Change → Test → Green? → Commit → Next step"
### Implementation Rhythm
For each refactoring step:
1. **Pre-check**
- Tests are passing (green)
- Code compiles
2. **Make ONE small change**
- Follow the mechanics from the catalog
- Keep changes minimal
3. **Verify**
- Run tests immediately
- Check for compilation errors
4. **If tests pass (green)**
- Commit with descriptive message
- Move to next step
5. **If tests fail (red)**
- STOP immediately
- Undo the change
- Analyze what went wrong
- Ask user if unclear
### Commit Strategy
Each commit should be:
- **Atomic**: One logical change
- **Reversible**: Easy to r
gitextract_4pfp0y5z/
├── .cspell.json
├── .github/
│ ├── FUNDING.yml
│ ├── ISSUE_TEMPLATE/
│ │ ├── bug_report.md
│ │ ├── config.yml
│ │ ├── documentation.md
│ │ ├── feature_request.md
│ │ └── question.md
│ ├── SECURITY_REPORTING.md
│ ├── TESTING.md
│ ├── markdown-link-check-config.json
│ ├── pull_request_template.md
│ └── workflows/
│ ├── ci.yml
│ ├── docs-check.yml
│ ├── release.yml
│ └── test.yml
├── .gitignore
├── .pre-commit-config.yaml
├── 01-slash-commands/
│ ├── README.md
│ ├── commit.md
│ ├── doc-refactor.md
│ ├── generate-api-docs.md
│ ├── optimize.md
│ ├── pr.md
│ ├── push-all.md
│ ├── setup-ci-cd.md
│ └── unit-test-expand.md
├── 02-memory/
│ ├── README.md
│ ├── directory-api-CLAUDE.md
│ ├── personal-CLAUDE.md
│ └── project-CLAUDE.md
├── 03-skills/
│ ├── .gitignore
│ ├── README.md
│ ├── blog-draft/
│ │ ├── SKILL.md
│ │ └── templates/
│ │ ├── draft-template.md
│ │ └── outline-template.md
│ ├── brand-voice/
│ │ ├── SKILL.md
│ │ ├── templates/
│ │ │ ├── email-template.txt
│ │ │ └── social-post-template.txt
│ │ └── tone-examples.md
│ ├── claude-md/
│ │ └── SKILL.md
│ ├── code-review/
│ │ ├── SKILL.md
│ │ ├── scripts/
│ │ │ ├── analyze-metrics.py
│ │ │ └── compare-complexity.py
│ │ └── templates/
│ │ ├── finding-template.md
│ │ └── review-checklist.md
│ ├── doc-generator/
│ │ ├── SKILL.md
│ │ └── generate-docs.py
│ └── refactor/
│ ├── SKILL.md
│ ├── references/
│ │ ├── code-smells.md
│ │ └── refactoring-catalog.md
│ ├── scripts/
│ │ ├── analyze-complexity.py
│ │ └── detect-smells.py
│ └── templates/
│ └── refactoring-plan.md
├── 04-subagents/
│ ├── README.md
│ ├── clean-code-reviewer.md
│ ├── code-reviewer.md
│ ├── data-scientist.md
│ ├── debugger.md
│ ├── documentation-writer.md
│ ├── implementation-agent.md
│ ├── secure-reviewer.md
│ └── test-engineer.md
├── 05-mcp/
│ ├── README.md
│ ├── database-mcp.json
│ ├── filesystem-mcp.json
│ ├── github-mcp.json
│ └── multi-mcp.json
├── 06-hooks/
│ ├── README.md
│ ├── auto-adapt-mode.py
│ ├── context-tracker-tiktoken.py
│ ├── context-tracker.py
│ ├── format-code.sh
│ ├── log-bash.sh
│ ├── notify-team.sh
│ ├── pre-commit.sh
│ ├── security-scan.sh
│ └── validate-prompt.sh
├── 07-plugins/
│ ├── README.md
│ ├── devops-automation/
│ │ ├── .claude-plugin/
│ │ │ └── plugin.json
│ │ ├── README.md
│ │ ├── agents/
│ │ │ ├── alert-analyzer.md
│ │ │ ├── deployment-specialist.md
│ │ │ └── incident-commander.md
│ │ ├── commands/
│ │ │ ├── deploy.md
│ │ │ ├── incident.md
│ │ │ ├── rollback.md
│ │ │ └── status.md
│ │ ├── hooks/
│ │ │ ├── post-deploy.js
│ │ │ └── pre-deploy.js
│ │ ├── mcp/
│ │ │ └── kubernetes-config.json
│ │ └── scripts/
│ │ ├── deploy.sh
│ │ ├── health-check.sh
│ │ └── rollback.sh
│ ├── documentation/
│ │ ├── .claude-plugin/
│ │ │ └── plugin.json
│ │ ├── README.md
│ │ ├── agents/
│ │ │ ├── api-documenter.md
│ │ │ ├── code-commentator.md
│ │ │ └── example-generator.md
│ │ ├── commands/
│ │ │ ├── generate-api-docs.md
│ │ │ ├── generate-readme.md
│ │ │ ├── sync-docs.md
│ │ │ └── validate-docs.md
│ │ ├── mcp/
│ │ │ └── github-docs-config.json
│ │ └── templates/
│ │ ├── adr-template.md
│ │ ├── api-endpoint.md
│ │ └── function-docs.md
│ └── pr-review/
│ ├── .claude-plugin/
│ │ └── plugin.json
│ ├── README.md
│ ├── agents/
│ │ ├── performance-analyzer.md
│ │ ├── security-reviewer.md
│ │ └── test-checker.md
│ ├── commands/
│ │ ├── check-security.md
│ │ ├── check-tests.md
│ │ └── review-pr.md
│ ├── hooks/
│ │ └── pre-review.js
│ └── mcp/
│ └── github-config.json
├── 08-checkpoints/
│ ├── README.md
│ └── checkpoint-examples.md
├── 09-advanced-features/
│ ├── README.md
│ ├── config-examples.json
│ └── planning-mode-examples.md
├── 10-cli/
│ └── README.md
├── CATALOG.md
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── INDEX.md
├── LEARNING-ROADMAP.md
├── LICENSE
├── QUICK_REFERENCE.md
├── README.backup.md
├── README.md
├── RELEASE_NOTES.md
├── SECURITY.md
├── STYLE_GUIDE.md
├── claude_concepts_guide.md
├── clean-code-rules.md
├── coverage.xml
├── prompts/
│ └── remotion-video.md
├── resources/
│ ├── DESIGN-SYSTEM.md
│ ├── INDEX.txt
│ ├── MANIFEST.txt
│ ├── QUICK-START.md
│ └── README.md
├── resources.md
└── scripts/
├── README.md
├── build_epub.py
├── pyproject.toml
├── requirements-dev.txt
├── requirements.txt
└── tests/
├── __init__.py
├── conftest.py
└── test_build_epub.py
SYMBOL INDEX (156 symbols across 14 files)
FILE: 03-skills/code-review/scripts/analyze-metrics.py
function analyze_code_metrics (line 6) | def analyze_code_metrics(code):
FILE: 03-skills/code-review/scripts/compare-complexity.py
class ComplexityAnalyzer (line 11) | class ComplexityAnalyzer:
method __init__ (line 14) | def __init__(self, code: str):
method calculate_cyclomatic_complexity (line 18) | def calculate_cyclomatic_complexity(self) -> int:
method calculate_cognitive_complexity (line 42) | def calculate_cognitive_complexity(self) -> int:
method calculate_maintainability_index (line 64) | def calculate_maintainability_index(self) -> float:
method get_complexity_report (line 86) | def get_complexity_report(self) -> dict:
function compare_files (line 101) | def compare_files(before_file: str, after_file: str) -> None:
FILE: 03-skills/doc-generator/generate-docs.py
class APIDocExtractor (line 5) | class APIDocExtractor(ast.NodeVisitor):
method __init__ (line 8) | def __init__(self):
method visit_FunctionDef (line 11) | def visit_FunctionDef(self, node):
method _extract_return_type (line 24) | def _extract_return_type(self, node):
function generate_markdown_docs (line 31) | def generate_markdown_docs(endpoints: list[dict]) -> str:
FILE: 03-skills/refactor/scripts/analyze-complexity.py
class FunctionMetrics (line 32) | class FunctionMetrics:
class FileMetrics (line 44) | class FileMetrics:
class ComplexityAnalyzer (line 60) | class ComplexityAnalyzer:
method __init__ (line 97) | def __init__(self, filepath: str):
method _detect_language (line 107) | def _detect_language(self) -> str:
method calculate_cyclomatic_complexity (line 119) | def calculate_cyclomatic_complexity(self, code: Optional[str] = None) ...
method calculate_cognitive_complexity (line 136) | def calculate_cognitive_complexity(self, code: Optional[str] = None) -...
method calculate_maintainability_index (line 181) | def calculate_maintainability_index(self) -> float:
method count_lines (line 211) | def count_lines(self) -> Dict[str, int]:
method find_functions (line 243) | def find_functions(self) -> List[FunctionMetrics]:
method _create_function_metrics (line 278) | def _create_function_metrics(self, name: str, start: int, end: int, co...
method analyze (line 298) | def analyze(self) -> FileMetrics:
function print_metrics (line 327) | def print_metrics(metrics: FileMetrics, verbose: bool = False) -> None:
function print_comparison (line 376) | def print_comparison(before: FileMetrics, after: FileMetrics) -> None:
function analyze_directory (line 442) | def analyze_directory(directory: str, verbose: bool = False) -> None:
function main (line 495) | def main():
FILE: 03-skills/refactor/scripts/detect-smells.py
class SmellSeverity (line 35) | class SmellSeverity(Enum):
class SmellType (line 43) | class SmellType(Enum):
class CodeSmell (line 62) | class CodeSmell:
class SmellReport (line 75) | class SmellReport:
method critical_count (line 81) | def critical_count(self) -> int:
method high_count (line 85) | def high_count(self) -> int:
method medium_count (line 89) | def medium_count(self) -> int:
method low_count (line 93) | def low_count(self) -> int:
class SmellDetector (line 97) | class SmellDetector:
method __init__ (line 112) | def __init__(self, filepath: str):
method _detect_language (line 122) | def _detect_language(self) -> str:
method detect_all (line 134) | def detect_all(self) -> SmellReport:
method _get_snippet (line 150) | def _get_snippet(self, start: int, end: int, context: int = 2) -> str:
method _detect_long_methods (line 160) | def _detect_long_methods(self) -> None:
method _check_method_length (line 198) | def _check_method_length(self, name: str, start: int, end: int, lines:...
method _detect_long_parameter_lists (line 220) | def _detect_long_parameter_lists(self) -> None:
method _detect_large_class (line 258) | def _detect_large_class(self) -> None:
method _check_class_size (line 292) | def _check_class_size(self, name: str, start: int, end: int, methods: ...
method _detect_complex_conditionals (line 320) | def _detect_complex_conditionals(self) -> None:
method _detect_magic_numbers (line 338) | def _detect_magic_numbers(self) -> None:
method _detect_excessive_comments (line 369) | def _detect_excessive_comments(self) -> None:
method _detect_deeply_nested (line 391) | def _detect_deeply_nested(self) -> None:
method _detect_switch_statements (line 429) | def _detect_switch_statements(self) -> None:
method _add_switch_smell (line 458) | def _add_switch_smell(self, start: int, end: int, cases: int) -> None:
method _detect_message_chains (line 471) | def _detect_message_chains(self) -> None:
method _detect_duplicate_code (line 491) | def _detect_duplicate_code(self) -> None:
method _detect_dead_code (line 515) | def _detect_dead_code(self) -> None:
function print_report (line 542) | def print_report(report: SmellReport, verbose: bool = False) -> None:
function analyze_directory (line 605) | def analyze_directory(directory: str, verbose: bool = False) -> None:
function main (line 659) | def main():
FILE: 06-hooks/auto-adapt-mode.py
function log (line 220) | def log(message: str):
function is_dangerous_command (line 230) | def is_dangerous_command(command: str) -> bool:
function generalize_tool_permission (line 238) | def generalize_tool_permission(tool_name: str, tool_input: dict) -> str ...
function load_settings (line 291) | def load_settings() -> dict:
function save_settings (line 299) | def save_settings(settings: dict):
function ensure_baseline (line 307) | def ensure_baseline(settings: dict) -> bool:
function add_permission (line 331) | def add_permission(settings: dict, rule: str) -> bool:
function main (line 366) | def main():
FILE: 06-hooks/context-tracker-tiktoken.py
function get_state_file (line 38) | def get_state_file(session_id: str) -> str:
function count_tokens (line 43) | def count_tokens(text: str) -> int:
function read_transcript (line 62) | def read_transcript(transcript_path: str) -> str:
function handle_user_prompt_submit (line 87) | def handle_user_prompt_submit(data: dict) -> None:
function handle_stop (line 101) | def handle_stop(data: dict) -> None:
function main (line 136) | def main():
FILE: 06-hooks/context-tracker.py
function get_state_file (line 25) | def get_state_file(session_id: str) -> str:
function count_tokens_estimate (line 30) | def count_tokens_estimate(text: str) -> int:
function read_transcript (line 40) | def read_transcript(transcript_path: str) -> str:
function handle_user_prompt_submit (line 65) | def handle_user_prompt_submit(data: dict) -> None:
function handle_stop (line 79) | def handle_stop(data: dict) -> None:
function main (line 113) | def main():
FILE: 07-plugins/devops-automation/hooks/post-deploy.js
function postDeploy (line 8) | async function postDeploy() {
FILE: 07-plugins/devops-automation/hooks/pre-deploy.js
function preDeploy (line 8) | async function preDeploy() {
FILE: 07-plugins/pr-review/hooks/pre-review.js
function preReview (line 8) | async function preReview() {
FILE: scripts/build_epub.py
class EPUBBuildError (line 75) | class EPUBBuildError(Exception):
class MermaidRenderError (line 81) | class MermaidRenderError(EPUBBuildError):
class ValidationError (line 87) | class ValidationError(EPUBBuildError):
class CoverGenerationError (line 93) | class CoverGenerationError(EPUBBuildError):
class EPUBConfig (line 105) | class EPUBConfig:
class BuildState (line 152) | class BuildState:
method reset (line 160) | def reset(self) -> None:
class ChapterInfo (line 169) | class ChapterInfo:
function setup_logging (line 185) | def setup_logging(verbose: bool = False) -> logging.Logger:
function validate_inputs (line 201) | def validate_inputs(config: EPUBConfig, logger: logging.Logger) -> None:
function sanitize_mermaid (line 241) | def sanitize_mermaid(mermaid_code: str) -> str:
class MermaidRenderer (line 253) | class MermaidRenderer:
method __init__ (line 256) | def __init__(
method _fetch_single (line 264) | async def _fetch_single(
method _fetch_with_retry (line 291) | async def _fetch_with_retry(
method render_all (line 328) | async def render_all(
function extract_all_mermaid_blocks (line 360) | def extract_all_mermaid_blocks(
function get_chapter_order (line 390) | def get_chapter_order() -> list[tuple[str, str]]:
function collect_folder_files (line 410) | def collect_folder_files(folder_path: Path) -> list[tuple[Path, str]]:
class ChapterCollector (line 442) | class ChapterCollector:
method __init__ (line 445) | def __init__(self, root_path: Path, state: BuildState) -> None:
method collect_all_chapters (line 449) | def collect_all_chapters(
method _collect_folder (line 483) | def _collect_folder(
function load_font (line 523) | def load_font(
function _add_logo_to_cover (line 539) | def _add_logo_to_cover(
function _draw_text_centered (line 562) | def _draw_text_centered(
function create_cover_image (line 582) | def create_cover_image(
function create_chapter_html (line 643) | def create_chapter_html(
function handle_svg_image (line 676) | def handle_svg_image(src: str, alt: str, logger: logging.Logger) -> str:
function process_mermaid_blocks (line 702) | def process_mermaid_blocks(
function convert_internal_links (line 733) | def convert_internal_links(
function md_to_html (line 779) | def md_to_html(
function create_stylesheet (line 831) | def create_stylesheet() -> epub.EpubItem:
function build_epub_async (line 858) | async def build_epub_async(
function create_epub (line 986) | def create_epub(root_path: Path, output_path: Path, verbose: bool = Fals...
function main (line 998) | def main() -> int:
FILE: scripts/tests/conftest.py
function tmp_project (line 18) | def tmp_project(tmp_path: Path) -> Path:
function config (line 41) | def config(tmp_project: Path) -> EPUBConfig:
function state (line 50) | def state() -> BuildState:
function logger (line 56) | def logger() -> logging.Logger:
FILE: scripts/tests/test_build_epub.py
class TestBuildState (line 31) | class TestBuildState:
method test_initial_state (line 34) | def test_initial_state(self, state: BuildState) -> None:
method test_state_modification (line 41) | def test_state_modification(self, state: BuildState) -> None:
method test_reset (line 53) | def test_reset(self, state: BuildState) -> None:
class TestEPUBConfig (line 73) | class TestEPUBConfig:
method test_required_fields (line 76) | def test_required_fields(self, tmp_path: Path) -> None:
method test_default_values (line 85) | def test_default_values(self, tmp_path: Path) -> None:
method test_custom_values (line 99) | def test_custom_values(self, tmp_path: Path) -> None:
class TestValidation (line 118) | class TestValidation:
method test_valid_inputs (line 121) | def test_valid_inputs(self, config: EPUBConfig, logger: logging.Logger...
method test_missing_root_path (line 126) | def test_missing_root_path(self, tmp_path: Path, logger: logging.Logge...
method test_root_path_is_file (line 135) | def test_root_path_is_file(self, tmp_path: Path, logger: logging.Logge...
method test_no_markdown_files (line 146) | def test_no_markdown_files(self, tmp_path: Path, logger: logging.Logge...
method test_missing_output_directory (line 157) | def test_missing_output_directory(
class TestMermaidProcessing (line 174) | class TestMermaidProcessing:
method test_sanitize_mermaid_numbered_list (line 177) | def test_sanitize_mermaid_numbered_list(self) -> None:
method test_sanitize_mermaid_no_change (line 183) | def test_sanitize_mermaid_no_change(self) -> None:
method test_extract_mermaid_blocks (line 188) | def test_extract_mermaid_blocks(
method test_extract_mermaid_blocks_deduplication (line 219) | def test_extract_mermaid_blocks_deduplication(
class TestChapterCollector (line 247) | class TestChapterCollector:
method test_collect_single_file (line 250) | def test_collect_single_file(self, tmp_path: Path, state: BuildState) ...
method test_collect_folder (line 264) | def test_collect_folder(self, tmp_project: Path, state: BuildState) ->...
method test_path_mapping (line 274) | def test_path_mapping(self, tmp_project: Path, state: BuildState) -> N...
class TestHTMLGeneration (line 294) | class TestHTMLGeneration:
method test_create_chapter_html_overview (line 297) | def test_create_chapter_html_overview(self) -> None:
method test_create_chapter_html_section (line 311) | def test_create_chapter_html_section(self) -> None:
method test_html_escaping (line 323) | def test_html_escaping(self) -> None:
class TestChapterOrder (line 342) | class TestChapterOrder:
method test_get_chapter_order (line 345) | def test_get_chapter_order(self) -> None:
class TestLogging (line 364) | class TestLogging:
method test_setup_logging_default (line 367) | def test_setup_logging_default(self) -> None:
method test_setup_logging_verbose (line 372) | def test_setup_logging_verbose(self) -> None:
class TestIntegration (line 383) | class TestIntegration:
method test_build_without_mermaid (line 387) | async def test_build_without_mermaid(
Condensed preview — 153 files, each showing path, character count, and a content snippet. Download the .json file or copy for the full structured content (1,101K chars).
[
{
"path": ".cspell.json",
"chars": 4297,
"preview": "{\n \"version\": \"0.2\",\n \"language\": \"en\",\n \"words\": [\n \"claude\",\n \"Claude\",\n \"Anthropic\",\n \"subagent\",\n "
},
{
"path": ".github/FUNDING.yml",
"chars": 220,
"preview": "# These are supported funding model platforms\ngithub: [luongnv89] # Replace with up to 4 GitHub Sponsors-enabled usernam"
},
{
"path": ".github/ISSUE_TEMPLATE/bug_report.md",
"chars": 893,
"preview": "---\nname: Bug Report\nabout: Report an issue with an example, guide, or documentation\ntitle: \"[BUG] \"\nlabels: bug\nassigne"
},
{
"path": ".github/ISSUE_TEMPLATE/config.yml",
"chars": 462,
"preview": "blank_issues_enabled: false\ncontact_links:\n - name: Claude Code Documentation\n url: https://code.claude.com/docs/en/"
},
{
"path": ".github/ISSUE_TEMPLATE/documentation.md",
"chars": 909,
"preview": "---\nname: Documentation Issue\nabout: Report unclear documentation, typos, or missing information\ntitle: \"[DOCS] \"\nlabels"
},
{
"path": ".github/ISSUE_TEMPLATE/feature_request.md",
"chars": 1017,
"preview": "---\nname: Feature Request\nabout: Suggest a new example, guide, or improvement\ntitle: \"[FEATURE] \"\nlabels: enhancement\nas"
},
{
"path": ".github/ISSUE_TEMPLATE/question.md",
"chars": 778,
"preview": "---\nname: Question\nabout: Ask a question about Claude Code or this guide\ntitle: \"[QUESTION] \"\nlabels: question\nassignees"
},
{
"path": ".github/SECURITY_REPORTING.md",
"chars": 9115,
"preview": "# Security Vulnerability Reporting\n\nThis file explains how to report security vulnerabilities to the Claude How To proje"
},
{
"path": ".github/TESTING.md",
"chars": 8116,
"preview": "# Testing Guide\n\nThis document describes the testing infrastructure for Claude How To.\n\n## Overview\n\nThe project uses Gi"
},
{
"path": ".github/markdown-link-check-config.json",
"chars": 2579,
"preview": "{\n \"ignorePatterns\": [\n {\n \"pattern\": \"^https://docs\\\\.example\\\\.com\",\n \"comment\": \"Example placeholder UR"
},
{
"path": ".github/pull_request_template.md",
"chars": 1291,
"preview": "## Description\nBrief summary of what this PR does.\n\n## Type of Change\n- [ ] New example or template\n- [ ] Documentation "
},
{
"path": ".github/workflows/ci.yml",
"chars": 3222,
"preview": "name: CI\n\non:\n push:\n branches: [main]\n pull_request:\n branches: [main]\n\n# Cancel in-progress runs for the same "
},
{
"path": ".github/workflows/docs-check.yml",
"chars": 10909,
"preview": "name: Documentation Checks\n\non:\n push:\n branches: [main]\n paths:\n - '**.md'\n - '.github/workflows/docs-"
},
{
"path": ".github/workflows/release.yml",
"chars": 492,
"preview": "name: Build and Release EPUB\n\non:\n push:\n tags:\n - 'v*'\n\njobs:\n build:\n runs-on: ubuntu-latest\n permissi"
},
{
"path": ".github/workflows/test.yml",
"chars": 6312,
"preview": "name: Automated Testing\n\non:\n push:\n branches: [main, develop]\n paths:\n - 'scripts/**'\n - '.github/work"
},
{
"path": ".gitignore",
"chars": 1124,
"preview": "# macOS\n.DS_Store\n.AppleDouble\n.LSOverride\n\n# Thumbnails\n._*\n\n# Files that might appear in the root of a volume\n.Documen"
},
{
"path": ".pre-commit-config.yaml",
"chars": 1498,
"preview": "# Pre-commit hooks for claude-howto project\n# Run `pre-commit install` to set up hooks\n# Run `pre-commit run --all-files"
},
{
"path": "01-slash-commands/README.md",
"chars": 16305,
"preview": "<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"../resources/logos/claude-howto-logo-dark.svg\">\n <img "
},
{
"path": "01-slash-commands/commit.md",
"chars": 769,
"preview": "---\nallowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git diff:*)\nargument-hint: [message]\nde"
},
{
"path": "01-slash-commands/doc-refactor.md",
"chars": 1276,
"preview": "---\nname: Documentation Refactor\ndescription: Restructure project documentation for clarity and accessibility\ntags: docu"
},
{
"path": "01-slash-commands/generate-api-docs.md",
"chars": 482,
"preview": "---\ndescription: Create comprehensive API documentation from source code\n---\n\n# API Documentation Generator\n\nGenerate AP"
},
{
"path": "01-slash-commands/optimize.md",
"chars": 676,
"preview": "---\ndescription: Analyze code for performance issues and suggest optimizations\n---\n\n# Code Optimization\n\nReview the prov"
},
{
"path": "01-slash-commands/pr.md",
"chars": 763,
"preview": "---\ndescription: Clean up code, stage changes, and prepare a pull request\nallowed-tools: Bash(git add:*), Bash(git statu"
},
{
"path": "01-slash-commands/push-all.md",
"chars": 4009,
"preview": "---\ndescription: Stage all changes, create commit, and push to remote (use with caution)\nallowed-tools: Bash(git add:*),"
},
{
"path": "01-slash-commands/setup-ci-cd.md",
"chars": 1024,
"preview": "---\nname: Setup CI/CD Pipeline\ndescription: Implement pre-commit hooks and GitHub Actions for quality assurance\ntags: ci"
},
{
"path": "01-slash-commands/unit-test-expand.md",
"chars": 994,
"preview": "---\nname: Expand Unit Tests\ndescription: Increase test coverage by targeting untested branches and edge cases\ntags: test"
},
{
"path": "02-memory/README.md",
"chars": 36885,
"preview": "<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"../resources/logos/claude-howto-logo-dark.svg\">\n <img "
},
{
"path": "02-memory/directory-api-CLAUDE.md",
"chars": 1280,
"preview": "# API Module Standards\n\nThis file overrides root CLAUDE.md for everything in /src/api/\n\n## API-Specific Standards\n\n### R"
},
{
"path": "02-memory/personal-CLAUDE.md",
"chars": 1651,
"preview": "# My Development Preferences\n\n## About Me\n- **Experience Level**: 8 years full-stack development\n- **Preferred Languages"
},
{
"path": "02-memory/project-CLAUDE.md",
"chars": 2374,
"preview": "# Project Configuration\n\n## Project Overview\n- **Name**: E-commerce Platform\n- **Tech Stack**: Node.js, PostgreSQL, Reac"
},
{
"path": "03-skills/.gitignore",
"chars": 64,
"preview": "# Local skill testing\n.claude/\n\n# Blog post outputs\nblog-posts/\n"
},
{
"path": "03-skills/README.md",
"chars": 27502,
"preview": "<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"../resources/logos/claude-howto-logo-dark.svg\">\n <img "
},
{
"path": "03-skills/blog-draft/SKILL.md",
"chars": 8130,
"preview": "---\nname: blog-draft\ndescription: Draft a blog post from ideas and resources. Use when users want to write a blog post, "
},
{
"path": "03-skills/blog-draft/templates/draft-template.md",
"chars": 982,
"preview": "# [Blog Post Title]\n\n*[Subtitle or tagline - optional]*\n\n**[Author Name]** | [Date]\n\n---\n\n[Opening hook - grab attention"
},
{
"path": "03-skills/blog-draft/templates/outline-template.md",
"chars": 1853,
"preview": "# Blog Post Outline: [Title]\n\n## Meta Information\n\n| Attribute | Value |\n|-----------|-------|\n| **Target Audience** | ["
},
{
"path": "03-skills/brand-voice/SKILL.md",
"chars": 2175,
"preview": "---\nname: brand-voice-consistency\ndescription: Ensure all communication matches brand voice and tone guidelines. Use whe"
},
{
"path": "03-skills/brand-voice/templates/email-template.txt",
"chars": 220,
"preview": "Subject: [Clear, benefit-driven subject]\n\nHi [Name],\n\n[Opening: What's the value for them]\n\n[Body: How it works / What t"
},
{
"path": "03-skills/brand-voice/templates/social-post-template.txt",
"chars": 161,
"preview": "[Hook: Grab attention in first line]\n[2-3 lines: Value or interesting fact]\n[Call to action: Link, question, or engageme"
},
{
"path": "03-skills/brand-voice/tone-examples.md",
"chars": 484,
"preview": "# Brand Voice Tone Examples\n\n## Exciting Announcement\n\"Save 8 hours per week on code reviews. Claude reviews your PRs au"
},
{
"path": "03-skills/claude-md/SKILL.md",
"chars": 6353,
"preview": "---\nname: claude-md\ndescription: Create or update CLAUDE.md files following best practices for optimal AI agent onboardi"
},
{
"path": "03-skills/code-review/SKILL.md",
"chars": 1859,
"preview": "---\nname: code-review-specialist\ndescription: Comprehensive code review with security, performance, and quality analysis"
},
{
"path": "03-skills/code-review/scripts/analyze-metrics.py",
"chars": 896,
"preview": "#!/usr/bin/env python3\nimport re\nimport sys\n\n\ndef analyze_code_metrics(code):\n \"\"\"Analyze code for common metrics.\"\"\""
},
{
"path": "03-skills/code-review/scripts/compare-complexity.py",
"chars": 5703,
"preview": "#!/usr/bin/env python3\n\"\"\"\nCompare cyclomatic complexity of code before and after changes.\nHelps identify if refactoring"
},
{
"path": "03-skills/code-review/templates/finding-template.md",
"chars": 2465,
"preview": "# Code Review Finding Template\n\nUse this template when documenting each issue found during code review.\n\n---\n\n## Issue: "
},
{
"path": "03-skills/code-review/templates/review-checklist.md",
"chars": 1409,
"preview": "# Code Review Checklist\n\n## Security Checklist\n- [ ] No hardcoded credentials or secrets\n- [ ] Input validation on all u"
},
{
"path": "03-skills/doc-generator/SKILL.md",
"chars": 1475,
"preview": "---\nname: api-documentation-generator\ndescription: Generate comprehensive, accurate API documentation from source code. "
},
{
"path": "03-skills/doc-generator/generate-docs.py",
"chars": 1599,
"preview": "#!/usr/bin/env python3\nimport ast\n\n\nclass APIDocExtractor(ast.NodeVisitor):\n \"\"\"Extract API documentation from Python"
},
{
"path": "03-skills/refactor/SKILL.md",
"chars": 11677,
"preview": "---\nname: code-refactor\ndescription: Systematic code refactoring based on Martin Fowler's methodology. Use when users as"
},
{
"path": "03-skills/refactor/references/code-smells.md",
"chars": 13586,
"preview": "# Code Smells Catalog\n\nA comprehensive reference of code smells based on Martin Fowler's *Refactoring* (2nd Edition). Co"
},
{
"path": "03-skills/refactor/references/refactoring-catalog.md",
"chars": 24059,
"preview": "# Refactoring Catalog\n\nA curated catalog of refactoring techniques from Martin Fowler's *Refactoring* (2nd Edition). Eac"
},
{
"path": "03-skills/refactor/scripts/analyze-complexity.py",
"chars": 20113,
"preview": "#!/usr/bin/env python3\n\"\"\"\nCode Complexity Analyzer\n\nAnalyzes code complexity metrics for Python, JavaScript, and TypeSc"
},
{
"path": "03-skills/refactor/scripts/detect-smells.py",
"chars": 28699,
"preview": "#!/usr/bin/env python3\n\"\"\"\nCode Smell Detector\n\nDetects common code smells in Python, JavaScript, and TypeScript files.\n"
},
{
"path": "03-skills/refactor/templates/refactoring-plan.md",
"chars": 6386,
"preview": "# Refactoring Plan Template\n\nUse this template to document and track your refactoring effort.\n\n---\n\n## Project Informati"
},
{
"path": "04-subagents/README.md",
"chars": 35898,
"preview": "<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"../resources/logos/claude-howto-logo-dark.svg\">\n <img "
},
{
"path": "04-subagents/clean-code-reviewer.md",
"chars": 2381,
"preview": "---\nname: clean-code-reviewer\ndescription: Clean Code principles enforcement specialist. Reviews code for violations of "
},
{
"path": "04-subagents/code-reviewer.md",
"chars": 1838,
"preview": "---\nname: code-reviewer\ndescription: Expert code review specialist. Use PROACTIVELY after writing or modifying code to e"
},
{
"path": "04-subagents/data-scientist.md",
"chars": 2217,
"preview": "---\nname: data-scientist\ndescription: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use "
},
{
"path": "04-subagents/debugger.md",
"chars": 1925,
"preview": "---\nname: debugger\ndescription: Debugging specialist for errors, test failures, and unexpected behavior. Use PROACTIVELY"
},
{
"path": "04-subagents/documentation-writer.md",
"chars": 2040,
"preview": "---\nname: documentation-writer\ndescription: Technical documentation specialist for API docs, user guides, and architectu"
},
{
"path": "04-subagents/implementation-agent.md",
"chars": 1839,
"preview": "---\nname: implementation-agent\ndescription: Full-stack implementation specialist for feature development. Has complete t"
},
{
"path": "04-subagents/secure-reviewer.md",
"chars": 1820,
"preview": "---\nname: secure-reviewer\ndescription: Security-focused code review specialist with minimal permissions. Read-only acces"
},
{
"path": "04-subagents/test-engineer.md",
"chars": 1874,
"preview": "---\nname: test-engineer\ndescription: Test automation expert for writing comprehensive tests. Use PROACTIVELY when new fe"
},
{
"path": "05-mcp/README.md",
"chars": 35056,
"preview": "<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"../resources/logos/claude-howto-logo-dark.svg\">\n <img "
},
{
"path": "05-mcp/database-mcp.json",
"chars": 218,
"preview": "{\n \"mcpServers\": {\n \"database\": {\n \"command\": \"npx\",\n \"args\": [\"@modelcontextprotocol/server-database\"],\n "
},
{
"path": "05-mcp/filesystem-mcp.json",
"chars": 157,
"preview": "{\n \"mcpServers\": {\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\"@modelcontextprotocol/server-filesystem\""
},
{
"path": "05-mcp/github-mcp.json",
"chars": 192,
"preview": "{\n \"mcpServers\": {\n \"github\": {\n \"command\": \"npx\",\n \"args\": [\"@modelcontextprotocol/server-github\"],\n "
},
{
"path": "05-mcp/multi-mcp.json",
"chars": 658,
"preview": "{\n \"mcpServers\": {\n \"github\": {\n \"command\": \"npx\",\n \"args\": [\"@modelcontextprotocol/server-github\"],\n "
},
{
"path": "06-hooks/README.md",
"chars": 38589,
"preview": "<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"../resources/logos/claude-howto-logo-dark.svg\">\n <img "
},
{
"path": "06-hooks/auto-adapt-mode.py",
"chars": 12024,
"preview": "#!/usr/bin/env python3\n\"\"\"\nauto-adapt-mode: Learn from user's tool approvals and update Claude config.\n\nHook Type: PostT"
},
{
"path": "06-hooks/context-tracker-tiktoken.py",
"chars": 4829,
"preview": "#!/usr/bin/env python3\n\"\"\"\nContext Usage Tracker (tiktoken version) - Tracks token consumption per request.\n\nUses UserPr"
},
{
"path": "06-hooks/context-tracker.py",
"chars": 4121,
"preview": "#!/usr/bin/env python3\n\"\"\"\nContext Usage Tracker - Tracks token consumption per request.\n\nUses UserPromptSubmit as \"pre-"
},
{
"path": "06-hooks/format-code.sh",
"chars": 936,
"preview": "#!/bin/bash\n# Auto-format code before writing\n# Hook: PreToolUse:Write\n\nFILE=$1\n\nif [ -z \"$FILE\" ]; then\n echo \"Usage: "
},
{
"path": "06-hooks/log-bash.sh",
"chars": 379,
"preview": "#!/bin/bash\n# Log all bash commands\n# Hook: PostToolUse:Bash\n\nCOMMAND=\"$1\"\nTIMESTAMP=$(date \"+%Y-%m-%d %H:%M:%S\")\nLOGFIL"
},
{
"path": "06-hooks/notify-team.sh",
"chars": 1843,
"preview": "#!/bin/bash\n# Send notifications on events\n# Hook: PostPush\n\nREPO_NAME=$(basename $(git rev-parse --show-toplevel 2>/dev"
},
{
"path": "06-hooks/pre-commit.sh",
"chars": 1178,
"preview": "#!/bin/bash\n# Run tests before commit\n# Hook: PreToolUse (matcher: Bash) - checks if the command is a git commit\n# Note:"
},
{
"path": "06-hooks/security-scan.sh",
"chars": 1482,
"preview": "#!/bin/bash\n# Security scan on file write\n# Hook: PostToolUse:Write\n\nFILE=$1\n\nif [ -z \"$FILE\" ]; then\n echo \"Usage: $0 "
},
{
"path": "06-hooks/validate-prompt.sh",
"chars": 983,
"preview": "#!/bin/bash\n# Validate user prompts\n# Hook: UserPromptSubmit\n\n# Read prompt from stdin\nPROMPT=$(cat)\n\necho \"🔍 Validating"
},
{
"path": "07-plugins/README.md",
"chars": 27083,
"preview": "<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"../resources/logos/claude-howto-logo-dark.svg\">\n <img "
},
{
"path": "07-plugins/devops-automation/.claude-plugin/plugin.json",
"chars": 216,
"preview": "{\n \"name\": \"devops-automation\",\n \"version\": \"1.0.0\",\n \"description\": \"Complete DevOps automation for deployment, moni"
},
{
"path": "07-plugins/devops-automation/README.md",
"chars": 1993,
"preview": "<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"../../resources/logos/claude-howto-logo-dark.svg\">\n <i"
},
{
"path": "07-plugins/devops-automation/agents/alert-analyzer.md",
"chars": 282,
"preview": "---\nname: alert-analyzer\ndescription: Analyzes monitoring alerts and system metrics\ntools: read, grep, bash\n---\n\n# Alert"
},
{
"path": "07-plugins/devops-automation/agents/deployment-specialist.md",
"chars": 276,
"preview": "---\nname: deployment-specialist\ndescription: Handles all deployment operations\ntools: read, write, bash, grep\n---\n\n# Dep"
},
{
"path": "07-plugins/devops-automation/agents/incident-commander.md",
"chars": 265,
"preview": "---\nname: incident-commander\ndescription: Coordinates incident response\ntools: read, write, bash, grep\n---\n\n# Incident C"
},
{
"path": "07-plugins/devops-automation/commands/deploy.md",
"chars": 271,
"preview": "---\nname: Deploy\ndescription: Deploy application to production or staging\n---\n\n# Deploy Application\n\nExecute deployment "
},
{
"path": "07-plugins/devops-automation/commands/incident.md",
"chars": 350,
"preview": "---\nname: Incident Response\ndescription: Handle production incidents with structured response\n---\n\n# Incident Response\n\n"
},
{
"path": "07-plugins/devops-automation/commands/rollback.md",
"chars": 265,
"preview": "---\nname: Rollback\ndescription: Rollback to previous deployment\n---\n\n# Rollback Deployment\n\nRollback to previous stable "
},
{
"path": "07-plugins/devops-automation/commands/status.md",
"chars": 314,
"preview": "---\nname: System Status\ndescription: Check overall system health and status\n---\n\n# System Status Check\n\nCheck system hea"
},
{
"path": "07-plugins/devops-automation/hooks/post-deploy.js",
"chars": 785,
"preview": "#!/usr/bin/env node\n\n/**\n * Post-deployment hook\n * Runs after deployment completes\n */\n\nasync function postDeploy() {\n "
},
{
"path": "07-plugins/devops-automation/hooks/pre-deploy.js",
"chars": 819,
"preview": "#!/usr/bin/env node\n\n/**\n * Pre-deployment hook\n * Validates environment and prerequisites before deployment\n */\n\nasync "
},
{
"path": "07-plugins/devops-automation/mcp/kubernetes-config.json",
"chars": 196,
"preview": "{\n \"mcpServers\": {\n \"kubernetes\": {\n \"command\": \"npx\",\n \"args\": [\"@modelcontextprotocol/server-kubernetes\""
},
{
"path": "07-plugins/devops-automation/scripts/deploy.sh",
"chars": 469,
"preview": "#!/bin/bash\nset -e\n\necho \"🚀 Starting deployment...\"\n\n# Load environment\nENV=${1:-staging}\necho \"📦 Target environment: $E"
},
{
"path": "07-plugins/devops-automation/scripts/health-check.sh",
"chars": 626,
"preview": "#!/bin/bash\n\necho \"🏥 System Health Check\"\necho \"====================\"\n\nENV=${1:-production}\n\n# Check API\necho -n \"API: \""
},
{
"path": "07-plugins/devops-automation/scripts/rollback.sh",
"chars": 579,
"preview": "#!/bin/bash\nset -e\n\necho \"⏪ Starting rollback...\"\n\nENV=${1:-staging}\necho \"📦 Target environment: $ENV\"\n\n# Get previous d"
},
{
"path": "07-plugins/documentation/.claude-plugin/plugin.json",
"chars": 190,
"preview": "{\n \"name\": \"documentation\",\n \"version\": \"1.0.0\",\n \"description\": \"Comprehensive documentation generation and maintena"
},
{
"path": "07-plugins/documentation/README.md",
"chars": 2481,
"preview": "<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"../../resources/logos/claude-howto-logo-dark.svg\">\n <i"
},
{
"path": "07-plugins/documentation/agents/api-documenter.md",
"chars": 274,
"preview": "---\nname: api-documenter\ndescription: API documentation specialist\ntools: read, write, grep\n---\n\n# API Documenter\n\nCreat"
},
{
"path": "07-plugins/documentation/agents/code-commentator.md",
"chars": 287,
"preview": "---\nname: code-commentator\ndescription: Code comment and inline documentation specialist\ntools: read, write, edit\n---\n\n#"
},
{
"path": "07-plugins/documentation/agents/example-generator.md",
"chars": 268,
"preview": "---\nname: example-generator\ndescription: Code example and tutorial specialist\ntools: read, write\n---\n\n# Example Generato"
},
{
"path": "07-plugins/documentation/commands/generate-api-docs.md",
"chars": 372,
"preview": "---\nname: Generate API Documentation\ndescription: Generate comprehensive API documentation from source code\n---\n\n# API D"
},
{
"path": "07-plugins/documentation/commands/generate-readme.md",
"chars": 288,
"preview": "---\nname: Generate README\ndescription: Create or update project README\n---\n\n# README Generator\n\nGenerate comprehensive R"
},
{
"path": "07-plugins/documentation/commands/sync-docs.md",
"chars": 286,
"preview": "---\nname: Sync Documentation\ndescription: Sync documentation with code changes\n---\n\n# Documentation Sync\n\nSynchronize do"
},
{
"path": "07-plugins/documentation/commands/validate-docs.md",
"chars": 290,
"preview": "---\nname: Validate Documentation\ndescription: Validate documentation for completeness and accuracy\n---\n\n# Documentation "
},
{
"path": "07-plugins/documentation/mcp/github-docs-config.json",
"chars": 192,
"preview": "{\n \"mcpServers\": {\n \"github\": {\n \"command\": \"npx\",\n \"args\": [\"@modelcontextprotocol/server-github\"],\n "
},
{
"path": "07-plugins/documentation/templates/adr-template.md",
"chars": 741,
"preview": "# ADR [Number]: [Title]\n\n## Status\n[Proposed | Accepted | Deprecated | Superseded]\n\n## Context\nWhat is the issue that we"
},
{
"path": "07-plugins/documentation/templates/api-endpoint.md",
"chars": 1730,
"preview": "# [METHOD] /api/v1/[endpoint]\n\n## Description\nBrief explanation of what this endpoint does.\n\n## Authentication\nRequired "
},
{
"path": "07-plugins/documentation/templates/function-docs.md",
"chars": 925,
"preview": "# Function: `functionName`\n\n## Description\nBrief description of what the function does.\n\n## Signature\n```typescript\nfunc"
},
{
"path": "07-plugins/pr-review/.claude-plugin/plugin.json",
"chars": 192,
"preview": "{\n \"name\": \"pr-review\",\n \"version\": \"1.0.0\",\n \"description\": \"Complete PR review workflow with security, testing, and"
},
{
"path": "07-plugins/pr-review/README.md",
"chars": 1797,
"preview": "<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"../../resources/logos/claude-howto-logo-dark.svg\">\n <i"
},
{
"path": "07-plugins/pr-review/agents/performance-analyzer.md",
"chars": 256,
"preview": "---\nname: performance-analyzer\ndescription: Performance impact analysis\ntools: read, grep, bash\n---\n\n# Performance Analy"
},
{
"path": "07-plugins/pr-review/agents/security-reviewer.md",
"chars": 266,
"preview": "---\nname: security-reviewer\ndescription: Security-focused code review\ntools: read, grep, diff\n---\n\n# Security Reviewer\n\n"
},
{
"path": "07-plugins/pr-review/agents/test-checker.md",
"chars": 248,
"preview": "---\nname: test-checker\ndescription: Test coverage and quality analysis\ntools: read, bash, grep\n---\n\n# Test Checker\n\nAnal"
},
{
"path": "07-plugins/pr-review/commands/check-security.md",
"chars": 291,
"preview": "---\nname: Security Check\ndescription: Run security-focused code review\n---\n\n# Security Check\n\nPerform focused security a"
},
{
"path": "07-plugins/pr-review/commands/check-tests.md",
"chars": 292,
"preview": "---\nname: Test Coverage Check\ndescription: Verify test coverage and quality\n---\n\n# Test Coverage Check\n\nAnalyze test cov"
},
{
"path": "07-plugins/pr-review/commands/review-pr.md",
"chars": 312,
"preview": "---\nname: Review PR\ndescription: Start comprehensive PR review with security and testing checks\n---\n\n# PR Review\n\nThis c"
},
{
"path": "07-plugins/pr-review/hooks/pre-review.js",
"chars": 894,
"preview": "#!/usr/bin/env node\n\n/**\n * Pre-review hook\n * Runs before starting PR review to ensure prerequisites are met\n */\n\nasync"
},
{
"path": "07-plugins/pr-review/mcp/github-config.json",
"chars": 192,
"preview": "{\n \"mcpServers\": {\n \"github\": {\n \"command\": \"npx\",\n \"args\": [\"@modelcontextprotocol/server-github\"],\n "
},
{
"path": "08-checkpoints/README.md",
"chars": 10663,
"preview": "<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"../resources/logos/claude-howto-logo-dark.svg\">\n <img "
},
{
"path": "08-checkpoints/checkpoint-examples.md",
"chars": 9103,
"preview": "# Checkpoint Examples\n\nReal-world examples of using checkpoints effectively in Claude Code.\n\nNote: Checkpoints are creat"
},
{
"path": "09-advanced-features/README.md",
"chars": 51083,
"preview": "<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"../resources/logos/claude-howto-logo-dark.svg\">\n <img "
},
{
"path": "09-advanced-features/config-examples.json",
"chars": 6797,
"preview": "{\n \"description\": \"Example Claude Code configurations for different use cases\",\n\n \"examples\": {\n \"development\": {\n "
},
{
"path": "09-advanced-features/planning-mode-examples.md",
"chars": 15258,
"preview": "# Planning Mode Examples\n\nReal-world examples demonstrating effective use of planning mode in Claude Code.\n\n## Example 1"
},
{
"path": "10-cli/README.md",
"chars": 28763,
"preview": "<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"../resources/logos/claude-howto-logo-dark.svg\">\n <img "
},
{
"path": "CATALOG.md",
"chars": 25694,
"preview": "<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"resources/logos/claude-howto-logo-dark.svg\">\n <img alt"
},
{
"path": "CHANGELOG.md",
"chars": 5343,
"preview": "# Changelog\n\n## v2.2.0 — 2026-03-26\n\n### Documentation\n\n- Sync all tutorials and references with Claude Code v2.1.84 (f7"
},
{
"path": "CODE_OF_CONDUCT.md",
"chars": 8326,
"preview": "# Contributor Code of Conduct\n\n## Our Commitment\n\nWe are committed to providing a welcoming and inspiring community for "
},
{
"path": "CONTRIBUTING.md",
"chars": 9596,
"preview": "<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"resources/logos/claude-howto-logo-dark.svg\">\n <img alt"
},
{
"path": "INDEX.md",
"chars": 26861,
"preview": "<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"resources/logos/claude-howto-logo-dark.svg\">\n <img alt"
},
{
"path": "LEARNING-ROADMAP.md",
"chars": 26897,
"preview": "<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"resources/logos/claude-howto-logo-dark.svg\">\n <img alt"
},
{
"path": "LICENSE",
"chars": 1066,
"preview": "MIT License\n\nCopyright (c) 2024 luongnv89\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\n"
},
{
"path": "QUICK_REFERENCE.md",
"chars": 13289,
"preview": "<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"resources/logos/claude-howto-logo-dark.svg\">\n <img alt"
},
{
"path": "README.backup.md",
"chars": 26938,
"preview": "<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"resources/logos/claude-howto-logo-dark.svg\">\n <img alt"
},
{
"path": "README.md",
"chars": 27461,
"preview": "<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"resources/logos/claude-howto-logo-dark.svg\">\n <img alt"
},
{
"path": "RELEASE_NOTES.md",
"chars": 253,
"preview": "## v2.2.0 — 2026-03-26\n\n### Bug Fixes\n\n- Remove dead marketplace link failing CI link checks (3fdf0d6)\n- Add `sandboxed`"
},
{
"path": "SECURITY.md",
"chars": 9944,
"preview": "# Security Policy\n\n## Overview\n\nThe security of the Claude How To project is important to us. This document outlines our"
},
{
"path": "STYLE_GUIDE.md",
"chars": 16476,
"preview": "<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"resources/logos/claude-howto-logo-dark.svg\">\n <img alt"
},
{
"path": "claude_concepts_guide.md",
"chars": 83036,
"preview": "<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"resources/logos/claude-howto-logo-dark.svg\">\n <img alt"
},
{
"path": "clean-code-rules.md",
"chars": 4382,
"preview": "# Clean Code Rules for AI Code Generation\n\nThese rules guide code generation to produce maintainable, professional-quali"
},
{
"path": "coverage.xml",
"chars": 23924,
"preview": "<?xml version=\"1.0\" ?>\n<coverage version=\"7.13.1\" timestamp=\"1767948660087\" lines-valid=\"628\" lines-covered=\"475\" line-r"
},
{
"path": "prompts/remotion-video.md",
"chars": 12648,
"preview": "You are an expert Motion Designer and Senior React Engineer specializing in **Remotion**. Your goal is to take a product"
},
{
"path": "resources/DESIGN-SYSTEM.md",
"chars": 5878,
"preview": "# Claude How To - Design System\n\n## Visual Identity\n\n### Icon Design Concept: Compass with Code Bracket\n\nThe Claude How "
},
{
"path": "resources/INDEX.txt",
"chars": 7533,
"preview": "╔═══════════════════════════════════════════════════════════════════════════╗\n║ CLAUDE HOW TO - BRAND ASSETS R"
},
{
"path": "resources/MANIFEST.txt",
"chars": 8152,
"preview": "╔════════════════════════════════════════════════════════════════════════════╗\n║ CLAUDE HOW TO - COMPLE"
},
{
"path": "resources/QUICK-START.md",
"chars": 2539,
"preview": "# Quick Start - Brand Assets\n\n## Copy Assets to Your Project\n\n```bash\n# Copy all resources to your web project\ncp -r res"
},
{
"path": "resources/README.md",
"chars": 7820,
"preview": "<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"logos/claude-howto-logo-dark.svg\">\n <img alt=\"Claude H"
},
{
"path": "resources.md",
"chars": 13872,
"preview": "<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"resources/logos/claude-howto-logo-dark.svg\">\n <img alt"
},
{
"path": "scripts/README.md",
"chars": 3180,
"preview": "<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"../resources/logos/claude-howto-logo-dark.svg\">\n <img "
},
{
"path": "scripts/build_epub.py",
"chars": 35941,
"preview": "#!/usr/bin/env -S uv run --script\n# /// script\n# dependencies = [\"ebooklib\", \"markdown\", \"beautifulsoup4\", \"httpx\", \"pil"
},
{
"path": "scripts/pyproject.toml",
"chars": 2808,
"preview": "[project]\nname = \"claude-howto\"\nversion = \"1.0.0\"\ndescription = \"Claude Code How-To Guide with EPUB builder\"\nreadme = \"R"
},
{
"path": "scripts/requirements-dev.txt",
"chars": 204,
"preview": "# Development dependencies (includes core dependencies)\n-r requirements.txt\n\n# Testing\npytest>=7.0\npytest-asyncio>=0.21\n"
},
{
"path": "scripts/requirements.txt",
"chars": 93,
"preview": "# Core dependencies for build_epub.py\nebooklib\nmarkdown\nbeautifulsoup4\nhttpx\npillow\ntenacity\n"
},
{
"path": "scripts/tests/__init__.py",
"chars": 30,
"preview": "# Tests for build_epub module\n"
},
{
"path": "scripts/tests/conftest.py",
"chars": 1530,
"preview": "\"\"\"Pytest configuration and shared fixtures for EPUB builder tests.\"\"\"\n\nfrom __future__ import annotations\n\nimport loggi"
},
{
"path": "scripts/tests/test_build_epub.py",
"chars": 14371,
"preview": "\"\"\"Tests for the EPUB builder module.\"\"\"\n\nfrom __future__ import annotations\n\nimport logging\nfrom pathlib import Path\nfr"
}
]
About this extraction
This page contains the full source code of the luongnv89/claude-howto GitHub repository, extracted and formatted as plain text for AI agents and large language models (LLMs). The extraction includes 153 files (1015.3 KB), approximately 260.3k tokens, and a symbol index with 156 extracted functions, classes, methods, constants, and types. Use this with OpenClaw, Claude, ChatGPT, Cursor, Windsurf, or any other AI tool that accepts text input. You can copy the full output to your clipboard or download it as a .txt file.
Extracted by GitExtract — free GitHub repo to text converter for AI. Built by Nikandr Surkov.