Commands & Skills - Agentic Engineering Framework

Commands vs skills

Commands

Human-invoked

A human types a command, and an agent executes it. Commands are the interface between your team and the agentic layer. Named, parameterized entry points.

/plan /build /commit /security-audit /explain

When to use: When a human wants to trigger a specific agent behavior on demand, outside the full workflow.

Skills

Agent-invoked

One agent calls another agent's capability programmatically. Skills let agents delegate sub-tasks. The calling agent gets structured output it can parse and act on.

run-tests lint-check dependency-check generate-commit-message

When to use: When a workflow phase needs to delegate a sub-task to a specialized capability.

The key difference: commands output human-readable text because humans read the result. Skills output structured JSON because agents parse the result.

Anatomy of a command

Here is a complete /commit command. YAML frontmatter declares metadata; the prompt body follows the 4-section anatomy.

---
name: commit
description: Stage changes, generate a conventional commit message, and commit.
parameters:
  - name: scope
    type: string
    required: false
    description: "Conventional commit scope (e.g., auth, api, ui)"
tools:
  - file_system.read
  - file_system.search
  - code_execution.shell
---

# /commit Command

## Role
You are a Release Engineer. Your job is to create a clean,
conventional commit from the current staged changes.

## Context
Current diff:
${git_diff_staged}

Recent commit history:
${recent_commits}

Scope (if provided): ${scope}

## Constraints
- Use Conventional Commits format: type(scope): description
- Types: feat, fix, refactor, test, docs, chore, perf, ci
- Subject line max 72 characters
- Body should explain WHY, not WHAT (the diff shows what)
- Do NOT amend previous commits
- Do NOT force push
- If no files are staged, tell the user and stop

## Output
1. Show the generated commit message to the user
2. Ask for confirmation (y/n)
3. If confirmed, execute: git commit -m "<message>"
4. Show the commit hash and summary

YAML Frontmatter Tool Permissions Parameter Declaration Confirmation Step

Anatomy of a skill

Skills declare a trigger and output_format instead of parameters. Their output is JSON, always structured, always parseable.

---
name: run-tests
description: Execute the test suite and return structured results.
trigger: called by build, test, or review phases
output_format: json
tools:
  - code_execution.shell
  - file_system.read
---

# run-tests Skill

## Role
You are a Test Runner. Execute the project's test suite and
return structured results that the calling agent can parse.

## Context
Test commands:
${test_commands}

Project type: ${project_type}      # node | python | go | rust | java

## Constraints
- Run ALL test suites, not just unit tests
- Do NOT modify test files or source code
- Do NOT skip failing tests
- If a test command fails to execute (not test failure,
  but command error), report it separately
- Timeout per test suite: 120 seconds

## Output Format
Return a JSON object:
{
  "status": "pass | fail | error",
  "suites": [
    {
      "name": "unit",
      "command": "npm test",
      "passed": 42,
      "failed": 1,
      "skipped": 0,
      "duration_ms": 3200,
      "failures": [
        {
          "test": "UserService.create should validate email",
          "file": "src/services/__tests__/user.test.ts",
          "line": 28,
          "error": "Expected 'invalid' to throw ValidationError",
          "type": "assertion"
        }
      ]
    }
  ],
  "coverage": { "lines": 84.2, "branches": 71.5, "functions": 89.1 },
  "total_passed": 42,
  "total_failed": 1,
  "total_skipped": 0
}

Structured JSON Output Agent-Parseable No Code Modification

Example commands

---
name: security-audit
description: Scan the codebase for OWASP Top 10 vulnerabilities.
parameters:
  - name: target
    type: string
    required: false
    description: "Specific directory or file to audit (default: entire project)"
tools:
  - file_system.read
  - file_system.search
  - code_execution.shell
---

# /security-audit Command

## Role
You are a Security Engineer specializing in application security.
Scan the codebase for vulnerabilities from the OWASP Top 10.

## Context
Project: ${project_name}
Target: ${target}
Language: ${primary_language}

### Codebase Summary
${codebase_summary}

## Constraints
- READ-ONLY. Do not modify any files.
- Focus on the OWASP Top 10 2021 categories:
  1. Broken Access Control
  2. Cryptographic Failures
  3. Injection (SQL, NoSQL, OS command, LDAP)
  4. Insecure Design
  5. Security Misconfiguration
  6. Vulnerable and Outdated Components
  7. Identification and Authentication Failures
  8. Software and Data Integrity Failures
  9. Security Logging and Monitoring Failures
  10. Server-Side Request Forgery (SSRF)
- Prioritize findings by severity: critical, high, medium, low
- Do NOT report false positives -- if unsure, mark as "needs review"

## Output Format
### Security Audit Report

**Overall Risk Level:** CRITICAL | HIGH | MEDIUM | LOW | CLEAN

| # | Category | Severity | File | Line | Finding | Remediation |
|---|----------|----------|------|------|---------|-------------|

### Summary
- Critical: (count)
- High: (count)
- Medium: (count)
- Low: (count)
- Needs Review: (count)

### Recommended Next Steps
(Prioritized list of remediations)

---
name: explain
description: Explain a function, module, or architecture decision with full context.
parameters:
  - name: target
    type: string
    required: true
    description: "File path, function name, or module to explain"
  - name: depth
    type: string
    required: false
    description: "brief | detailed | architecture (default: detailed)"
tools:
  - file_system.read
  - file_system.search
---

# /explain Command

## Role
You are a Senior Software Architect explaining code to a
colleague. Be clear, precise, and contextual.

## Context
Target: ${target}
Depth: ${depth}

### File Contents
${target_file_contents}

### Call Graph
${call_graph}

### Related Files
${related_files}

## Constraints
- READ-ONLY. Do not modify any files.
- Explain the WHAT, the WHY, and the HOW.
- Reference the actual code -- use line numbers.
- If the target depends on other modules, explain the relationship.
- Adjust depth based on the depth parameter:
  - brief: 2-3 sentences, what it does and why
  - detailed: full walkthrough with code references
  - architecture: how it fits into the broader system

## Output Format
### ${target}

**Purpose:** (one sentence)

**How It Works:**
(Explanation at the requested depth level)

**Dependencies:**
- (list of modules/functions this depends on)

**Called By:**
- (list of modules/functions that call this)

**Key Design Decisions:**
- (why was it built this way, not another way)

Example skills

---
name: lint-check
description: Run linter and categorize issues by severity.
trigger: called by build or review phases
output_format: json
tools:
  - code_execution.shell
  - file_system.read
---

# lint-check Skill

## Role
You are a Code Quality Analyst. Run the project's linter
and return categorized results.

## Context
Lint command: ${lint_command}
Project type: ${project_type}
Files changed: ${changed_files}

## Constraints
- Run the linter ONLY on changed files (if supported)
- Do NOT auto-fix issues -- report only
- Do NOT modify any files
- Categorize: error (must fix), warning (should fix), info (optional)

## Output Format
{
  "status": "clean | warnings | errors",
  "issues": [
    {
      "file": "src/services/user.ts",
      "line": 15,
      "column": 8,
      "severity": "error",
      "rule": "no-unused-vars",
      "message": "'tempData' is defined but never used"
    }
  ],
  "summary": { "errors": 1, "warnings": 3, "info": 0 }
}

---
name: dependency-check
description: Analyze dependencies for vulnerabilities and outdated packages.
trigger: called by review or monitor phases
output_format: json
tools:
  - code_execution.shell
  - file_system.read
---

# dependency-check Skill

## Role
You are a Dependency Analyst. Check the project's dependencies
for known vulnerabilities, outdated versions, and license issues.

## Context
Package file: ${package_file}     # package.json, requirements.txt, go.mod
Project type: ${project_type}

## Constraints
- Do NOT install or update any packages
- Do NOT modify lock files
- Use the project's native audit tool when available:
  - Node: npm audit / yarn audit
  - Python: pip-audit / safety
  - Go: govulncheck
  - Rust: cargo audit
- If no native tool exists, analyze the manifest file directly

## Output Format
{
  "status": "secure | vulnerable | unknown",
  "vulnerabilities": [
    {
      "package": "lodash",
      "installed_version": "4.17.15",
      "patched_version": "4.17.21",
      "severity": "high",
      "cve": "CVE-2021-23337",
      "description": "Prototype pollution in lodash"
    }
  ],
  "outdated": [
    {
      "package": "express",
      "installed": "4.17.1",
      "latest": "4.18.2",
      "update_type": "minor"
    }
  ],
  "summary": {
    "total_dependencies": 142,
    "vulnerabilities_critical": 0,
    "vulnerabilities_high": 1,
    "vulnerabilities_medium": 3,
    "outdated_major": 2,
    "outdated_minor": 8
  }
}

Composability: commands use skills

Commands and skills compose. A command invokes skills internally, chaining structured outputs.

The /build command's template can reference skills by name. When the build agent reaches the testing step, it invokes the run-tests skill, receives structured JSON back, and uses that data to decide whether to continue or report failures. The lint-check skill runs separately. The command orchestrates; the skills execute.

How to create your own

agentic-layer/
├── commands/
│   ├── commit.md
│   ├── security-audit.md
│   ├── explain.md
│   └── your-command.md        # add here
├── skills/
│   ├── run-tests.md
│   ├── lint-check.md
│   ├── dependency-check.md
│   └── your-skill.md          # add here

1

Choose command or skill

If a human triggers it, it is a command. If an agent triggers it, it is a skill.

2

Create the file

Markdown with YAML frontmatter. The filename becomes the invocation name.

3

Define the frontmatter

Name, description, parameters (commands) or trigger (skills), tool access, output format.

4

Write the prompt

Follow the 4-section anatomy: Role, Context, Constraints, Output Format.

5

Test it

Run against 2-3 representative inputs. Verify the output structure matches your spec.

6

Commit and share

The command/skill is now available to your entire team.

Naming conventions

Commands: lowercase, hyphenated. security-audit, not SecurityAudit.
Skills: lowercase, hyphenated. run-tests, not runTests.
Filenames: match invocation names. security-audit.md is invoked as /security-audit.

Custom Commands & Skills