PTENES
MODULE 3.3

📂 Helper scripts and references

Complete structure of a professional skill: a scripts/ folder with bash helpers, reference.md files, .env.example for keys, progressive disclosure, and inviolable hard rules.

6
Topics
45
Minutes
Intermediate
Level
Practical
Type
1

⚙ scripts/ folder: shell automation

The subfolder scripts/ contains the executables the agent invokes via Bash. Each script is atomic: one responsibility, one clear output.

SKILL.md orchestrator scripts/check.sh scripts/analyze.sh scripts/generate.sh reference.md prompting/model-routing .env.example SKILL.md stays short — scripts and refs loaded on demand
Example: atomic script check-deps.sh
#!/bin/bash
# check-deps.sh — verifica dependĂȘncias antes de executar
# Uso: bash scripts/check-deps.sh

set -e

echo "Verificando dependĂȘncias..."

# Verifica ffmpeg
if ! command -v ffmpeg &>/dev/null; then
  echo "❌ ffmpeg não encontrado. Instale: brew install ffmpeg"
  exit 1
fi

# Verifica .env
if [ ! -f .env ]; then
  echo "❌ .env não encontrado. Copie .env.example e preencha."
  exit 1
fi

echo "✅ Tudo pronto!"

✓ Well-written scripts

  • ✓One responsibility per file
  • ✓Verb-noun name (check-deps, analyze-video)
  • ✓Shebang on the first line
  • ✓Clear output with ✅/❌
  • ✓set -e for fast failure

✗ Problematic scripts

  • ✗Monolithic 500-line script
  • ✗Inline code in SKILL.md
  • ✗API key hardcoded in the script
  • ✗No error handling
  • ✗Generic name (script.sh, run.sh)
Atomic
1 script = 1 task
Verb-noun
descriptive name
chmod +x
executable
Prefix
arcads_*, n8n_*
2

📚 reference.md files

References are the skill’s "detailed manuals" — they contain everything that would be too extensive for the main SKILL.md. The agent consults them on demand when it needs in-depth information.

What goes in references/

📄 reference.md
  • ‱ Complete API specifications
  • ‱ Parameter tables
  • ‱ JSON response examples
  • ‱ Error codes and handling
📁 prompting/
  • ‱ Copywriting formulas
  • ‱ Content analysis rules
  • ‱ Routing logic
  • ‱ Prompt templates
📋 MASTER_COMPLETO.md
  • ‱ Complete HTML templates
  • ‱ Color and typography system
  • ‱ Reusable components
  • ‱ Review checklists
How SKILL.md references external files
## ReferĂȘncias

Sempre leia estes arquivos antes de criar ou editar qualquer pĂĄgina:

1. **`references/MASTER_COMPLETO.md`**
   Templates HTML completos, CSS e JavaScript obrigatĂłrios.
   ContĂ©m tudo que vocĂȘ precisa para construir qualquer pĂĄgina.

2. **`references/CHECKLIST_REVISAO.md`**
   Checklist para verificar a pĂĄgina antes de entregar.

3. **`references/SVG-FUTURISTA.md`**
   Leia SEMPRE que for criar um mĂłdulo de conteĂșdo.

# O SKILL.md menciona, mas nĂŁo duplica. Detalhes ficam nas refs.

💡 Golden rule: mention, don’t duplicate

The SKILL.md should only point for references—never copy their contents. Duplication creates inconsistencies: when you update a reference, the SKILL.md becomes outdated without you realizing it.

On demand
read when needed
No limit
can be extensive
Mentioned
link in the SKILL.md
Not duplicated
single source of truth
3

🔑 .env.example: Keep Secrets Out of Code

The file .env.example is the industry standard for documenting environment variables without exposing real values.

Example: .env.example for a skill with an external API
# .env.example — copie para .env e preencha com valores reais
# NUNCA faça commit do arquivo .env

# Arcads API
ARCADS_API_KEY=sua_chave_arcads_aqui
ARCADS_BASE_URL=https://api.arcads.ai/v1

# ConfiguraçÔes opcionais
ARCADS_DEFAULT_MODEL=seedance-2.0
ARCADS_TIMEOUT_SECONDS=300

# DiretĂłrios de trabalho
WORK_DIR=./tmp/arcads
OUTPUT_DIR=./output

⚠ Hard security rule

An API key exposed in a public commit can cause losses in minutes. Follow these rules without exception:

  • ⚠NEVER commit the file .env real
  • ⚠NEVER log environment variables in output or debug
  • ⚠ALWAYS add .env to .gitignore
  • ⚠ALWAYS use $VARIAVEL in the scripts, never as a literal value

Setup cycle for new users

1

Clone / install the skill

The .env.example is already in the folder. The user can see what needs to be configured.

2

cp .env.example .env

Copy the template. The real .env never goes into the repository.

3

Fills in the actual values

Edit the .env with the real API key. The check.sh script checks that it’s filled in before using the skill.

.env.example
in the repository
.env
in .gitignore
$VARIAVEL
in the scripts
check.sh
checks first
4

đŸ”œ Progressive Disclosure

Progressive disclosure is the principle of showing the essentials first and revealing details on demand. Applied to skills: a short SKILL.md + detailed references + specialized scripts.

The 3 levels of detail

📄
Level 1 — SKILL.md
Main workflow, critical rules, pointers to refs. ALWAYS read. 50-150 lines.
ALWAYS
📚
Level 2 — references/
Detailed specs, tables, history. Read when the agent needs in-depth information.
ON DEMAND
⚙
Level 3 — scripts/
Concrete implementation. Run when the agent needs to perform an action.
WHEN RUNNING

💡 Why progressive disclosure saves tokens

A 500-line SKILL.md costs 5-10x more in tokens than a 100-line one — and is read on EVERY activation. References with 500 lines only cost tokens when the agent needs them. Progressive disclosure makes the skill scalable.

Level 1
Short SKILL.md
Level 2
extensive references
Level 3
executable scripts
Savings
tokens on demand
5

🚧 Hard Rules: Rules That Never Break

Hard rules are absolute restrictions — the skill's immune system. They differ from guidelines (suggestions) because they are non-negotiable. Written in UPPERCASE to make confusion impossible.

Hard Rules section in SKILL.md
## Hard Rules

# Estas regras são invioláveis — não há exceção.

- **NUNCA** parafrasear o transcript do vĂ­deo original.
  Usar verbatim (texto exato) para preservar timing e autenticidade.

- **SEMPRE** rodar o dialogue gate antes de gerar.
  Confirmar todos os inputs com o usuårio para evitar gasto de créditos.

- **NUNCA** logar a API key em qualquer output ou arquivo de log.
  Usar $ARCADS_API_KEY; nunca imprimir ou expor o valor real.

- **SEMPRE** verificar .env antes de executar qualquer script.
  Rodar scripts/check.sh como primeiro passo de toda geração.

✓ Effective hard rules

  • ✓3–7 rules (more becomes noise)
  • ✓Each with a short justification
  • ✓Verb in uppercase (NEVER, ALWAYS)
  • ✓Testable with an adversarial case
  • ✓Protection against the costliest errors

✗ Problematic hard rules

  • ✗20+ rules — nobody remembers them all
  • ✗No justification — the reason is unknown
  • ✗Rules for very rare situations
  • ✗Mixing hard rules with guidelines
  • ✗No dedicated section — lost in the body
NEVER/ALWAYS
in uppercase
3–7 rules
ideal amount
Rationale
why it is inviolable
Dedicated section
## Hard Rules
6

🔒 Confirmation Gates

One gate is a checkpoint where the agent stops and asks for confirmation before taking a costly, irreversible, or high-impact action. The cost of confirming is zero; the cost of not confirming can be enormous.

Example: dialogue gate before generating a video (Arcads)
## Fluxo de Geração

1. Coletar inputs (imagem/ĂĄudio/vĂ­deo/ator)
2. Detectar modelo recomendado (ver prompting/model-routing.md)

### DIALOGUE GATE — executar antes de qualquer chamada à API

Apresentar ao usuĂĄrio:
```
📋 Resumo da geração:
  Modelo: Seedance 2.0 (lip sync)
  Ator: [nome]
  Script: "[primeiros 50 chars...]"
  Custo estimado: ~8 créditos Arcads
  Duração: ~15 segundos

Confirma? (S/N)
```

NUNCA prosseguir sem confirmação explícita "S" ou "sim".
3. Executar scripts/arcads_generate.sh apenas após confirmação.

📊 When to use a gate

💰 Actual cost
API calls billed by usage (video, image, tokens)
♻ Irreversible
delete files, publish to production, send emails
⚡ High impact
change the database, modify system settings

💡 Quality gate, not bureaucracy

Gates should be informative, not annoying. A good gate shows the estimated cost, summarizes what will be done, and offers a clear way out. A gate that says "do you confirm? (y/n)" without context is as bad as having no gate—the user will confirm without understanding what they’re confirming.

Cost
show estimate
Summary
what will be done
Clear output
cancel option
Blocking
without "S," it doesn’t advance

📂 Module Summary

✓
scripts/ — atomic files, verb-noun naming, chmod +x, no hardcoded credentials
✓
references/ — extensive docs read on demand; SKILL.md points to them and never duplicates them
✓
.env.example — template without real values; real .env in .gitignore; scripts use $VARIAVEL
✓
Progressive disclosure — 3 levels: SKILL.md (always) → references (on demand) → scripts (when running)
✓
Hard rules — 3-7 rules in UPPERCASE in the ## Hard Rules section; each with a justification
✓
Confirmation gates — before costly or irreversible actions; informational (cost + summary + output)

Next Module:

3.4 — Case study: ads-skill (Arcads) — dissect a real production skill that applies everything you’ve learned

← Module 3.2 Next: ads-skill Case Study →