Get startedGet started for free

Tightening the codebase-onboarding skill

A teammate just shared a personal skill called codebase-onboarding to help new hires get oriented in a service repo, and it's already installed at ~/.claude/skills/codebase-onboarding/SKILL.md.

There are two problems with it that waste context every time the skill loads:

  1. It leaves Claude with full edit and write permission (the skill is supposed to be read-only. New hires shouldn't get an agent that modifies code while they're just trying to look around).
  2. The body is huge because the entire architecture reference was pasted directly into SKILL.md instead of split into a separate file.

In this exercise you'll fix both: add an allowed-tools allowlist that restricts the skill to read-only discovery, and apply progressive disclosure by moving the architecture reference into its own file under references/

This exercise is part of the course

Introduction to Agent Skills

View Course

Exercise instructions

  • Start Claude Code with claude.
  • Ask Claude to read ~/.claude/skills/codebase-onboarding/SKILL.md and identify any design issues.
  • Ask Claude to add an allowed-tools field to the frontmatter restricting the skill to read-only discovery tools.
  • Ask Claude to apply progressive disclosure by moving the architecture reference into references/architecture.md and replacing it with a link.
  • Type /exit to exit Claude Code.

Hands-on interactive exercise

Turn theory into action with one of our interactive exercises

Start Exercise