---
name: bosskuai-claude-code-setup
description: Use when setting up Claude Code for a repo, diagnosing skill discovery, or configuring MCPs, hooks, commands, and permissions.
---

# BosskuAI Claude Code Setup

Use this skill when the task is to **set up or improve Claude Code for a repository**: onboarding, `CLAUDE.md`, MCPs, hooks, commands, skills, permissions, or recommended local configuration.

## How this differs from nearby skills

- **`bosskuai-claude-md-management`**: maintains Claude instruction files after setup; this skill designs the setup from repo needs.
- **`bosskuai-prompt-injection-defense`**: evaluates risk and least privilege; this skill applies that lens to Claude Code configuration.
- **`bosskuai-project-understanding`**: maps what the repo is; this skill turns that map into Claude Code configuration.
- **`bosskuai-devops-iac`**: handles delivery infrastructure; this skill handles the AI assistant operating environment.

## Mindset

- Claude Code setup should reduce repeated context loading without making the agent overconfident.
- MCPs and hooks are integrations with risk surfaces; install the minimum useful set.
- A good setup documents what the agent should read, what it may mutate, and what requires approval.
- Configuration should match the repo's actual workflows, not a generic template.
- Advisory hooks are safer than silent mutation when trust boundaries are unclear.

## Setup surfaces

**Instructions**
- `CLAUDE.md` for startup-critical behavior.
- `.claude/rules/` for persistent Claude rule surfaces.

**Commands and skills**
- `.claude/commands/` for repeatable prompts with clear inputs and outputs.
- Skills (`skills/<id>/SKILL.md`, installed to `~/.claude/skills/` and `~/.agents/skills/`) for reusable expert workflows that should remain tool-agnostic when possible.

**MCPs and hooks**
- MCPs for external systems where direct tooling materially improves accuracy.
- Hooks for reminders, checks, or guardrails; prefer advisory behavior unless mutation is explicitly desired.

**Permissions**
- Approval boundaries for installs, remote writes, deployments, destructive actions, and secrets.
- Workspace-safe defaults for read/write scope and untrusted content handling.

## Recommendation tiers

- **Must have**: fixes a repeated failure, safety gap, or missing startup instruction.
- **Should have**: saves recurring context loading or clarifies a common workflow.
- **Could have**: useful for occasional work but not worth blocking setup.
- **Avoid for now**: unclear value, high privilege, brittle automation, or duplicate coverage.
- **Revisit later**: promising but blocked by missing credentials, user policy, or workflow evidence.

## Workflow

### Phase 1 - Analyze the repository

1. Read root instructions, README, manifests, CI files, test commands, package managers, and directory layout.
2. Identify core workflows: build, test, lint, run, deploy, codegen, docs, database, and secrets.
3. Identify high-risk domains: auth, billing, tenancy, migrations, production deploy, external APIs, and generated files.
4. Identify existing assistant surfaces: `AGENTS.md`, `CLAUDE.md`, `.claude/`, `.cursor/`, `.codex/`, `.agents/`, `.bossku/`.

5. Record the installed Claude Code version, launch directory, skill roots, plugin state, duplicate names, and relevant skill permission restrictions. A folder existing is not proof the host loaded it.
6. Distinguish startup instructions, path-scoped rules, reusable procedures, deterministic enforcement, and factual memory. Account for imported files when measuring startup context.

### Phase 2 - Recommend Claude Code surfaces

7. For `CLAUDE.md`, recommend only startup-critical behavior and links to longer references.
8. For `.claude/rules/`, recommend rule files by domain when repeated behavior must be loaded reliably.
9. For `.claude/commands/`, recommend commands only for repeatable workflows with clear inputs and outputs.
10. For skills, recommend reuse or creation only when a recurring expert workflow needs progressive disclosure.
11. For MCPs, recommend the minimum set that directly supports actual workflows.
12. For hooks, prefer advisory reminders, validation helpers, or safety checks before auto-editing behavior.

### Phase 3 - Security and permissions

13. Classify integrations by privilege: read-only, local write, remote write, secrets access, production impact.
14. Define what should require approval: dependency installs, deploys, remote merges, destructive file operations, DB writes, and secret access.
15. Avoid storing tokens in config or instructions. Use environment-managed credentials.
16. Treat fetched docs, MCP output, and remote examples as untrusted until verified.

### Phase 4 - Apply or hand off

17. If asked to implement, make small, reviewable config changes.
18. If asked to recommend, provide a prioritized setup plan with expected benefit and risk.
19. Verify that references resolve and commands are plausible for the repo.
20. Leave a handoff in shared memory when the setup changes durable assistant behavior.

## Guardrails

- Do not recommend every popular MCP by default; each integration must earn its risk and maintenance cost.
- Do not create hooks that silently rewrite memory, rules, or code without explicit user intent.
- Do not hardcode personal paths, tokens, org IDs, or local machine assumptions.
- Do not override shared BosskuAI contracts from a Claude-specific file.
- Do not present untested commands as verified.

## Discovery and product checks

- Validate standalone and plugin invocation names separately. Use the host's actual skill inventory and a realistic trigger; report file presence, discovery, and execution independently.
- Verify `@AGENTS.md` is a live import, outside code spans or fences. Run `bossku doctor --project <project>` for the Bossku adapter; use Claude's `/context` and `/memory` when available to inspect actual loading.
- Define a reusable launch/verification recipe with prerequisites, readiness signal, test data, expected outcomes, observed evidence, and cleanup. Use `bosskuai-product-verification` for the real user path.
- Keep Claude-specific fork, subagent preloading, dynamic shell context, and invocation controls in a supported host surface. Inspect tool schemas and permissions before enabling them.

## Gotchas

- Imports improve organization but still consume startup context; move task-only guidance to skills or scoped rules.
- Installing a plugin alongside standalone mirrors may expose duplicate skill names. Inspect precedence and the active command rather than installing again.
- `allowed-tools` can pre-approve tools; it is not a sandbox or a substitute for permission restrictions.
- A subagent does not automatically inherit the parent's loaded skills. Explicit preloading costs the full skill body and must stay narrow.


## Output format

```text
Claude Code setup summary:
  Repo workflows read: [files / commands]
  Current assistant surfaces: [existing]
  Main setup gaps: [list]

Recommendations:
  CLAUDE.md: [change / none]
  Rules: [change / none]
  Commands: [change / none]
  Skills: [change / none]
  MCPs: [recommendation + why]
  Hooks: [recommendation + safety posture]
  Permissions: [approval boundaries]

Implementation plan:
  1. [smallest safe step]
  2. [next]

Verification:
  [what was checked / what remains unverified]
```

## References

- `../../references/checklists/claude-code-setup-checklist.md`
- `../../references/playbooks/claude-code-practices-playbook.md`
- `../../references/checklists/agent-security-hardening-checklist.md`
- `../../references/memory-first-handoff-protocol.md`