Welcome back! In the previous lesson, we learned the difference between config.toml and skills, and we built a minimal "Hello Skill" to understand the basic structure. Now we're ready to go deeper.

In this lesson, we'll build a sophisticated Repo Navigator skill that can analyze any repository's structure, detect tooling and frameworks, and provide a comprehensive map of the project. This skill will serve as our master example for understanding all the components that make skills powerful and reusable.

By the end of this lesson, you'll understand how to craft detailed role definitions, create systematic procedures, structure outputs effectively, and add safety constraints - all the elements that make skills production-ready.

When you join a new project or explore an open-source repository, you face several recurring questions:

• What programming languages are used?
• What package manager and build tools are configured?
• How do I run tests and start the application?
• Where are the main entry points?
• Is there CI/CD configured?

Manually answering these questions requires scanning multiple files, understanding different ecosystem conventions, and piecing together information from various locations. A Repo Navigator skill automates this discovery process, providing instant, structured answers that help you get oriented quickly.

Let's build the Repo Navigator skill component by component. Create a file at .codex/skills/repo-navigator/SKILL.md and follow along as we add each piece.

Start by adding the metadata header to your SKILL.md file:

The metadata header (YAML front matter) provides essential information about the skill:

Name: A unique identifier used to reference this skill. Use lowercase with hyphens, like a URL slug. This name appears in logs and can be used to explicitly invoke the skill.

Description: A concise summary of what the skill does. This helps both humans and Codex understand the skill's purpose at a glance. Keep it to one sentence focusing on the outcome.

Trigger: The intent pattern that should activate this skill, with concrete examples. This enables Codex to autonomously decide when to use this skill versus its general capabilities.

Now add the role definition to your skill file:

The Role section establishes the persona and domain expertise for this skill. By defining a clear role, we're telling Codex what perspective to take and what knowledge to prioritize. A "repository analyst" will approach tasks differently than a "code reviewer" or "documentation writer." This role focuses on understanding and explaining, not modifying or judging.

Add the task breakdown next:

The Task section breaks down the objective into specific, measurable sub-goals. Each numbered item represents a concrete deliverable that can be verified. The numbered list provides a clear sequence and makes it easy to check completeness. Notice how each item is verifiable: you can check if languages were identified, if commands were found, and if the output matches the expected format.

Now we'll add the first part of the discovery process:

This is where we get into the procedural heart of the skill. The Discovery Process provides step-by-step instructions for gathering information.

Rather than trying to "guess" languages, we check for specific files that are standard in each ecosystem. This approach is deterministic (same files → same conclusion), verifiable (anyone can check if package.json exists), and transparent (the logic is explicit).

Notice we list several files per language to handle variations: requirements.txt for traditional Python projects, pyproject.toml for modern Python using PEP 518, and setup.py for Python packages. If Codex finds ANY of these files, it can confidently identify Python.

Add the command detection step:

The second discovery step focuses on finding the commands developers actually use. We check several locations because there's no universal standard: package.json scripts are common in Node.js projects, Makefiles are popular in C and Go, and CI configs often contain the "official" build/test commands.

Add the entrypoint detection step:

The final discovery step locates where code execution actually begins. Each ecosystem has different patterns: Node.js checks package.json for an explicit main field, Python looks for __main__.py or entry_points in config, Go finds main.go files, and Rust checks the bin/ directory or looks for lib.rs. Knowing the entrypoint helps developers understand where to start reading code and how the application is structured.

Add the output specification:

The Output Format section ensures consistency in how results are presented. The Markdown table provides visual clarity and scannability, making it easy to find specific information. By offering JSON as an alternative, we enable tool integration and programmatic access to the data. Using placeholder syntax like [detected languages] shows exactly what should go in each field while remaining readable.

Finally, add the constraints:

The Constraints section adds guardrails to ensure the skill behaves safely and honestly. "Only analyze files that exist" prevents hallucination - Codex must check for actual files, not guess based on probabilities. "If multiple languages detected, list all" prevents oversimplification of polyglot repositories. "If commands not found... state 'Not found'" teaches Codex to be transparent about limitations rather than inventing information.

Let's trace through how Codex uses this skill when a user asks "How is this project organized?":

1. Trigger matching: Codex recognizes this question matches the intent pattern
2. Role assumption: Codex adopts the "repository analyst" persona
3. Systematic discovery: Codex follows the discovery process step-by-step, checking for language files, commands, and entrypoints
4. Output formatting: Codex structures findings in the specified table format, verifying all constraints are met

Each component guides one part of this process, working together to produce reliable, consistent results.

One of the key benefits of well-structured skills is reusability. This Repo Navigator skill can be:

• Shared across projects: Drop it into any repository's .codex/skills/ directory
• Version controlled: Track changes to your skill definitions alongside code
• Forked and customized: Start with this base and add project-specific checks
• Composed into pipelines: Use as the first step in more complex workflows

The clear structure makes it easy to understand, modify, and maintain over time.

We've now explored every component of a sophisticated Codex skill:

• Metadata: Identity and intent-based trigger patterns
• Role: Persona and expertise domain
• Task: Measurable objectives
• Discovery Process: Step-by-step procedures
• Output Format: Consistent result structure
• Constraints: Safety and honesty guardrails

These components work together to create a skill that is autonomous (triggers automatically), reliable (follows clear procedures), transparent (shows its reasoning), and safe (respects boundaries).

Get ready to see your skill in action!