Advanced Agent Skills Techniques [references, scripts, templates]

Mastered basic SKILL.md writing but want to do more complex things?

Agent Skills can achieve advanced functionality by using directories like references/, scripts/, and templates/ alongside SKILL.md.

This article covers advanced skill creation techniques.

Extended Skill Structure

Beyond the basic structure, you can add these directories:

Copymy-advanced-skill/
├── SKILL.md              # Required: main instructions
├── references/           # Detailed documentation
│   ├── coding-standards.md
│   └── security-checklist.md
├── scripts/              # Executable scripts
│   └── lint-check.sh
├── templates/            # Output templates
│   └── pr-description.md
└── assets/               # Other resources
    └── config.json

references/: Splitting Detailed Documentation

Why Split?

When SKILL.md gets too long, problems occur:

• Context window pressure
• Increased load time
• Difficult maintenance

When exceeding recommended size (SKILL.md body: under 5,000 tokens), split details into references/.

Split Example

SKILL.md (concise):

Copy---
name: code-review
description: Review PRs according to team coding standards
---

## Overview

Review PR code and verify compliance with team standards.

## Reference Documents

See details in:
- `references/coding-standards.md` - Coding standards
- `references/security-checklist.md` - Security checklist

references/coding-standards.md (detailed):

Copy# Coding Standards

## Naming Conventions

- Variables: camelCase
- Constants: UPPER_SNAKE_CASE
- Classes: PascalCase
- Files: kebab-case

## Indentation

- 2 spaces
- No tabs

[... detailed rules continue ...]

Progressive Disclosure

AI loads only necessary files based on task:

1. Initially only SKILL.md name and description
2. When skill is invoked, load full SKILL.md
3. Load references/ files as needed

This maintains performance even with extensive documentation.

scripts/: Automation Scripts

Example Usage

scripts/lint-check.sh:

Copy#!/bin/bash
# Run code lint check
# Usage: This script is called automatically during skill execution

echo "Running lint check..."
npm run lint --silent

if [ $? -eq 0 ]; then
    echo "✓ Lint check passed"
else
    echo "✗ Lint errors found"
    exit 1
fi

Reference in SKILL.md:

Copy## Execution Steps

1. First run `scripts/lint-check.sh` to check for lint errors
2. If errors exist, suggest fixes
3. If no errors, begin review

Caveats

• Tool dependency: scripts/ works in Claude Code but may not in other tools
• Security: Always review content of externally obtained scripts
• Idempotency: Design to produce same results on repeated execution

templates/: Standardizing Output Format

Example Usage

templates/pr-description.md:

Copy## Summary

<!-- 1-2 sentence overview of changes -->

## Change Type

- [ ] Feature addition
- [ ] Bug fix
- [ ] Refactoring
- [ ] Documentation update

## Details

### Changes

<!-- Specific changes -->

### Testing

<!-- How to test -->

## Related Issues

<!-- #123 etc. -->

Usage in SKILL.md:

Copy## Steps

1. Analyze changes
2. Generate description following `templates/pr-description.md` format
3. Check appropriate items

Benefits

• Unified PR format across team
• Prevents missing required information
• Easier for reviewers to read

Multi-File Coordination

Advanced Skill Example

Copysecurity-audit/
├── SKILL.md
├── references/
│   ├── owasp-top-10.md
│   ├── company-policy.md
│   └── exception-list.md
├── scripts/
│   ├── dependency-check.sh
│   └── secret-scan.sh
└── templates/
    └── audit-report.md

SKILL.md:

Copy---
name: security-audit
description: Conduct security audit and generate report based on OWASP Top 10 and company policy
---

## Audit Procedure

### 1. Automated Checks

First run these scripts:
- `scripts/dependency-check.sh` - Dependency vulnerability check
- `scripts/secret-scan.sh` - Secret leak check

### 2. Manual Review

Review code based on:
- `references/owasp-top-10.md` - OWASP Top 10 perspective
- `references/company-policy.md` - Company security policy

See `references/exception-list.md` for exceptions.

### 3. Report Generation

Generate audit report in `templates/audit-report.md` format.

Best Practices

File Size Guidelines

When to Split

Consider splitting when:

• SKILL.md exceeds 500 lines
• Specific reference info updates frequently
• Multiple skills need same information

Consider Compatibility

To use across tools, minimize scripts/ dependency:

Copy## Note

This skill uses `scripts/lint-check.sh`, but
in environments where scripts can't run, manually execute `npm run lint`.

Summary

Leverage Agent Skills extended structure for advanced workflows:

• references/: Split detailed docs to keep SKILL.md light
• scripts/: Automate with scripts
• templates/: Standardize output format

Start small and extend as needed.

Related Articles

• How to Create Your Own Skills - Basic skill creation
• How to Share Skills with Your Team - Use advanced skills with teams
• Skill Security Best Practices - Use scripts/ safely
• 7 Tips for Better Productivity - Skill usage tips