A collection of practical patterns and best practices learned through real-world Claude Code usage
This repository contains 39 battle-tested skills extracted from actual Claude Code development sessions, following the Agent Skills standard.
English | 日本語
skills/
├── ai-era-architecture-principles/SKILL.md
├── brainstorming-communication/SKILL.md
├── cjk-aware-text-metrics/SKILL.md
├── ...
└── zenn-textlint-workarounds/SKILL.md
Each skill lives in skills/{skill-name}/SKILL.md with YAML frontmatter for discovery by Agent Skills-compatible tools.
| Skill | Description |
|---|---|
| ai-era-architecture-principles | Framework adoption decision matrix: custom vs large frameworks in the Claude Code era |
| algorithm-migration-with-rollback | Rollback-safe migration pattern for core algorithms (encryption, hashing, ML) with persisted data |
| service-layer-extraction | Extract business logic from Typer/Click CLI into a testable service layer |
| Skill | Description |
|---|---|
| claude-code-tool-patterns | Large file write perf, Edit refresh pattern, Hook JSON escape trap |
| claude-code-self-generation-over-api | Try self-generation before API calls on Max plan |
| claude-code-mcp-manual-install | Add MCP servers from within a session via jq-based ~/.claude.json editing |
| parallel-subagent-batch-merge | Generate 50+ items with parallel subagents and merge outputs |
| skill-stocktaking-process | 4-step skill consolidation with character budget awareness |
| directory-structure-enforcement-hooks | PreToolUse + Stop hook 3-layer defense for directory rules |
| cross-source-fact-verification | Fact-check drafts against multiple independent sources |
| Skill | Description |
|---|---|
| cjk-aware-text-metrics | CJK/Latin weighted token estimation for multilingual pipelines |
| cost-aware-llm-pipeline | LLM cost control via model routing, budget tracking, retry, and prompt caching |
| data-generation-quality-metrics-loop | Iterative generate-measure-fix loops with quantitative metrics |
| deep-research-api-landscape | Official Deep Research APIs (OpenAI, Gemini, Perplexity) over browser automation |
| keyword-based-llm-eval | Evaluate LLM-generated structured output with keyword matching and F1 metrics |
| long-document-llm-pipeline | Process 50K+ char documents through LLM APIs with section splitting and batch cost reduction |
| regex-vs-llm-structured-text | Parse structured text with regex first, add LLM only for low-confidence edge cases |
| Skill | Description |
|---|---|
| root-cause-challenge-pattern | 5-step decision framework: challenge assumptions before adding complexity |
| brainstorming-communication | Communication protocol for idea exploration vs implementation phases |
| json-data-validation-test-design | Layered pytest validation for auto-generated JSON data |
| Skill | Description |
|---|---|
| backward-compatible-frozen-extension | Extend frozen dataclass or Pydantic pipeline with new fields without breaking consumers |
| content-hash-cache-pattern | SHA-256 content-hash keying with frozen CacheEntry for expensive file processing |
| mock-friendly-api-layering | Fix mock assertion failures from public functions forwarding internal params to shared helpers |
| python-immutable-accumulator | Frozen dataclass + tuple accumulation with __slots__ gotcha |
| python-optional-dependencies | pyproject.toml extras, runtime checks, factory pattern |
| python-module-to-package-refactor | Module-to-package refactoring with mock.patch target updates |
| textual-tui-pipeline-interception | Add interactive review/approval step to CLI pipeline using Textual TUI |
| Skill | Description |
|---|---|
| immutable-model-updates | Thread-safe immutable state updates for Swift model structs |
| protocol-di-testing | Test Swift code with protocol-based dependency injection for file system, network, APIs |
| swift-actor-persistence | Thread-safe data persistence layer using Swift actors with in-memory cache and file storage |
| swift-codable-decode-diagnosis | Debug Swift Codable JSON decode errors with vague localizedDescription messages |
| xcode-package-swift-misidentification | Fix simulator launch failure caused by Package.swift misidentification |
| xcode-pbxproj-file-registration | Register .swift files added outside Xcode in 4 pbxproj sections |
| Skill | Description |
|---|---|
| tech-writing-patterns | Cross-posting, tone adjustment, quality patterns |
| zenn-context-driven-writing | Context collection and structuring workflow before drafting |
| zenn-qiita-crosspost-workflow | Automated Zenn-to-Qiita conversion pipeline |
| prh-hyphen-regex-escape | Node.js 20+ unicode regex incompatibility with prh hyphen patterns |
| zenn-markdownlint-config | Zenn-specific markdownlint-cli2 rule overrides |
| zenn-textlint-workarounds | Known false positives and workarounds for Zenn articles |
# Copy a single skill to your global learned skills
cp skills/python-immutable-accumulator/SKILL.md \
~/.claude/skills/learned/python-immutable-accumulator.md
# Or to a project
cp skills/zenn-markdownlint-config/SKILL.md \
your-project/.claude/skills/learned/zenn-markdownlint-config.md# Copy all skills (as flat .md files for Claude Code compatibility)
for dir in skills/*/; do
name=$(basename "$dir")
cp "$dir/SKILL.md" ~/.claude/skills/learned/"$name".md
doneEach SKILL.md includes YAML frontmatter following the Agent Skills specification:
---
name: skill-name
description: "Use when ... trigger phrase. Brief description."
license: MIT
metadata:
author: shimo4228
version: "1.0"
extracted: "2026-02-08"
---Compatible with:
- agnix — Agent Skills validator
- SkillsMP — Agent Skills marketplace
- SkillHub — Skill discovery platform
- Share your learned skills -- Extract patterns from your own Claude Code sessions
- Improve existing skills -- Add examples, clarify explanations
- Report issues -- Found a gotcha that's outdated? Let us know
---
name: your-skill-name
description: "Use when ... Brief description."
license: MIT
metadata:
author: your-github-username
version: "1.0"
extracted: "YYYY-MM-DD"
---
# Skill Title
**Extracted:** YYYY-MM-DD
**Context:** Brief problem context
## Problem
Clear statement of the problem
## Solution
Concrete solution with code examples
## When to Use
Specific scenarios where this skill appliesMIT License -- see LICENSE file for details
Created by: @shimo4228 Last Updated: 2026-02-14