How Agent Skills Use Discovery, Invocation, and the Portable SKILL.md Format

Agent Skills in the AI Engineering from Scratch curriculum rely on a portable SKILL.md manifest to standardize discovery, invocation, and progress tracking across any compatible host environment.

Agent Skills represent a structured approach to learning AI engineering through portable, executable modules. In the rohitg00/ai-engineering-from-scratch repository, these skills use a markdown-based specification that enables host-agnostic discovery and invocation without requiring environment-specific wrappers.

The Portable SKILL.md Manifest

Every Agent Skill is defined by a SKILL.md file that lives alongside the skill implementation, such as /.claude/skills/learn-agent-skills/SKILL.md. According to the source code, the header of this file contains a simple front-matter block (lines 1–9) that declares the skill’s name and description. Because the file is pure markdown, any host capable of reading files—whether Codex, Claude Code, or a compatible CLI—can interpret the same instructions without requiring host-specific wrappers.

Host-Agnostic Command Names

The manifest defines a canonical command name that remains consistent across environments. Lines 22–26 of the skill definition specify the portable identifier learn-agent-skills, allowing learners to invoke the skill using identical syntax regardless of their host platform:

# Invoking an Agent Skill across different hosts

learn-agent-skills          # Codex host

/learn-agent-skills         # Claude Code host

Discovery Mechanisms in Agent Skills

Discovery is treated as an explicit, verifiable checkpoint rather than inferred behavior. In the Learn Agent Skills module, the manifest marks specific discovery checkpoints at line 59, while line 155 references lesson 13/24, which tasks learners with distinguishing "discovery, catalog metadata, body activation, and reference or script loading."

Learners record each discovery observation in the progress file AGENT-SKILLS-LEARNING.md, creating an auditable trail of what was found rather than assumed.

Recording Discovery Evidence

The discovery process requires learners to document findings in a structured markdown table. The SKILL.md defines a progress tracking schema (lines 92–99) that captures the lesson order, status, and concrete evidence:

# Recording a discovery step in AGENT-SKILLS-LEARNING.md

| Order | Lesson | Status | Evidence | Completed |
|------:|--------|--------|----------|-----------|
| 2    | 13/24  | In progress | Discovered catalog metadata via `skill discover` | |

Skill Invocation Protocol

Invocation is architected as a discrete checkpoint separate from discovery. The skill manifest instructs learners to "create a minimal skill, install the complete reviewer bundle into a real host, invoke it explicitly, verify the report, and remove it cleanly" (line 53). This ensures that invocation is tested against real host environments rather than simulated scenarios.

The portable command syntax enables consistent execution across Codex, Claude Code, and other compatible hosts without rewriting command structures.

Verifying Invocation Steps

When recording invocation in the learning journal, learners document the specific command used and the host response:

# Recording an invocation step

| Order | Lesson | Status | Evidence | Completed |
|------:|--------|--------|----------|-----------|
| 3    | 13/25  | Next | Invoked skill with `skill invoke --name learn-agent-skills` | |

Progress Tracking Across the Learning Path

The Agent Skills curriculum uses multiple coordinated files to maintain state. The learning-paths/agent-skills.json manifest lists the ordered lessons, while AGENT-SKILLS-LEARNING.md serves as the learner-generated ledger. This separation of concerns allows the portable SKILL.md to remain environment-agnostic while the JSON manifest handles curriculum sequencing.

The progress table defined in the skill specification (lines 92–99) drives learners through discovery, invocation, permission handling, evaluation, and packaging in deterministic, lock-step fashion, ensuring each phase produces verifiable evidence before proceeding.

Summary

• The SKILL.md file provides a host-agnostic manifest using standard markdown front-matter (lines 1–9) that any compatible host can parse.
• Discovery is explicitly checkpointed at line 59, requiring learners to catalog metadata and distinguish activation phases through lesson 13/24 (line 155).
• Invocation uses the portable command learn-agent-skills (lines 22–26) and follows a strict protocol: install, invoke, verify, and remove (line 53).
• Progress tracking relies on a structured markdown table defined at lines 92–99, recording evidence in AGENT-SKILLS-LEARNING.md for auditability.

Frequently Asked Questions

What makes the SKILL.md format portable across different AI hosts?

The format uses pure markdown with a simple front-matter block (lines 1–9) rather than host-specific configuration syntax. Because it contains no proprietary extensions, any host that can read text files—including Codex, Claude Code, or custom CLIs—can parse the skill definition and execute the standardized command learn-agent-skills without environment-specific wrappers.

How does discovery differ from invocation in Agent Skills?

Discovery involves identifying and cataloging the skill's metadata, body activation methods, and reference scripts (line 155), which learners record as verifiable observations in AGENT-SKILLS-LEARNING.md. Invocation, conversely, is the active execution of the skill using the canonical command name (lines 22–26) and requires installing the skill into a real host, running it, verifying the output, and cleanly removing it (line 53).

Where is learner progress stored when working with Agent Skills?

Progress is documented in the learner-generated file AGENT-SKILLS-LEARNING.md, which uses the markdown table structure defined in the portable SKILL.md (lines 92–99). This table tracks the lesson order, current status, and specific evidence for each discovery and invocation step, while the curriculum sequence is managed separately in learning-paths/agent-skills.json.

Can Agent Skills be invoked on hosts other than Claude Code?

Yes. The skill definition specifies the command learn-agent-skills (lines 22–26) as the portable identifier, allowing execution on any compatible host. The repository demonstrates this portability by showing equivalent invocation syntax for both Codex (learn-agent-skills) and Claude Code (/learn-agent-skills), with the underlying SKILL.md remaining identical across environments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}