web-to-markdown

This configuration embodies several key principles:

1. Plugin-First Architecture - Modular, composable extensions over monolithic configs
2. Absolute Paths - Reference plugins from single source of truth (~/dev/agents)
3. Skills Over Agents - Reusable skill blocks for common patterns
4. Documentation as Code - Coding standards travel with config
5. Meta-Tooling - Tools to create tools (create-command, create-skill, etc.)
6. DRY Configuration - One place to maintain, many places to reference

```

.

├── .claude/ # Project config (references plugins via absolute paths)

│ ├── settings.json # Simplified plugin-based config

│ └── settings.local.json # Local overrides (not tracked)

├── .claude-plugin/ # Plugin marketplace definition

│ └── marketplace.json # Marketplace configuration

├── plugins/ # All skills organized in plugins

│ ├── meta-work/ # Meta-work: commands, skills, plugins, docs

│ │ ├── .claude-plugin/ # Plugin manifest

│ │ ├── commands/ # /create-command, /create-agent, /create-doc, /create-plugin

│ │ ├── skills/ # prompting, claude-permissions, skill-creator, plugin-creator

│ │ └── README.md

│ ├── development-lifecycle/ # Dev workflow: git, code review, planning

│ │ ├── .claude-plugin/

│ │ ├── commands/ # /execute-implementation

│ │ ├── agents/ # deep-research, deep-context-gatherer

│ │ ├── skills/ # analyze-size, git-commit, code-review, start-feature, finish-feature, fix-eslint, dev-work-summary

│ │ └── README.md

│ ├── typescript-coding/ # TypeScript/JavaScript development guidance

│ │ ├── .claude-plugin/

│ │ ├── skills/

│ │ │ └── typescript-coding/

│ │ │ ├── SKILL.md

│ │ │ ├── STACK.md # Tech stack overview

│ │ │ ├── TOOLING.md # Tool usage patterns

│ │ │ ├── TESTING.md # Testing patterns

│ │ │ └── LOGGING.md # Logging strategies

│ │ └── README.md

│ ├── knowledge-work/ # Knowledge capture, web research, ideation

│ │ ├── .claude-plugin/

│ │ ├── skills/ # gemini-research, gh-code-search, brainwriting, readwise-api, scratchpad-fetch, web-to-markdown

│ │ └── README.md

│ └── basic-skills/ # Foundational utilities

│ ├── .claude-plugin/

│ ├── skills/ # timestamp

│ └── README.md

├── docs/ # Project documentation and coding standards

│ ├── CODING_STYLE.md

│ ├── DEVELOPMENT_WORKFLOW.md

│ ├── roadmap/ # Development roadmap and planning

│ │ └── overview.md

│ ├── scratchpad/ # Web fetched content cache

│ └── web-captures/ # Playwright web-to-markdown captures

├── hooks/ # Claude Code hooks

│ ├── skill-reminder/ # Contextual skill reminder hook

│ │ └── prompt-hook.ts # UserPromptSubmit hook (TypeScript)

│ └── tts-readback/ # Text-to-speech readback hook

│ ├── stop-hook.ts # Hook implementation

│ ├── package.json # Dependencies

│ └── README.md # Hook documentation

├── CLAUDE.md # Global Claude instructions

├── settings.json # Claude Code settings

├── setup-project.sh # Automated project bootstrap script

└── README.md

```

Quick Setup (Automated)

Use the provided bootstrap script to set up new projects:

```bash

# Bootstrap a new project

./setup-project.sh ~/path/to/your-project

# Use current directory

./setup-project.sh .

```

The script will:

• ✓ Create .claude directory if needed
• ✓ Create settings.json with absolute paths to all plugins
• ✓ Configure hooks (TTS readback, skill reminder)
• ✓ Safe to re-run (won't overwrite existing files)

Manual Setup

If you prefer manual configuration, create .claude/settings.json in your project:

```json

{

"$schema": "https://json.schemastore.org/claude-code-settings.json",

"plugins": [

"/Users/Uberto.Rapizzi/dev/agents/plugins/meta-work",

"/Users/Uberto.Rapizzi/dev/agents/plugins/development-lifecycle",

"/Users/Uberto.Rapizzi/dev/agents/plugins/typescript-coding",

"/Users/Uberto.Rapizzi/dev/agents/plugins/knowledge-work",

"/Users/Uberto.Rapizzi/dev/agents/plugins/basic-skills"

],

"hooks": {

"Stop": [{

"matcher": "",

"hooks": [{

"type": "command",

"command": "/Users/Uberto.Rapizzi/dev/agents/hooks/tts-readback/node_modules/.bin/tsx /Users/Uberto.Rapizzi/dev/agents/hooks/tts-readback/stop-hook.ts",

"timeout": 30

}]

}],

"UserPromptSubmit": [{

"hooks": [{

"type": "command",

"command": "node --experimental-strip-types /Users/Uberto.Rapizzi/dev/agents/hooks/skill-reminder/prompt-hook.ts",

"timeout": 5

}]

}]

}

}

```

Note: The paths above are example absolute paths. Replace /Users/Uberto.Rapizzi/dev/agents with the actual path to your cloned agents directory. The setup-project.sh script automatically resolves these paths for you.

Hook Details:

• prompt-hook.ts: Uses Node.js native type stripping (Node 22.6+), no build step required
• stop-hook.ts: Requires tsx for Kokoro.js TTS library compatibility

Verifying Setup

After running setup-project.sh, verify your configuration:

1. Plugin Loading:

```bash

cd /path/to/your-project

claude /skills

# Expected: 19 skills from 5 plugins

# - meta-work (4 skills)

# - development-lifecycle (7 skills)

# - typescript-coding (1 skill)

# - knowledge-work (6 skills)

# - basic-skills (1 skill)

```

2. Commands Available:

```bash

claude /meta-work:create-command --help

# Should show usage info, not "command not found"

```

3. Hooks Configured:

```bash

# Check hooks in your project settings

cat .claude/settings.json | grep -A 5 hooks

# Should show Stop hook (TTS) and UserPromptSubmit hook (skill-reminder)

```

4. Documentation Referenced:

```bash

# Verify CLAUDE.md references global docs

cat .claude/CLAUDE.md 2>/dev/null || cat CLAUDE.md

# Should reference @docs/CODING_STYLE.md and @docs/DEVELOPMENT_WORKFLOW.md

```

Troubleshooting:

• If skills don't appear: Check plugin paths are absolute, not relative
• If hooks don't fire: Verify hook script is executable and paths are correct
• If commands fail: Ensure you're in a project with .claude/settings.json configured

Architecture Overview 🏗️

Skills = Self-contained modules with SKILL.md frontmatter

• Core skills: /skills (shared across projects)
• Plugin-scoped: plugins/{name}/skills (domain-specific)
• Invoke: Skill(name) or Skill(plugin:name)

Commands = Slash commands for direct instructions

• Format: /command-name [args]
• Simple operations, no complex reasoning

Agents = Specialized AI reasoning agents

• Format: @plugin:agent-name
• Complex multi-step tasks, parallel executio