Improve developer workflows using AI-assisted tooling

Key points

1. 1

   Skills are SKILL.md files with YAML frontmatter in .claude/skills/<name>/ (project, committed) or ~/.claude/skills/<name>/ (personal); plugins and managed settings can distribute them organization-wide. They are invoked as /name with $ARGUMENTS (or named arguments), load only when invoked or judged relevant, and supersede the older .claude/commands/ custom-command format. Frontmatter controls invocation: disable-model-invocation: true for side-effecting actions only a person should trigger, user-invocable: false for background knowledge, allowed-tools to pre-approve tools, context: fork to run in a subagent.

2. 2

   Keep CLAUDE.md short (target under 200 lines) and limited to facts Claude needs in every session: build and test commands, conventions, layout, always-do rules. Move multi-step procedures into skills and area-specific conventions into path-scoped .claude/rules/ files. Adherence drops when instructions are vague, conflicting or buried in a long file; capital letters and "MUST" do not fix that. @path imports still load at launch, so they organize text without saving tokens.

3. 3

   Plan mode (Shift+Tab, /plan prefix, or claude --permission-mode plan) lets Claude research and propose without editing; edits stay blocked until the plan is approved. Use it for large or risky changes to avoid expensive re-work, then approve into manual edit review, accept-edits or auto mode. Course-correct early with Escape and /rewind.

4. 4

   Permission modes set the baseline: default asks before edits, commands and network; acceptEdits auto-approves edits and common filesystem commands in the working directories; plan is read-only; dontAsk denies anything that would prompt (for locked-down CI); bypassPermissions skips all checks and is for isolated containers or VMs only. Layer allow, ask and deny rules on top; deny rules apply in every mode.

5. 5

   Subagents are Markdown files with frontmatter in .claude/agents/ (project, shared) or ~/.claude/agents/ (personal), with name, description, tools (allow-list), model, permissionMode and maxTurns. Each runs in its own context window and returns a summary, so use them to isolate verbose operations (test runs, log parsing, documentation fetching), to enforce read-only or tool-restricted exploration, and for parallel independent investigation. Prefer the main conversation for tightly iterative work or when phases share a lot of context. Subagent requests still cost tokens; give simple subagents a smaller model.

6. 6

   Hooks make workflow steps deterministic: a PostToolUse hook on Edit|Write can run a formatter, a PreToolUse hook can rewrite a test command to show only failures (reducing context), PreCompact can archive a transcript, SessionEnd can run cleanup. Configure them under the hooks key of a settings file, with a single-string matcher that uses | to combine tool names.

7. 7

   Headless mode (claude -p) runs Claude Code in scripts and CI: --output-format json returns the result, session ID, usage, total_cost_usd and any permission_denials; --json-schema gives structured output; --allowedTools and --permission-mode pre-approve exactly what the job needs; --max-turns bounds iterations; --bare skips auto-discovery of hooks, skills, MCP servers and CLAUDE.md for reproducible CI runs; --continue / --resume <id> chain follow-ups.

8. 8

   GitHub Actions: anthropics/claude-code-action responds to @claude mentions (interactive mode) or runs a prompt automatically on any event, including a schedule or every pull request (automation mode). Set it up with /install-github-app or manually by installing the Claude GitHub App and adding a secret. Never commit keys; store ANTHROPIC_API_KEY (or CLAUDE_CODE_OAUTH_TOKEN) as a GitHub secret, or use OIDC workload identity federation so no static key is stored. For an organization, install the app once at org level, use an org-level secret with a Console API key rather than a personal OAuth token, and share a reusable workflow. Cap cost with --max-turns in claude_args, workflow timeouts and concurrency limits; define review criteria in CLAUDE.md. Bedrock, Vertex and Foundry are supported through OIDC (use_bedrock, use_vertex, use_foundry).

9. 9

   Cost habits to teach: /clear between unrelated tasks; /compact with focus instructions; specific prompts instead of "improve this codebase"; match the model to the job (Sonnet for most coding, Opus for hard reasoning, Haiku for simple subagents); adjust effort or thinking for simple tasks; prefer CLI tools over MCP servers when both exist and disable unused servers; check /context and /usage.

10. 10

    Measuring adoption and impact: the Teams and Enterprise dashboard at claude.ai/analytics/claude-code shows daily active users, sessions, lines accepted, suggestion accept rate and, with the GitHub integration, PRs and lines shipped with Claude Code plus a leaderboard and CSV export. Console customers get usage, spend and per-member insights at platform.claude.com/claude-code and via the Claude Code Analytics API. Enterprise organizations can also use the Enterprise Analytics API. Cloud-provider usage is not included; for that, and for near-real-time per-developer cost anywhere, use OpenTelemetry with team attributes or an LLM gateway.

11. 11

    Use the data well: track adoption dips as a friction signal, find power users who can coach others, compare PRs per user before and after rollout alongside DORA or sprint metrics, and pilot with a small group to set a cost baseline before wider rollout.

12. 12

    Traps: pasting procedures into CLAUDE.md; personal skills or notes instead of a committed skill; bypass permissions as a speed-up for large refactors; using a personal OAuth token as a shared CI credential; parsing transcript files for metrics (internal format, privacy); and enabling prompt logging to measure productivity.

Read the source

• Extend Claude with skills
• Choose a permission mode (plan mode)
• Create custom subagents
• Hooks reference
• Run Claude Code programmatically (headless)
• Claude Code GitHub Actions
• Track team usage with analytics
• Manage costs effectively