Deep Dive into Skill Components

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:

---
name: repo-navigator
description: Analyze repository structure, detect tooling, and output a structured project map
trigger: When the user asks about repository structure, tooling, or project organization (e.g., "how is this project organized?", "what's the tech stack?", "analyze this repo")
---

# Repository Navigator Skill

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:

## Role
You are a repository analyst specializing in understanding project structure, build systems, and technology stacks.

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:

## Task
Analyze the current repository to:
1. Detect programming language(s) and frameworks
2. Identify package managers and dependency files
3. Find build, test, and development commands
4. Locate main entrypoints and key source directories
5. Output a structured map (Markdown table or JSON format)

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:

## Discovery Process
1. Check for language indicators:
   - Python: requirements.txt, setup.py, pyproject.toml, .py files
   - Node.js: package.json, node_modules/, .js/.ts files
   - Go: go.mod, go.sum, .go files
   - Rust: Cargo.toml, .rs files
   - Java: pom.xml, build.gradle, .java files

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:

2. Identify build/test commands:
   - Check package.json "scripts" section
   - Look for Makefile targets
   - Check CI configuration (.github/workflows/, .gitlab-ci.yml)
   - Examine setup.py or pyproject.toml for Python

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:

3. Find entrypoints:
   - package.json "main" field
   - Python __main__.py or setup.py entry_points
   - Go main.go files
   - Rust bin/ or lib.rs

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:

## Output Format
Present findings as a Markdown table:

| Category | Value |
|----------|-------|
| Languages | [detected languages] |
| Package Manager | [detected manager] |
| Test Command | [test command] |
| Build Command | [build command] |
| Main Entrypoint | [entry file] |
| Key Directories | [main dirs] |

Or as JSON if user requests that format.

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:

## Constraints
- Only analyze files that exist (don't assume)
- If multiple languages detected, list all
- If commands not found in standard locations, state "Not found in standard locations"

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!