How to Create a Subagent with an Agent Skill

Core concepts

Before creating anything, it helps to separate four things that beginners often mix up. They are complementary, not interchangeable.

AGENTS.md
    ↓
Project-wide rules

Skill
    ↓
How a recurring task should be performed

Subagent
    ↓
Who performs a delegated task

User prompt
    ↓
What should be done right now

Each layer answers a different question. None of them replaces the others: rules constrain the work, Skills describe how the work is done, subagents decide who does it, and your prompt states what should happen right now.

1. Install the setup skill

This tutorial is built around Setting Up Agentic Projects from the GiovanniL30/ai-skills repository. That skill prepares an existing or new repository for agentic development and can configure tool-native subagent roles when the target coding tool is known and supported.

npx skills add https://github.com/GiovanniL30/ai-skills/tree/main/skills --skill setting-up-agentic-projects

• npx skills add installs an Agent Skill from a repository.
• GiovanniL30/ai-skills is the Skill repository.
• --skill setting-up-agentic-projects selects only the setup skill.
• The exact installation location depends on your agent or coding tool.

Do not assume that every AI coding tool discovers skills in exactly the same directory. Check your tool's own skill discovery documentation if you need the precise path.

npx skills add https://github.com/GiovanniL30/ai-skills/tree/main/skills --skill setting-up-agentic-projects

npx skills add https://github.com/GiovanniL30/ai-skills/tree/main/skills --skill setting-up-agentic-projects --global

Use $setting-up-agentic-projects to configure this project for agentic development.

Use the setting-up-agentic-projects skill to configure this project for agentic development.

Important: installing a Skill only installs instructions. It does not create a subagent, and it does not change your project. Nothing is configured until you ask the skill to do so, which is what Part 3 covers.

2. Start with a normal project

Use an ordinary project. Nothing agent-specific is required yet:

my-project/
├── src/
├── tests/
├── package.json
└── README.md

You do not need to manually create agent configuration files first. The purpose of setting-up-agentic-projects is to inspect the existing project and determine what setup is actually appropriate.

3. Ask the setup skill to create a reviewer subagent

Copy this prompt into your coding agent from the project root:

Use the setting-up-agentic-projects skill.

Prepare this repository for agentic development and create a
specialized code-reviewer subagent.

Requirements:

- Inspect the existing repository before making changes.
- Inspect the existing project instructions.
- Inspect the installed Agent Skills.
- Use the reviewing-code skill for the review workflow.
- Configure the reviewer as a specialized read-only role.
- The reviewer should focus on correctness, security, performance,
  maintainability, and regressions.
- The reviewer must not modify application code.
- Use the native subagent configuration supported by the coding tool
  currently being used.
- Verify the current official documentation before creating
  tool-specific configuration.
- Do not invent configuration paths or fields.
- Keep the setup minimal and avoid duplicating the skill contents.
- Verify that the resulting configuration is valid.
- Report which files were created or changed and why.

This is intentionally a setup request, not a code-review request. The setup skill's job is to prepare the project and configure the role - it does not perform a review yet. Part 6 covers the separate task prompt that actually runs the reviewer.

Note: reviewing-code is used throughout this tutorial as an illustrative example of a review-workflow skill name. Substitute the review workflow your own project uses.

4. What the setup skill does

User
 │
 │ "Create a reviewer subagent"
 ▼
setting-up-agentic-projects
 │
 ├── Discover repository
 │
 ├── Inspect AGENTS.md
 │
 ├── Inspect existing Skills
 │
 ├── Identify coding tool
 │
 ├── Verify supported subagent configuration
 │
 ├── Create minimal configuration
 │
 └── Verify setup
        │
        ▼
   Reviewer Subagent
        │
        ▼
   reviewing-code Skill

The setup skill does not blindly generate a generic agent file. It determines the appropriate configuration based on the actual coding tool in use, verifies that the tool supports custom subagents, and checks the current official documentation before writing anything. If the tool has no supported mechanism, it should tell you instead of inventing a configuration path.

5. Skill and subagent working together

Reviewer Subagent
       │
       ▼
reviewing-code Skill
       │
       ▼
Repository
       │
       ▼
Review Findings

This distinction is the key lesson of the tutorial. The subagent decides who performs the work and what it is allowed to do; the Skill decides how that type of work is performed. Because they are separate, many roles can share the same Skill.

6. Run the subagent

Once the setup is complete, use a second prompt that actually uses the configured reviewer:

Use the reviewer subagent to review the current repository.

Follow the reviewing-code skill.

Review the latest changes for:

- correctness
- security
- performance
- maintainability
- regressions

Do not modify any files.

For every finding, provide:

1. Severity
2. File path
3. Line or relevant location
4. Problem
5. Why it matters
6. Suggested fix

Do not report speculative issues.

Finish with an overall assessment.

This is now a task prompt, while the prompt in Part 3 was a setup prompt. The setup prompt configures the project once; the task prompt can be reused every time you want a review.

7. The resulting architecture

                    PROJECT
                       │
                       ▼
                  AGENTS.md
                       │
          ┌────────────┴────────────┐
          │                         │
          ▼                         ▼
 Reviewer Subagent            Other Agents
          │
          ▼
  reviewing-code Skill
          │
          ▼
       Repository

Multiple specialized subagents can reuse the same Skills:

Reviewer Agent
      └── reviewing-code

Debugger Agent
      └── debugging-code

Frontend Agent
      └── designing-frontend

Implementation Agent
      └── implementing-features

This is exactly why Skills and subagents are separate concepts: roles come and go, but the workflows they depend on stay shared and consistent.

8. Use the setup skill for other roles

The same pattern works for any specialized role. For example, a frontend designer:

Use the setting-up-agentic-projects skill.

Create a specialized frontend-design subagent for this project.

Requirements:

- Use the designing-frontend skill.
- Inspect the existing frontend architecture and design documentation.
- Make the role focused on UI/UX and frontend architecture.
- Do not modify application code during design review.
- Use the native subagent configuration for the current coding tool.
- Verify the official tool documentation before creating the configuration.
- Keep the role minimal and avoid duplicating the Skill.

Frontend Designer Subagent
          │
          ▼
 designing-frontend
          │
          ▼
Frontend project

See the Designing Frontend skill for the workflow this role would follow.

9. Tool-specific configuration

This section is important. Agent Skills are designed to be portable, while custom subagent configuration is often tool-specific:

The Skill can be portable across compatible coding agents, but subagent configuration may be different for each tool. setting-up-agentic-projects checks the target tool and its current documentation before generating native configuration.

Conceptually, the same request results in different native output:

Codex
  → native Codex subagent configuration

Claude Code
  → native Claude Code subagent configuration

OpenCode
  → native OpenCode agent configuration

Other tools
  → verify their current agent configuration support

• Do not treat any single directory (for example .agents/agents/) as a universal subagent location.
• Not every tool supports custom subagents; verify before configuring.
• The tutorial deliberately hardcodes no tool-specific configuration syntax - the setup skill reads the current official documentation instead.
• Native discovery must be verified for your target tool; a directory alone does not activate an agent.

10. Do not manually duplicate Skills

A common anti-pattern is copying the whole workflow into the agent definition:

reviewer-agent.md

"You are a reviewer.
Check security.
Check performance.
Check maintainability.
Check correctness.
..."

This duplicates the workflow already provided by reviewing-code/SKILL.md, and the two copies will drift apart. Prefer:

Reviewer Subagent
      │
      └── uses reviewing-code

The subagent defines the role and boundaries. The Skill defines the reusable workflow.

11. When you actually need a subagent

Do I need a specialized worker?
          │
          ├── No
          │    ↓
          │  Use a prompt + Skill
          │
          └── Yes
               ↓
       Create/configure a subagent
               │
               ↓
          Give it a Skill

Not every task needs a subagent. A subagent is useful when:

• the task benefits from independent context
• the role needs different permissions
• the task can be performed in parallel
• the coding tool provides a useful native agent mechanism
• the role is repeated often

Otherwise, using a Skill directly from the main agent with a normal prompt may be simpler.

12. Common mistakes

Skill = Subagent

Skill = reusable expertise/workflow
Subagent = specialized worker/role

13. Quick reusable pattern

1. Install the Skill.
2. Ask setting-up-agentic-projects to inspect the project.
3. Specify the role you want.
4. Specify which Skill the role should use.
5. Specify permissions and boundaries.
6. Let the setup Skill determine the tool-native configuration.
7. Verify the configuration.
8. Run the subagent with a task-specific prompt.

Use the setting-up-agentic-projects skill.

Create/configure a specialized [ROLE] subagent.

The subagent should:

- [RESPONSIBILITY]
- [RESPONSIBILITY]
- [RESPONSIBILITY]

Use the [SKILL-NAME] skill.

Permissions:

- [READ-ONLY / WRITE / OTHER]

Constraints:

- [CONSTRAINT]
- [CONSTRAINT]

Use the native configuration supported by the current coding tool.
Verify the current official documentation before generating
tool-specific configuration.

Keep the setup minimal and avoid duplicating the Skill.
Verify the resulting configuration.

Save the template, fill in the brackets, and you have a setup prompt for any role. See the Setting Up Agentic Projects guide for the full workflow, and the use cases page for ready-made task prompts.

14. Final mental model

AGENTS.md
"What rules does this project follow?"

Skill
"How should this type of work be performed?"

Subagent
"Who should perform this specialized work?"

Prompt
"What do I want done right now?"

                User
                  │
                  ▼
               Prompt
                  │
                  ▼
             Subagent
                  │
                  ▼
                Skill
                  │
                  ▼
              Project

Takeaway: Use setting-up-agentic-projects when you want help preparing the project and configuring specialized agent roles. Use your task-specific Skills to give those roles reusable expertise.