DEV Community: Dailos Rafael Díaz Lara

AI - Foundations and best practices creating skills

Dailos Rafael Díaz Lara — Sun, 13 Sep 2026 13:39:18 +0000

Let's talk about skills for AI agents, and we're doing it off the back of attending an online workshop given by @mouredev on skills a few days ago.

🎥 Full video on YouTube

The workshop was really interesting, so much so that I was left wanting more, so I went digging a bit deeper, not so much into what skills do or what they're for, but into the best practices for defining them.

The result is this post, where I try to organize the main ideas I've been gathering and putting in order. I hope they're as useful to you as they've been to me.

Without further ado... let's get started.

🤓 Introduction

Skills are used to automate repetitive processes whose procedure can be described with a high degree of precision.

The information inside a skill has to be perfectly structured and fine-tuned so that the model has the least possible chance of making up results.

The content of a skill can include:

Prompt
Rules
Tools
MCPs
Other skills
etc.

When we start up an agent, it already knows which skills are available; however, skills can be invoked manually by the developer (explicit invocation), or automatically by the agent itself (implicit invocation), once we've made it aware that they exist.

Every skill we use gets loaded into the context of the current session, so it's important to control excessive use when they're not needed.

💻 Creating Skills

📍 Skill location

We'll create skills inside the ./.agents/skills directory (if they're only for the current project), or in ~/.agents/skills (if they're global for every agent running on the machine).

🔎 NOTE
This is the standard across the vast majority of agents, but just in case, it's always worth checking how a specific agent handles skills.
For example, in Claude Code CLI, if we manually create a skill in our repo, it won't be detected even after restarting the agent. Why? Because for this agent they need to be created in ./.claude/skills. It's not a problem with the skill or its definition, but with where Claude Code looks for it.

Each skill must be created inside a directory specific to that skill. Therefore, it's essential that the skill's directory name matches the name we give the skill itself, since that's the name by which the agent will invoke it.

On top of that, a SKILL.md file — containing the skill's definition — must always exist inside that directory.

🎩 Skill header

Every skill must have a header that describes it. This header is identified by the opening and closing --- characters typical of YAML.

⚠️ IMPORTANT
Even though the skill is defined using Markdown, the content of the skill's header must be written in YAML.

The content of that header must include the following fields:

name (🔥 required)

Must be between 1 and 64 alphanumeric characters, lowercase, in kebab-case format.

It cannot start or end with a hyphen, and it can never contain two or more consecutive hyphens (--).

Finally, it must match the name of the directory where the skill is defined, since that's what's used to invoke the skill (/skill-name).

The regex for this name is: ^[a-z0-9]+(-[a-z0-9]+)*$.

description (🔥 required)

Must be between 1 and 1024 characters.

It has to be specific enough for the agent to be able to read its content and determine whether it matches what the user is looking for.

To do that, the description should contain specific phrases, verbs, or concrete use cases, for example: Use when the user asks to review code or optimize database queries.

license (optional)

Used to define the legal usage context of the skill or its usage permissions.

When setting its value, it's considered good practice to follow the SPDX (Short-form License Identifiers) standard.

The most common values tend to be: MIT, Apache-2.0, GLP-3.0, and Proprietary or Commercial.

version (optional)

Contains the string that defines the semantic versioning of the skill, for example: 1.0.0.

It's usually used to configure pipelines, deployment updates, or tracking within certain ecosystems.

context (optional) inline | fork

Lets us define how the skill runs in relation to the agent's main conversation thread.

This aspect matters at the level of memory orchestration configuration and environment isolation when the skill is invoked.

By default, if this field isn't defined, the skill runs in line with the ongoing conversation; however, there are values we can assign to this field to change that behavior:

inline (default value)

The skill runs directly within the current conversation window.

The instructions, examples, and tools defined inside SKILL.md are added directly to the current context, and the model retains them in full for use in later parts of the conversation.

This setting is recommended when, upon starting multiple tasks that need to work together, the skill needs to know the entire history, tone, and specific references the user has made in order to operate correctly.

With all that said, if we choose this option, we need to set guardrails at the description level so the skill knows exactly when it should step back to gather information and then return to where it left off.
fork (sub-agent or isolated sandbox mode)

In this mode, you could think of it as creating a metaphorical "child process," where the agent temporarily pauses the main conversation thread, copies the relevant information from the current state, and spins up an isolated sub-agent to process exclusively the task assigned by the skill.

At the memory level, the sub-agent created doesn't read the entire memory or history of the main conversation; instead, it prevents the model from getting distracted from that conversation by avoiding drift caused by mixing in other queries.

At the token consumption level, since it doesn't take the full main conversation history but rather a small, very specific section, we can reduce the volume of input tokens and get a cheaper, faster execution.

Once the skill has completed its task, it gathers, cleans up, and distills a summary of the result and injects it into the main conversation thread before closing the "child process" in which it was operating.

With all that said, if we choose this option, we need to be aware that the instructions must be fully self-contained, since the skill won't have access to the complete conversation history.

Comparison table

Feature / Behavior	`context: inline` (Default)	`context: fork`
Work area	Main conversation window	Isolated sub-agent
History visibility	Full history preserved	Hidden (or heavily restricted)
Token consumption	High (grows with conversation length)	Low (optimized for skill-specific data)
Output obtained	Continuous as the conversation goes on	A simple, structured summary
Main use case	Interactive assistant (e.g., copywriting)	Heavy background work (e.g., code review)

compatibility (optional)

This field acts as an environment check, making sure the machine where the skill or execution engine is running has the hardware capabilities, software packages, or required LLM engine requirements needed to run the instructions defined inside the skill. For example, we can define the model's minimum reasoning requirements, as well as operating system constraints, CLI packages, or required binaries.

If the system scans the skill and detects a compatibility issue, the skill is disabled or hidden to prevent runtime errors.

For example:

  compatibility:
    model: ">=gpt-4o"
    os: "linux, darwin"
    dependencies:
      - "python>=3.10"
      - "ffmpeg"

allowed-tools (optional) (also known as allow-tools)

This field is defined by a list of values that strictly establish or limit which tools the agent is allowed to use when the skill runs.

When defining the content of this property, you should keep the Principle of Least Privilege in mind, so that if a skill needs to read local documentation, it shouldn't be allowed to execute terminal commands.

When a skill that has this property defined is executed, the agent automatically suspends/disables any tool not specified in the list, so that even if the model hallucinated and tried to invoke one of the disallowed tools, the model's orchestrator would block it.

One of the main advantages of this field is that it prevents excessive consumption caused by the unnecessary use of expensive tools or the execution of dangerous operations (files, databases, infrastructure, etc.) that aren't clearly authorized.

For example:

  allowed-tools:
    - internet_browse
    - read_local_file
    - parse_json

disable-model-invocation (optional) true | false

This field is used to configure the level of "awareness" the model has about whether the skill in question exists or not.

When this field isn't defined, or is left at its default value (false), when the agent starts up it will have the skill in its list of available skills, and if the user says Check my server logs, the model will analyze the skill's description and, if it matches the goal of the request, it will start running the skill.

If this option is set to true, the model will completely ignore this skill, no matter how the agent is being used. The only way to use it is through explicit invocation of that skill, i.e., /skill-name.

This setting is particularly useful for destructive workflows, ones that apply irreversible changes, or ones that carry high risk for the system, where a misinterpretation by the model could lead to accidental loss of valuable data or unauthorized system changes.

For example:

  name: wipe-database-cache
  disable-model-invocation: true

metadata (optional)

This field is an unstructured dictionary designed for development-specific tasks, where we can add additional information related to the skill.

It acts as a communication bridge between different platforms, code editors, and frameworks that need a way to define additional information relevant to each one, without breaking the open standard for skill definitions.

One of the main uses given to this field is to display the skill's information in a human-friendly format in applications or tools that manage skills.

On the other hand, when skills aren't public, this field can be used for tracking their development at a corporate level.

For example:

  metadata:
    author: "Platform Security Team"
    category: "DevOps / SRE"
    icon: "shield-alert"
    cost_center: "fintech-ops-99"

Some complete examples of skill headers could be the following:

# This example uses 'context: fork' so it runs in a secure thread, with low token consumption, to perform
# heavy backend-level validation. Also, since it runs autonomously, it can be invoked automatically by the
# model and can include the CLI tools needed to carry out its task.
---
name: kubernetes-manifest-validator
description: Use this skill when the user provides Kubernetes YAML files, Helm charts, or K8s deployment manifests and requests syntax validation, security linting, or API deprecation checks.
license: Apache-2.0
version: 2.4.1
context: fork
compatibility:
  model: ">=gpt-4o"
  os: "linux"
  dependencies:
    - "kubeconform>=0.6.0"
    - "trivy>=0.45.0"
allowed-tools:
  - read_local_file
  - execute_terminal_command
  - write_local_file
disable-model-invocation: false
metadata:
  team: "SRE-Core"
  environment: "staging-validation"
  severity-tier: "medium"
---

---
# This example uses 'context: inline' so it runs within the agent's context window, since it needs access
# to the full conversation history. The tool restriction lets the model run the skill during the conversation.
name: market-competitor-analyzer
description: Use this skill when the user asks for competitive intelligence, financial market trends, stock ticker comparisons, or landscape analysis regarding corporate competitors.
license: MIT
version: 1.0.3
context: inline
compatibility:
  model: ">=gpt-4-mini"
  os: "any"
  dependencies:
    - "python-yfinance>=0.2.0"
allowed-tools:
  - web_search
  - fetch_url_content
  - render_data_chart
disable-model-invocation: false
metadata:
  department: "Product-Strategy"
  billing-code: "mkt-res-2026"
  ux-icon: "trending-up"
---

# This skill involves the irreversible deletion of data, so it includes the 'disable-model-invocation: true'
# setting, making it only invokable by a human. Additionally, the 'compatibility' field restricts it to the
# specific database it can operate on.
---
name: production-database-purger
description: Mandatorily hidden from automatic routing. This skill safely drops stale tables, truncates high-volume log schemas, and runs database vacuuming routines on production clusters during maintenance windows.
license: Proprietary
version: 4.0.0-rc1
context: fork
compatibility:
  model: ">=o1-preview"
  os: "linux, darwin"
  dependencies:
    - "postgresql-client-16"
    - "aws-cli-v2"
allowed-tools:
  - execute_sql_query
  - fetch_vault_secret
disable-model-invocation: true
metadata:
  compliance-required: "SOC2-Type-II"
  requires-human-approval: true
  criticality: "high"
  slack-alert-channel: "#prod-ops-logs"
---

At this point, it's worth noting that even though these fields may belong to a standard, not every agent understands them or uses the same naming to achieve the same goal. The following table shows which agent accepts which header field:

Header fields for SKILL.md supported by agent

Header Field	Claude Code CLI	Claude.ai (Web)	Claude API	AutoGen Studio	CrewAI Core	LangGraph Engine	OpenCode CLI	Aider CLI	CodeRabbit CLI
`name`	✅	✅	✅	✅	✅	✅	✅	✅	✅
`description`	✅	✅	✅	✅	✅	✅	✅	✅	✅
`version`	✅	❌	✅	❌	✅	✅	✅	❌	✅
`license`	✅	❌	✅	❌	❌	❌	❌	❌	✅
`context`	✅	❌	✅	❌	❌	❌	✅ (mode)	❌	✅
`allowed-tools`	✅	❌	✅	✅	✅	✅	✅ (perms)	✅	✅
`disable-model-invocation`	✅	❌	✅	❌	❌	❌	✅ (disable)	❌	✅
`compatibility`	✅	❌	✅	❌	❌	❌	✅ (deps)	❌	❌
`metadata`	✅	✅	✅	✅	✅	✅	✅	✅	✅

🛢 Body of a skill (the `T-I-P-O` pattern)

Once we've finished defining the skill's header, it's time for the body.

⚠️ IMPORTANT
Unlike the header section, the body of a skill is written using Markdown.

What we define here is a compendium of semantic directives, structured in a certain way, that the model is able to internalize as operational instructions.

This block is decisive for whether the agent behaves as deterministically as possible, or starts having critical hallucinations during execution.

Despite the importance of this block, since it's open source, there's no single, strict structure that universally forces us to define a skill's body in a particular way. That said, in enterprise environments there's a growing convergence toward using the pattern known as T-I-P-O (Targets, Inputs, Procedure, and Outputs), which is the de facto minimum accepted to guarantee a baseline of determinism in the model.

# Target (or # Objective)

Defines what this skill's execution is aiming for and what the expected final goal is.

When an agent gets lost in a loop of tool calls, it re-evaluates its progress by comparing it against what's defined in this section.

Example:

  # Target

  The absolute objective of this skill is to locate deprecated API endpoints inside the repository, upgrade them to the current SDK version, and ensure the test suite passes with zero errors.

# Inputs (or # Prerequisites)

Defines the exact variables, files, or data formats the agent must receive before starting work.

This section matters because it stops the agent from "guessing" or making up data; that way, if the current context doesn't contain these elements, the agent knows it should stop and ask for them.

For example:

  # Inputs

  This skill requires two primary artifacts from the active workspace context:

  1. `legacy_endpoints.json` - A manifest listing the raw endpoints.
  2. `current_sdk_spec.yaml` - The up-to-date OpenAPI schema reference.

# Procedure (or # Execution Steps)

Defines a numbered, sequential list that the agent must follow strictly, step by step.

With this, we manage to break the model's reasoning down into manageable subtasks (Chain-of-Thought) while forcing the agent to follow numbered steps, reducing possible hallucinations in workflows that use multiple tools.

For example:

  # Procedure

  1. Parse the `legacy_endpoints.json` file using the `read_file` tool.
  2. For each endpoint listed, locate its definition in the codebase using `grep_search`.
  3. Replace the deprecated syntax with the new methods specified in `current_sdk_spec.yaml`.
  4. Run the local testing pipeline using `execute_terminal_command(command="npm test")`.

# Outputs (or # Expected Output Format)

Defines the output contract upon completion of the skill's execution.

Here we indicate whether we want a JSON, a Markdown document, a Markdown code block, etc., as well as the exact structure of the final response.

This way, the agent's outputs will be easily readable by other automated scripts or by the user, without containing filler text.

For example:

  # Outputs

  Return exclusively a valid JSON block containing the compilation summary. Do not include conversational preambles.

Full example of a defined skill:

---
name: api-migration-tool
description: Use when the user requests an automated upgrade of legacy API endpoints.
version: 1.0.0
context: fork
allowed-tools:
  - read_file
  - write_file
  - grep_search
  - execute_terminal_command
disable-model-invocation: false
---

# Target

Migrate deprecated microservice API routing schemas to the v2 standard.

# Inputs

- Workspace variable: `target_directory`
- Source config file: `api_routing.conf`

# Procedure

1. Scan the `target_directory` for any `.conf` files.
2. Cross-reference keys against the official version 2 documentation wrapper.
3. Apply the structural rewrites into a new temporary branch.
4. Validate the syntax integrity.

# Outputs

Provide a markdown table summarizing:

- The file paths modified.
- The original lines of code.
- The rewritten replacement chunks.

🔎 NOTE
As a final note regarding the body of a skill, when we're in a section where we implement an unordered list, we sometimes find that both the hyphen (-) and the asterisk (*) are used to mark a list item.
While it's true that, computationally, it makes no difference to the model, cleanliness and order matter here from a DevEx standpoint, so the use of the hyphen (-) is encouraged for unordered list items over any other character.

These are the basic sections a skill should have. Beyond these, if our application's needs require defining additional sections, we're free to do so as long as it helps fine-tune the skill's use even further.

Some additional sections beyond those proposed by the T-I-P-O pattern are the following:

# Guardrails & Safety Constraints

Defines critical restrictions by listing absolute limits, forbidden behaviors, and areas the agent must never touch.

This is the main line of defense against data destruction or security breaches.

For example:

  # Guardrails & Safety Constraints

  - **NEVER** pass raw string variables directly into bash command lines without character escaping.
  - Do not modify or read any files inside the hidden `.git/` or `.vault/` internal directories.

# User Verification Gates

Establishes human approval checkpoints, explicitly defining which specific actions must mandatorily halt the agent's autonomous flow to require visual "Ok" or manual confirmation from the user in the chat.

For example:

  # User Verification Gates

  - **Trigger:** Prior to executing any database truncation or dropping an index.
  - **Action:** Halt the script, render the specific SQL payload to the user, and ask: "Do you confirm the execution of this database migration? (y/n)".

# Escalation Protocols

This section prevents the agent from getting stuck trying to solve problems that exceed its permission capabilities, instructing it on when to give up and hand the case off to a human user.

For example:

  # Escalation Protocols

  - If a connection timeout error occurs more than 3 consecutive times on port 5432, halt automation.
  - Do not attempt to guess credentials. Output: `[CRITICAL] Network isolation detected. Escalating ticket to SRE team.`

# State Tracking & Memory Logging

With this section we force the model to structure its thought process and internalize state changes in local variables before calling the next tool, solving memory loss in very long workflows.

For example:

  # State Tracking & Memory Logging

  - Before modifying a file, open a `<state>` block to log the original file hash and line count.
  - Maintain a rolling list of modified assets in your tool call parameters to avoid circular file edits.

# Chain-of-Thought Auditing

Here, what we do is force the agent to justify each action using specific XML tags (like <thought>) before invoking terminal commands, which makes debugging and auditing the agent's behavior far easier.

For example:

  # Chain-of-Thought Auditing

  - Every tool call must be preceded by a `<reasoning>` block containing:
    1. Why this tool is necessary now.
    2. The expected outcome of the invocation.

# Performance & Cost Optimization

Here we can prevent the agent from uncontrollably consuming the API budget (or exhausting the context window), by regulating the amount of text it can read or write in a single iteration.

For example:

  # Performance & Cost Optimization

  - When parsing log files, use range parameters to inspect a maximum of 150 lines per tool call.
  - Avoid re-reading large context files if the content was already logged in the active scratchpad.

# Compliance & Regulatory Standards

This section matters when we're working with certain data, since it ensures that the deliverables generated by the agent (such as source code or data reports) comply with strict legal or organizational regulations for the sector (SOC2, GDPR, ISO), or from the company itself.

For example:

  # Compliance & Regulatory Standards

  - All telemetry methods designed by this skill must completely sanitize PII (Personally Identifiable Information).
  - Ensure encryption-in-transit configurations use TLS 1.3 as a baseline.

# Workspace Clean-up & Idempotency

With this property we can guarantee the hygiene of the local system, ensuring the agent deletes its temporary execution files and that, if the skill runs twice in a row, the result is identical without duplicating data.

For example:

  # Workspace Clean-up & Idempotency

  - Upon task completion or premature failure, execute an explicit cleanup step to delete `/tmp/cache_*.json`.
  - Design every code refactor to be completely idempotent; running the skill twice must yield zero changes on the second run.

# Corporate Style & Terminology Glossaries

Here we can unify business terms and the agent's voice when it generates technical documentation, reports, or text responses aimed at end clients or company leadership.

For example:

  # Corporate Style & Terminology Glossaries

  - Use the term "Client Workspace" instead of "Tenant Folder" across all markdown outputs.
  - Keep tone formal and highly concise; eliminate words like "obviously", "simply", or conversational expressions.

# Diagnostic & Telemetry Footprints

This property injects digital signatures and standardized logs into Git commits or the headers of files created by the agent, to uniquely identify which changes were made by the AI and which version of the skill was used.

For example:

  # Diagnostic & Telemetry Footprints

  - Append this precise signature at the end of every modified file header:
    `/* Automated optimization applied via agent-skill: db-optimizer (v2.4.1) */`

🗃 More complex skills

As we develop a skill, it can become increasingly complex, which makes our SKILL.md file practically unworkable due to the amount of information, instructions, examples, or similar content it can contain. The most likely result is:

😰 loading all this content into an agent,
🤯 early context saturation,
🔥 increasing unnecessary token consumption, and
💀 degrading the model's response.

The solution to this lies in a process called Skill Atomization, through which heavy logic, external resources, and referential examples are extracted from the skill, turning it into a declarative orchestrator, keeping the file's content under 50 or 100 lines of text. This makes the skill's initialization speed within the agent very high and increases the system's scalability through independent reference updates.

This atomization process is carried out through two actions: Rigorous structuring and Technical linking.

Rigorous structuring

Inside the directory where we've defined the SKILL.md file, we start creating directories with semantically sensible names.

Inside each of those directories, we create the corresponding files that will hold the information we want to extract from the original skill.

The directory structure depends solely on the development team, but there is indeed a certain tendency to have certain established directories, which don't need to be implemented if our skill doesn't require them, but if we do, it's recommended to keep the same naming.

An example of rigorous structuring could be this:

  my-complex-agent-skill/
    ├── SKILL.md                 # (Required   ) Main file (Orchestrator and Frontmatter)
    ├── scripts/                 # (Optional   ) Executable code that offloads heavy logic from the LLM
    │   └── optimize_matrix.py   #               Numerical computation/complex analysis script
    ├── assets/                  # (Optional   ) Static data and validation schemas
    │   └── database_schema.json #               Reference database structure
    ├── references/              # (Optional   ) Style guides, manuals, or dense documentation
    │   └── code_style_guide.md  #               Formatting rules the LLM only reads if needed
    └── examples/                # (Optional   ) Few-Shot Example library (user stories)
        ├── standard_case.md
        └── edge_case_timeout.md

Technical linking

Now that we've extracted the excess information from our skill into independent sections of our directory structure, we need to link that content back inside the file that's left.

For this we'll use explicit relative paths to the content we want to reference. Agents are able to read these paths and, through the use of internal tools, can access the files on demand, only when the procedure section requires it.

With this:

✅ we avoid loading all this content into an agent up front,
✅ we avoid early context saturation,
✅ we reduce unnecessary token consumption, and
✅ we avoid early degradation of the model's response.

To do this, there are two commonly used patterns: Direct relative link and Footnote reference link.

Direct relative link

Used for immediate dependencies the agent must always inspect before running a procedure.

For example:

# Inputs

This skill requires the project context infrastructure to match the configuration rules specified in the core [Database Architectural Reference Schema](./assets/database_schema.json).

Footnote reference link

Used for dependencies that are worth having linked but whose loading happens only in very specific situations, meaning the agent won't load these references into context unless absolutely necessary.

Beyond that, they're also often used in very long procedures, pushing references to the end of the file and keeping the main text free of clutter.

For example:

# Procedure

1. Pull the latest Docker manifest using the environment variables.
2. Build the staging container and verify the cluster health check endpoints.
3. In case the build triggers a pipeline schema violation, fetch the resolution steps immediately.

# Error Handling & Edge Cases

* If the server returns a 503 error, verify if your service mesh matches the internal corporate architecture layout.

---

# Resource Footnotes / Lazy-Load References: ./assets/health_check_spec.json: ./references/pipeline_troubleshooting_guide.md: ./references/corporate_network_mesh_v2.md

Now then, how can we start externalizing a skill? Well, we can start by laying out the following steps:

1. Move scripts out of the prompt context (/scripts)

Since explaining to an agent in natural language the operations a script must carry out is complex and consumes tokens unnecessarily, we can create a scripting file in a language of our choice that performs that operation.

In the skill's header, within the allowed-tools section, we'll grant execution permission for the execute_terminal_command command and invoke our script from the skill's text.

For example:

  ---
  name: my-custom-skill
  description: ...
  allowed-tools:
    - execute_terminal_command
  ---

  # Procedure

  1. Do not compute matrix variances manually. Instead, trigger the native optimization script:
    `execute_terminal_command(command="python3 ./scripts/optimize_matrix.py --path=.")`

2. Externalize the example library (/examples)

We need to be very careful with how we use the linked files in this section, since, generally speaking, because they contain extensive, concrete examples, they can take up a lot of space, raising both input and output token consumption if we misuse the examples.

Ideally, each example should be its own independent file, so that linking to it allows loading one or another depending on the agent's needs.

For example:

  # Expected Workflows

  Before formatting your final response, read and analyze the corresponding execution logs inside the example library based on the current workload:
  - For standard microservice queries, read [Standard Flow Case](./examples/standard_case.md).
  - For database connection timeouts, read [Timeout Recovery Case](./examples/edge_case_timeout.md).

3. Load documentation on demand (/references)

API documentation, procedures, etc., can saturate an agent's context very quickly, and on top of that, keeping it updated would also require modifying the skill's content.

If we extract that documentation into independent, isolated files, we can selectively load them only when needed.

For example:

  # Error Handling & Edge Cases

  If a compilation error occurs due to typing differences, do not attempt to guess the syntax. Read the internal reference document [Type Definition Manual](./references/code_style_guide.md) before attempting a second patch rewrite.

🧐 Good (✅) and bad (❌) practices to follow when defining a skill

At the header level

✅ Sync the name and the folder: Keep the name field written in kebab-case (lowercase with hyphens) and make sure it exactly matches the name of the containing folder to avoid indexing failures.
✅ Keep semantic descriptions tight: Write the description field using action verbs and specific trigger keywords (e.g., "Use when the user requests an API optimization"). This optimizes routing and prevents accidental activations.
✅ Apply the Principle of Least Privilege: Declare exclusively, in allowed-tools, the tools the skill strictly needs to achieve its goal, blocking access to dangerous system commands if they aren't required.
✅ Force human approval for critical tasks: Set disable-model-invocation: true on destructive or production skills (like deployments or database purges) to force the skill to only be activated via a slash command (/) typed by a person.
✅ Specify environment dependencies: Use the compatibility field to list minimum versions of system binaries (e.g., python>=3.10, docker), so the framework halts execution before generating a terminal error.
✅ Leverage metadata for governance: Use the metadata block systematically in corporate environments to record the owning team, cost center, and compliance identifiers (e.g., compliance: SOC2).
❌ Duplicate skill names: Using the same name field in different SKILL.md files within the repository, which causes collisions and makes the orchestrator ignore components at random.
❌ Create generic or ambiguous descriptions: Writing descriptions like description: "An AI assistant to help you write code". This causes the LLM to activate the skill constantly for common tasks, saturating the context window.
❌ Grant universal permissions out of laziness: Declaring wildcards for tools or including terminal execution tools (execute_terminal_command) in skills that only need to read data.
❌ Ignore version control: Leaving the version field static at 1.0.0 indefinitely, preventing CI/CD pipelines from verifying whether production agents are running the most recently validated behavior.
❌ Confuse the role of context: fork: Configuring a skill as context: inline when it needs to process thousands of lines of server logs, causing the main chat to fill up with noise and burn through the token budget.
❌ Omit the license field in shared skills: Leaving the license field empty in shared internal repositories, exposing development teams to intellectual property compliance issues.

At the body level

✅ Adopt the standard T-I-P-O structure: Always organize the body of the document using the # Target, # Inputs, # Procedure, and # Outputs blocks to guide the model through a deterministic flow.
✅ Write imperative, numbered procedures: Use numbered lists (1., 2., 3.) in the procedure section to force sequential, step-by-step reasoning (Chain-of-Thought).
✅ Standardize unordered bullets with hyphens: Use only hyphens (-) for lists of constraints, inputs, or tools. Reserve asterisks (*) exclusively for bold (**) or italics (*), making it easier for syntax parsers to read.
✅ Externalize dense manuals via footnotes: Apply lazy loading by moving paths to manuals or secondary guides to the bottom of the page ([Reference 1]: ./references/guide.md), keeping the main flow free of filler text.
✅ Define strict output contracts: In the # Outputs section, specify the exact response format (e.g., a valid JSON schema or a Markdown table), and explicitly forbid conversational preambles like "Sure, here is your summary".
✅ State negative constraints assertively: Dedicate an independent section to safety restrictions (# Guardrails & Safety Constraints) and write prohibitions in uppercase and imperative form (e.g., "NEVER run recursive deletes").
❌ Mix bullet styles within the same block: Randomly combining hyphens (-) and asterisks (*) within the same list, which can break context segmentation in certain parsing engines.
❌ Write instructions as free-form narrative prose: Writing the procedure as a long paragraph instead of a structured list. Models tend to skip secondary instructions when they're buried in dense blocks of text.
❌ Embed extensive source code within the instructions: Pasting complete Python or Bash scripts into the prompt body. This drastically degrades the model's attention and drives up execution costs.
❌ Assume the agent knows the current environment: Writing procedures without first defining the # Inputs section, causing the agent to try to guess file paths, variable names, or database environments.
❌ Use ambiguous or conditional language: Using phrases like "Please try to optimize the query if you think it is a good idea". Production agents require direct, deterministic instructions (e.g., "Analyze query latency using the EXPLAIN tool").
❌ Overload the skill with too many secondary goals: Trying to make a single SKILL.md file handle code analysis, cloud deployments, and database optimization simultaneously. If the scope grows, split it into independent skills.

At the level of robustness, error handling, and scalability

✅ Design clear escape routes for tool errors: Dedicate a section to # Error Handling detailing exactly what the agent should do if a tool returns an error, times out, or returns empty data.
✅ Delegate numeric and algorithmic processing to scripts: Instead of asking the model to analyze a matrix or a giant JSON via prompts, write a native script in /scripts and have the agent run it, processing only the output summary.
✅ Implement modular Few-Shot Examples: Store complex interaction examples in independent files inside an /examples directory and link to them on demand, avoiding saturating the agent's initial context.
✅ Verify the integrity of relative links via CI/CD: Implement an automated script in your integration pipeline that validates that all references to ./assets/, ./scripts/, or ./references/ inside your skills actually exist physically and aren't broken.
✅ Set halt conditions (Halt Conditions): Explicitly instruct the agent to stop execution immediately and request human supervisor intervention if it encounters critical permission issues (e.g., 403 Unauthorized) or persistent network failures.
✅ Keep the skill's core under 100 configuration tokens: Design the main SKILL.md as a lightweight, minimalist conductor that delegates to external resources, guaranteeing ultra-fast startups and optimal memory consumption.
✅ Define project-level skills according to that project's needs: When a skill is used in isolated projects, it's not advisable to extract it for global consumption, since any agent would load it regardless of whether it needs it for that particular repository or not. We should only create global skills, or promote a local skill to global, when we're 100% certain that skill will be used by every project.
❌ Allow infinite retry loops: Omitting contingency instructions for failures, which causes the agent to try running the same faulty tool over and over in an infinite cycle that burns through your API budget.
❌ Hide system error messages: Instructing the model to ignore terminal failures (e.g., 2> /dev/null). If the agent masks errors, diagnosing anomalous behavior in production environments becomes impossible.
❌ Hardcode credentials, absolute paths, or secrets: Writing passwords, API tokens, or absolute paths like /Users/username/project in the body of the skill. This breaks the agent's portability across different systems and creates a critical security vulnerability.
❌ Blindly trust long-term context memory: Designing a procedure that depends on the agent remembering a piece of data provided at the start of the general chat, especially when operating in context: inline configurations.
❌ Validate changes using the production environment itself: Allowing a code refactoring skill to apply direct modifications to the main branch (main) without forcing the prior execution of the local unit test suite on an isolated branch.
❌ Update external scripts without updating the skill's manual: Modifying the input parameters of an automation script in ./scripts/ but forgetting to update the corresponding tool-calling rules in the body of the SKILL.md file, causing the agent to invoke commands with outdated syntax.

👋 Final conclusions

It's clear that if there's one thing that hasn't changed with AI's arrival in the world of development, it's that best practices are more necessary now than ever, and a clear sign of that is the special care we need to take when defining our skills.

I hope this content has been useful to you. If you have any questions, feel free to reach out to me. Here are my profiles on X, LinkedIn, and Github.

🙏 Acknowledgments

Of course, to @mouredev for taking the time to prepare and share the workshop that was the origin of everything you've read, if you've made it this far.

IA - Fundamentos y buenas prácticas en la creación de Skills

Dailos Rafael Díaz Lara — Sun, 13 Sep 2026 13:28:00 +0000

Vamos a hablar de skills para agentes de IA y lo vamos a hacer a raíz de haber asistido hace unos días al taller online impartido por @mouredev sobre skills.

🎥 Vídeo completo en YouTube

El taller estuvo muy interesante, tanto que me quedé con ganas de más, así que me puse a investigar un poco, no tanto en lo que hacen y para qué sirven las skills, sino en las buenas prácticas a la hora de definirlas.

El resultado es este post donde trato de organizar las principales ideas que he ido reuniendo y ordenando. Espero que te sean tan útiles como lo ha sido para mi.

Sin más... empecemos.

🤓 Introducción

Las skills se emplean para automatizar los procesos repetitivos cuyo procedimiento puede ser descrito con un alto grado de definición.

La información dentro de una skill ha de estar perfectamente estructurada y afinada para que el modelo no pueda tener la más mínima posibilidad de inventarse resultados.

El contenido de una skill puede tener:

Prompt
Reglas
Herramientas
MCPs
Otras skills
etc.

Cuando arrancamos un agente, éste conoce las skills disponibles; ahora bien, las skills pueden ser invocadas manualmente por el desarrollador (invocación explícita), o de manera automática por parte del propio agente (invocación implícita), cuando le hemos informado de la disponibilidad de las mismas.

Cada skill que usemos, queda cargada en el contexto de la sesión en curso, por lo que es importante controlar su uso en exceso cuando no son necesarias.

💻 Creación de Skills

📍 Ubicación de las skills

Las skills las crearemos dentro del directorio ./.agents/skills (si son únicamente para el proyecto actual), o en ~/.agents/skills (si son globales para todos los agentes que se ejecuten en el equipo).

🔎 NOTA
Éste es el estándar entre la gran mayoría de los agentes pero por si acaso, siempre es interesante revisar cómo un agente en concreto trata las skills.
Por ejemplo, en Claude Code CLI, cuando creamos una skill manualmente en nuestro repo, aunque reiniciemos el agente, no la detectará. ¿Por qué? Pues porque para este agente hay que crearlas en ./.claude/skills. No es un problema con la skill o su definición, sino con dónde la busca Claude Code.

Cada skill deberá crearse dentro de un directorio específico para dicha skill. Por lo tanto, es imperativo que el nombre del directorio de la skill coincida con el nombre que le demos a la misma, ya que será el nombre por el cual dicha skill será invocada por el agente.

Además de esto, dentro de dicho directorio siempre debe existir el archivo SKILL.md, que contiene la definición de la skill en cuestión.

🎩 Encabezado de una skill

Toda skill ha de poseer un encabezado que la describirá. Este encabezado se identifica por el uso de los caracteres --- de apertura y cierre propios de Yaml.

⚠️ IMPORTANTE
A pesar de que la skill se define usando Markdown, el contenido de la cabecera de la skill ha de escribirse en Yaml.

El contenido de dicho encabezado ha de albergar los siguientes campos:

name (🔥 obligatorio)

Debe tener entre 1 y 64 caracteres alfanuméricos, en minúsculas y en formato kebab-case.

No puede empezar ni terminar con guión medio y en nigún caso puede contener dos o más guiones medios consecutivos (--)

Finalmente, ha de coincidir con el nombre del directorio donde se está definiendo la skill ya que será éste el que se emplee para invocar a la skill (/skill-name)

La RegEx de dicho nombre es la siguiente: ^[a-z0-9]+(-[a-z0-9]+)*$.

description (🔥 obligatorio)

Debe tener entre 1 y 1024 caracteres.

Ha de ser lo suficientemente específico como para que el agente sea capaz leer su contenido y determinar si es lo que el usuario está buscando.

Para ello, la descripción debe contener frases específicas, verbos o casos de uso concreto, por ejemplo: Use when the user asks to review code or optimize database queries.

license (opcional)

Se emplea para definir el contexto legal de uso de la skill o los permisos de uso de la misma.

A la hora de definir su valor, se considera buena práctica seguir el estándar de identificadores SPDX (Short-form License Identifiers).

Los valores más usuales suelen ser: MIT, Apache-2.0, GLP-3.0 y Proprietary o Commercial

version (opcional)

Contiene la cadena de caracteres que define el seguimiento semántico de las versiones de la skill, por ejemplo: 1.0.0.

Suele emplearse para configurar pipelines, actualizaciones de despliegues o el seguimiento en determinados ecosistemas.

context (opcional) inline | fork

Nos permite definir cómo se ejecuta la skill en relación al hilo de conversación principal del agente.

Este aspecto es importante a nivel de configuración de orquestación de memoria y el aislamiento de entornos por parte del agente cuando la skill es invocada.

Por defecto, si este campo no es definido, la skill se ejecuta en linea con la conversación en curso, sin embargo, existen valores que le podemos dar al campo para modificar este comportamiento:

inline (valor por defecto)

La skill se ejecuta directamente dentro de la ventana conversacional actual.

Las instrucciones, ejemplos y herramientas definidas dentro de SKILL.md son añadidas directamente al contexto actual y el modelo las retiene en su totalidad para ser usadas en posteriores conversaciones.

Se recomienda usar esta configuración cuando al arrancar múltiples tareas que han de trabajar de manera colaborativa, la skill deba conocer todo el historial, tono y referencias específicas que el usuario haya hecho para operar correctamente.

Con todo esto, si elegimos esta opción, hemos de establecer guardarraíles a nivel de descripción para que la skill sepa exactamente cuándo debe dar un paso atrás para recopilar información y luego volver a donde estaba.
fork (modo sub-agente o sandbox aislado)

En este modo, podríamos entender que se crea un "proceso hijo" metafórico donde el agente pausa temporalmente el hilo de conversación principal, copia la información relevante del estado actual y arranca un sub-agente aislado para procesar exclusivamente la tarea encomendada por la skill.

A nivel de memoria, el subagente creado no lee toda la memoria ni el historial de la conversación principal sino que previene que el modelo se distraiga de dicha conversación evitando desviaciones por mezcla de otras consultas.

A nivel de consumo de tokens, como no se coge el historial principal de conversación, sino una pequeña sección muy concreta, podemos reducir el volumen de tokens de entrada y obtener una ejecución más barata y rápida.

Una vez que la skill ha completado su tarea, ésta recopila, limpia y destila un resumen del resultado y lo inyecta en el hilo de la conversación principal antes de cerrar el "proceso hijo" donde ha estado operando.

Con todo esto, si elegimos esta opción, hemos de ser conscientes de que las instrucciones han de ser completamente auto-contenidas ya que la skill no tendrá acceso al historial completo de conversación.

Tabla comparativa

Funcionalidad / Comportamiento	`context: inline` (Default)	`context: fork`
Área de trabajo	Ventana de conversación principal	Subagente aislado
Visibilidad del historial	Historial completo preservado	Oculto (o fuertemente restringido)
Consumo de tokens	Alto (Crece con la longitud de la conversación)	Bajo (Optimizado para datos específicos de la skill)
Resultado obtenido	Continuo a medida que la conversación continua	Un resumen sencillo y estructurado
Caso de uso principal	Asistente interactivo (p.e., Copywriting)	Trabajos pesados en background (p.e., Code review)

compatibility (opcional)

Este campo actúa como una validación de entorno, asegurándose de que el equipo donde se está ejecutando la skill o el motor de ejecución, tiene las capacidades de hardware, paquetes de software o requisitos de motor LLM requeridos para ejecutar las instrucciones definidas dentro de la skill. Por ejemplo, podemos definir los requisitos de razonamiento mínimos del LLM, así como las restricciones del sistema operativo, los paquetes para la CLI o los binarios requeridos.

En caso de que el sistema escanee la skill y detecte un problema de compatibilidad, la skill se desactiva o es ocultada para prevenir errores en tiempo de ejecución.

Por ejemplo:

  compatibility:
    model: ">=gpt-4o"
    os: "linux, darwin"
    dependencies:
      - "python>=3.10"
      - "ffmpeg"

allowed-tools (opcional) (también conocido por allow-tools)

Este campo está definido por un listado de valores que permiten establecer o acotar estrictamente aquellas herramientas que están permitidas al agente para ser utilizadas cuando se ejecute la skill.

A la hora de definir el contenido de esta propiedad se ha de tener en mente el Principio del Mínimo Privilegio de manera que, si una skill necesita leer documentación local, no se le debe permitir ejecutar comandos de terminal.

Cuando una skill que posee esta propiedad definida se ejecuta, el agente automáticamente suspende/desactiva cualquier herramienta no especificada en el listado, de manera que incluso si el modelo alucinara e invocase alguna de las herramientas no permitidas, el orquestador del modelo la bloquearía.

Una de las principales ventajas de este campo es que previene el consumo excesivo a raíz del uso innecesario de herramientas caras o la ejecución de operaciones peligrosas (archivos, bases de datos, infraestructura, etc.), que no estén claramente autorizadas.

Por ejemplo:

  allowed-tools:
    - internet_browse
    - read_local_file
    - parse_json

disable-model-invocation (opcional) true | false

Este campo se emplea para configurar el nivel de "conciencia" que el modelo tiene sobre la existencia o no de la skill en cuestión.

Cuando este campo no se define o se pone a su valor por defecto (false), cuando el agente arranque la tendrá en su listado de skills disponibles y si el usuario dice Revisar los registros de mi servidor, el modelo analizará la descripción de la skill y si coincide con el objetivo de la petición, comenzará a ejecutar la skill.

En el caso de que esta opción se defina como true, el modelo ignorará por completo esta skill, independientemente del uso que se esté haciendo del agente. La única manera que hay de poder usarla es a través de la invocación explícita de dicha skill, es decir /skill-name.

Esta configuración es realmente interesante para flujos de trabajo destructivos, que apliquen cambios irreversibles o que conlleven un alto riesgo para el sistema, donde una interpretación errónea por parte del modelo puede acarrear la pérdida accidental de datos valiosos o modificaciones no autorizadas del sistema.

Por ejemplo:

  name: wipe-database-cache
  disable-model-invocation: true

metadata (opcional)

Este campo es un diccionario no estructurado diseñado para tareas específicas de desarrollo, donde podemos añadir información adicional referente a la skill.

Sirve como puente de comunicación entre diferentes plataformas, editores de código y frameworks, que necesitan una manera de definir información adicional relevante para cada cual, sin romper el estándar abierto de la definición de skills.

Uno de los principales usos que se le suele dar a este campo es para mostrar información de la skill en formato human-friendly en aplicaciones o herramientas que gestionan skills.

Por otro lado, cuando las skills no son públicas, este campo se puede usar para la trazabilidad de su desarrollo a nivel corporativo.

Por ejemplo:

  metadata:
    author: "Platform Security Team"
    category: "DevOps / SRE"
    icon: "shield-alert"
    cost_center: "fintech-ops-99"

Algunos ejemplos completos de cabeceras de skill podrían ser los siguientes:

# Este ejemplo usa 'context: fork' para que se ejecute en un hilo seguro, con bajo consumo de tokens para realizar
# la validación pesada a nivel de backend. Además, como se ejecuta de manera autónoma, puede ser invocada de manera
# automática por parte del modelo he incluir las herramientas CLI necesarias para poder llevar a cabo su tarea.
---
name: kubernetes-manifest-validator
description: Use this skill when the user provides Kubernetes YAML files, Helm charts, or K8s deployment manifests and requests syntax validation, security linting, or API deprecation checks.
license: Apache-2.0
version: 2.4.1
context: fork
compatibility:
  model: ">=gpt-4o"
  os: "linux"
  dependencies:
    - "kubeconform>=0.6.0"
    - "trivy>=0.45.0"
allowed-tools:
  - read_local_file
  - execute_terminal_command
  - write_local_file
disable-model-invocation: false
metadata:
  team: "SRE-Core"
  environment: "staging-validation"
  severity-tier: "medium"
---

---
# Este ejemplo usa 'context: inline' para que se ejecute dentro de la ventana de contexto del agente, dado que
# necesita acceso al historial de conversación completo. La restricción de herramientas permiten al modelo
# ejecutar la skill durante la conversación.
name: market-competitor-analyzer
description: Use this skill when the user asks for competitive intelligence, financial market trends, stock ticker comparisons, or landscape analysis regarding corporate competitors.
license: MIT
version: 1.0.3
context: inline
compatibility:
  model: ">=gpt-4-mini"
  os: "any"
  dependencies:
    - "python-yfinance>=0.2.0"
allowed-tools:
  - web_search
  - fetch_url_content
  - render_data_chart
disable-model-invocation: false
metadata:
  department: "Product-Strategy"
  billing-code: "mkt-res-2026"
  ux-icon: "trending-up"
---

# Esta skill conlleva la eliminación irrevocable de datos por lo que contiene la configuración
# 'disable-model-invocation: true', haciendo que sólo pueda ser invocada por una persona. Además,
# con el campo 'compatibility' le estamos limitando la base de datos específica sobre la que puede
# operar.
---
name: production-database-purger
description: Mandatorily hidden from automatic routing. This skill safely drops stale tables, truncates high-volume log schemas, and runs database vacuuming routines on production clusters during maintenance windows.
license: Proprietary
version: 4.0.0-rc1
context: fork
compatibility:
  model: ">=o1-preview"
  os: "linux, darwin"
  dependencies:
    - "postgresql-client-16"
    - "aws-cli-v2"
allowed-tools:
  - execute_sql_query
  - fetch_vault_secret
disable-model-invocation: true
metadata:
  compliance-required: "SOC2-Type-II"
  requires-human-approval: true
  criticality: "high"
  slack-alert-channel: "#prod-ops-logs"
---

Llegados a este punto, es importante remarcar que, aunque estos campos puedan pertenecer a un estándar, no todos los agentes los entienden o usan nomenclaturas diferentes para alcanzar el mismo objetivo. En la siguiente tabla se muestra qué agente acepta qué campo de cabecera:

Campos de cabecera para SKILL.md soportados según agente

Header Field	Claude Code CLI	Claude.ai (Web)	Claude API	AutoGen Studio	CrewAI Core	LangGraph Engine	OpenCode CLI	Aider CLI	CodeRabbit CLI
`name`	✅	✅	✅	✅	✅	✅	✅	✅	✅
`description`	✅	✅	✅	✅	✅	✅	✅	✅	✅
`version`	✅	❌	✅	❌	✅	✅	✅	❌	✅
`license`	✅	❌	✅	❌	❌	❌	❌	❌	✅
`context`	✅	❌	✅	❌	❌	❌	✅ (mode)	❌	✅
`allowed-tools`	✅	❌	✅	✅	✅	✅	✅ (perms)	✅	✅
`disable-model-invocation`	✅	❌	✅	❌	❌	❌	✅ (disable)	❌	✅
`compatibility`	✅	❌	✅	❌	❌	❌	✅ (deps)	❌	❌
`metadata`	✅	✅	✅	✅	✅	✅	✅	✅	✅

🛢 Cuerpo de una skill (patrón `T-I-P-O`)

Una vez hemos completado la definición de la cabecera de la skill, ahora le toca el turno al cuerpo.

⚠️ IMPORTANTE
A diferencia de lo que sucede en la sección de cabecera, el cuerpo de una skill sí se define usando Markdown.

Lo que definamos aquí será un compendio de directivas semánticas, estructuradas de una determinada manera, que el modelo es capaz de asimilar como instrucciones operativas.

Este bloque es determinante para que el agente se comporte lo más determinista posible o que empiece a tener alucinaciones críticas durante la ejecución.

A pesar de la importancia de este bloque, al tratarse de open source, no existe una estructura única y estricta que de manera universal nos obligue a definir el cuerpo de una skill de una determinada manera. No obstante, en entornos empresariales se está convergiendo a usar el patrón denominado T-I-P-O (Targets, Inputs, Procedure y Outputs), siendo el mínimo indispensable aceptado de facto para garantizar un mínimo de determinismo en el modelo.

# Target (u # Objective)

Define qué se está buscando con la ejecución de esta skill y cuál es el objetivo final esperado.

Cuando un agente se pierde en un bucle de llamadas a herramientas, reevalua su progreso comparándolo con lo definido en este apartado.

Ejemplo:

  # Target

  The absolute objective of this skill is to locate deprecated API endpoints inside the repository, upgrade them to the current SDK version, and ensure the test suite passes with zero errors.

# Inputs (o # Prerequisites)

Define las variables, archivos o formatos de datos exactos que el agente debe recibir antes de empezar a trabajar.

Este apartado es importante porque evita que el agente empiece a "adivinar" o inventar datos; de modo que, si el contexto actual no contiene estos elementos, el agente sabe que debe detenerse y pedirlos.

Por ejemplo:

  # Inputs

  This skill requires two primary artifacts from the active workspace context:

  1. `legacy_endpoints.json` - A manifest listing the raw endpoints.
  2. `current_sdk_spec.yaml` - The up-to-date OpenAPI schema reference.

# Procedure (o # Execution Steps)

Define una lista numerada y secuencial que el agente debe seguir estrictamente y paso por paso.

Con esto conseguimos segmentar el razonamiento del modelo en subtareas manejables (Chain-of-Thought) al tiempo que forzamos al agente a seguir pasos numerados, reduciendo las posibles alucinaciones en flujos donde se empleen múltiples herramientas.

Por ejemplo:

  # Procedure

  1. Parse the `legacy_endpoints.json` file using the `read_file` tool.
  2. For each endpoint listed, locate its definition in the codebase using `grep_search`.
  3. Replace the deprecated syntax with the new methods specified in `current_sdk_spec.yaml`.
  4. Run the local testing pipeline using `execute_terminal_command(command="npm test")`.

# Outputs (o # Expected Output Format)

Define el contrato de salida al finalizar la ejecución de la skill.

Aquí indicamos si queremos obtener un JSON, un Markdown, un Markdown Code Block, etc., así como la estructura exacta de la respuesta final.

De este modo, las salidas del agente serán fácilmente legibles por otros scripts automatizados o por el usuario, sin que contenga texto de relleno.

Por ejemplo:

  # Outputs

  Return exclusively a valid JSON block containing the compilation summary. Do not include conversational preambles.

Ejemplo completo de una skill definida:

---
name: api-migration-tool
description: Use when the user requests an automated upgrade of legacy API endpoints.
version: 1.0.0
context: fork
allowed-tools:
  - read_file
  - write_file
  - grep_search
  - execute_terminal_command
disable-model-invocation: false
---

# Target

Migrate deprecated microservice API routing schemas to the v2 standard.

# Inputs

- Workspace variable: `target_directory`
- Source config file: `api_routing.conf`

# Procedure

1. Scan the `target_directory` for any `.conf` files.
2. Cross-reference keys against the official version 2 documentation wrapper.
3. Apply the structural rewrites into a new temporary branch.
4. Validate the syntax integrity.

# Outputs

Provide a markdown table summarizing:

- The file paths modified.
- The original lines of code.
- The rewritten replacement chunks.

🔎 NOTA
Como nota final relativa al cuerpo de una skill, cuando estamos en una sección donde implementamos un listado no ordenado, en ocasiones podemos encontrar que se usa tanto el guión medio (-) como el asterisco (*) para indicar un elemento de dicha lista.
Si bien es verdad que a nivel computacional, al modelo le da exactamente igual, aquí prima la limpieza y el orden a nivel de DevEx, por lo que se promueve el uso de guión medio (-) para los elementos de una lista no ordenada, frente a cualquier otro carácter.

Estas son las secciones básicas que debería tener una skill. A parte de estas, si las necesidades de nuestra aplicación requieren de la definición de más secciones, tenemos total libertad para hacerlo siempre que ello permita afinar más el uso de la skill.

Algunas secciones adicionales a los propuestos por el patrón T-I-P-O son las siguientes:

# Guardrails & Safety Constraints

Define restricciones críticas mediante el listado de límites absolutos, comportamientos prohibidos y zonas donde el agente jamás debe interactuar.

Esta es la principal línea de defensa contra destrucciones de datos o brechas de seguridad.

Por ejemplo:

  # Guardrails & Safety Constraints

  - **NEVER** pass raw string variables directly into bash command lines without character escaping.
  - Do not modify or read any files inside the hidden `.git/` or `.vault/` internal directories.

# User Verification Gates

Establece los puntos de aprobación humana, definiendo explícitamente qué acciones específicas detienen de forma obligatoria el flujo autónomo del agente para requerir un "Ok" visual o confirmación manual por parte del usuario, en el chat.

Por ejemplo:

  # User Verification Gates

  - **Trigger:** Prior to executing any database truncation or dropping an index.
  - **Action:** Halt the script, render the specific SQL payload to the user, and ask: "Do you confirm the execution of this database migration? (y/n)".

# Escalation Protocols

Esta sección evita que el agente se quede atrapado intentando resolver problemas que superan sus capacidades de permisos, instruyéndolo sobre cuándo rendirse y derivar el caso a un usuario humano.

Por ejemplo:

  # Escalation Protocols

  - If a connection timeout error occurs more than 3 consecutive times on port 5432, halt automation.
  - Do not attempt to guess credentials. Output: `[CRITICAL] Network isolation detected. Escalating ticket to SRE team.`

# State Tracking & Memory Logging

Con esta sección forzamos al modelo a estructurar su proceso de pensamiento e internalizar los cambios de estado en variables locales antes de llamar a la siguiente herramienta, solucionando la pérdida de memoria en flujos de trabajo muy largos.

Por ejemplo:

  # State Tracking & Memory Logging

  - Before modifying a file, open a `<state>` block to log the original file hash and line count.
  - Maintain a rolling list of modified assets in your tool call parameters to avoid circular file edits.

# Chain-of-Thought Auditing

Aquí lo que hacemos es obliga al agente a justificar cada acción utilizando etiquetas XML específicas (como ) antes de invocar comandos terminales, lo que facilita enormemente la depuración y auditoría del comportamiento del agente.

Por ejemplo:

  # Chain-of-Thought Auditing

  - Every tool call must be preceded by a `<reasoning>` block containing:
    1. Why this tool is necessary now.
    2. The expected outcome of the invocation.

# Performance & Cost Optimization

Aquí podemos prevenir que el agente consuma de forma descontrolada el presupuesto de la API (o agote la ventana de contexto) ,regulando la cantidad de texto que puede leer o escribir en una sola iteración.

Por ejemplo:

  # Performance & Cost Optimization

  - When parsing log files, use range parameters to inspect a maximum of 150 lines per tool call.
  - Avoid re-reading large context files if the content was already logged in the active scratchpad.

# Compliance & Regulatory Standards

Este apartado es importante cuando operamos con determinados datos, ya que nos asegura que los entregables generados por el agente (como código fuente o reportes de datos), cumplan con normativas legales u organizacionales estrictas del sector (SOC2, GDPR, ISO), o de la propia empresa.

Por ejemplo:

  # Compliance & Regulatory Standards

  - All telemetry methods designed by this skill must completely sanitize PII (Personally Identifiable Information).
  - Ensure encryption-in-transit configurations use TLS 1.3 as a baseline.

# Workspace Clean-up & Idempotency

Con esta propiedad podemos garantiza la higiene del sistema local, asegurando que el agente borre sus archivos temporales de ejecución y que, si la skill se ejecuta dos veces seguidas, el resultado sea idéntico sin duplicar datos.

Por ejemplo:

  # Workspace Clean-up & Idempotency

  - Upon task completion or premature failure, execute an explicit cleanup step to delete `/tmp/cache_*.json`.
  - Design every code refactor to be completely idempotent; running the skill twice must yield zero changes on the second run.

# Corporate Style & Terminology Glossaries

Aquí podemos unificar los términos de negocio y la voz del agente cuando genera documentación técnica, reportes o respuestas textuales dirigidas a clientes finales o a la directiva de la empresa.

Por ejemplo:

  # Corporate Style & Terminology Glossaries

  - Use the term "Client Workspace" instead of "Tenant Folder" across all markdown outputs.
  - Keep tone formal and highly concise; eliminate words like "obviously", "simply", or conversational expressions.

# Diagnostic & Telemetry Footprints

Esta propiedad inyecta firmas digitales y logs estandarizados en los commits de Git o cabeceras de archivos creados por el agente para identificar de forma unívoca qué cambios fueron hechos por la IA y qué versión de la skill se utilizó.

Por ejemplo:

  # Diagnostic & Telemetry Footprints

  - Append this precise signature at the end of every modified file header:
    `/* Automated optimization applied via agent-skill: db-optimizer (v2.4.1) */`

🗃 Skills más complejas

A medida que desarrollamos una skill, ésta puede volverse cada vez más compleja lo que hace que nuestro archivo SKILL.md se vuelva prácticamente inoperativo por la cantidad de información, instrucciones, ejemplos o similares que puede contener. El resultado más probable es:

😰 cargar todo este contenido en un agente,
🤯 saturación temprana del contexto,
🔥 incrementando del consumo innecesario de tokens y,
💀 degradando la respuesta del modelo.

La solución a esto está en un proceso llamado Atomización de la skill mediante el cual, se extrae de la misma lógica pesada, recursos externos y ejemplos referenciales que permiten transforma a la skill en un orquestador declarativo, manteniendo el contenido del archivo por debajo de las 50 o 100 líneas de texto. Esto hace que la velocidad de inicialización de la skill en el agente sea muy alta e incrementa la escalabilidad del sistema a través de la actualización independiente de referencias.

Este proceso de atomización se lleva a cabo realizando estas dos acciones: Estructuración rigurosa y Enlazado técnico.

Estructuración rigurosa

Dentro del directorio donde hemos definido el archivo SKILL.md, comenzaremos a crear directorios con nombres semánticamente razonables.

En cada uno de esos directorios, crearemos los archivos correspondientes que contendrán la información que deseamos extraer de la skill original.

La estructura de directorios depende únicamente del equipo de desarrollo pero sí es verdad que hay cierta tendencia a contar con determinados directorios ya establecidos, que no es necesario implementar si nuestra skill no los requiere, pero de hacerlo, se recomienda mantener el nombrado de los mismos.

Un ejemplo de estructuración rigurosa podría ser éste:

  my-complex-agent-skill/
    ├── SKILL.md                 # (Obligatorio) Archivo principal (Orquestador y Frontmatter)
    ├── scripts/                 # (Opcional   ) Código ejecutable que delega lógica pesada fuera del LLM
    │   └── optimize_matrix.py   #               Script de cómputo numérico/análisis complejo
    ├── assets/                  # (Opcional   ) Datos estáticos y esquemas de validación
    │   └── database_schema.json #               Estructura de la base de datos de referencia
    ├── references/              # (Opcional   ) Guías de estilo, manuales o documentación densa
    │   └── code_style_guide.md  #               Reglas de formato que el LLM solo lee si es necesario
    └── examples/                # (Opcional   ) Biblioteca de Few-Shot Examples (historias de usuario)
        ├── standard_case.md
        └── edge_case_timeout.md

Enlazado técnico

Ahora que ya hemos extraído el exceso de información de nuestra skill a secciones independientes de nuestra estructura de directorios, necesitamos enlazar dicho contenido dentro del archivo que ha quedado.

Para ello emplearemos rutas relativas explícitas al contenido que queramos hacer referencia. Los agentes son capaces de leer estas rutas y mediante el uso de herramientas internas, pueden acceder a los archivos bajo demanda, únicamente cuando la sección del procedimiento lo exige.

Con esto:

✅ evitamos cargar todo este contenido en un agente de primeras,
✅ evitamos la saturación temprana del contexto,
✅ reducimos el consumo innecesario de tokens y,
✅ evitamos la degradación temprana de la respuesta del modelo.

Para hacer esto, hay dos patrones que se usan habitualmente: Enlace relativo directo y Enlace de referencia al pie.

Enlace relativo directo

Se usa para dependencias inmediatas que el agente siempre debe inspeccionar antes de ejecutar un procedimiento.

Por ejemplo:

# Inputs

This skill requires the project context infrastructure to match the configuration rules specified in the core [Database Architectural Reference Schema](./assets/database_schema.json).

Enlace de referencia al pie

Se usa para dependencias que es interesante tener enlazadas pero cuya carga se lleva a cabo en situaciones muy concretas, es decir, el agente no cargará estas referencias en el contexto salvo extrema necesidad.

Además de esto, también suelen ser usados en procedimientos muy largos, relegando las referencias al final del archivo y evitando ruido en el texto.

Por ejemplo:

# Procedure

1. Pull the latest Docker manifest using the environment variables.
2. Build the staging container and verify the cluster health check endpoints.
3. In case the build triggers a pipeline schema violation, fetch the resolution steps immediately.

# Error Handling & Edge Cases

* If the server returns a 503 error, verify if your service mesh matches the internal corporate architecture layout.

---

# Resource Footnotes / Lazy-Load References: ./assets/health_check_spec.json: ./references/pipeline_troubleshooting_guide.md: ./references/corporate_network_mesh_v2.md

Ahora bien, ¿cómo podemos empezar a externalizar una skill? Pues podemos empezar por plantear los siguientes pasos:

1. Mover scripts fuera del contexto de prompt (/scripts)

Dado que explicarle naturalmente a un agente las operaciones que debe llevar a cabo un script es complejo y consume tokens sin necesidad, podemos crear un archivo de scripting en un lenguaje de nuestra elección, que realice dicha operación.

En la cabecera de la skill, dentro del apartado allowed-tools daremos permisos de ejecución al comando execute_terminal_command e invocaremos nuestros script desde el texto de la skill.

Por ejemplo:

  ---
  name: my-custom-skill
  description: ...
  allowed-tools:
    - execute_terminal_command
  ---

  # Procedure

  1. Do not compute matrix variances manually. Instead, trigger the native optimization script:
    `execute_terminal_command(command="python3 ./scripts/optimize_matrix.py --path=.")`

2. Externalizar la biblioteca de ejemplos (/examples)

Hay que tener mucho cuidado con el uso que hagamos de los archivos enlazados de esta sección, dado que por lo general, al contener ejemplos extensos y concretos, pueden ocupar mucho, elevando el consumo de tokens, tanto de entrada como de salida, si hacemos un mal uso de los ejemplos.

Lo ideal aquí es que cada ejemplo sea un archivo independiente, de manera que su enlazado permita cargar uno u otro dependiendo de las necesidades del agente.

Por ejemplo:

  # Expected Workflows

  Before formatting your final response, read and analyze the corresponding execution logs inside the example library based on the current workload:
  - For standard microservice queries, read [Standard Flow Case](./examples/standard_case.md).
  - For database connection timeouts, read [Timeout Recovery Case](./examples/edge_case_timeout.md).

3. Cargar documentación bajo demanda (/references)

La documentación de APIs, procedimientos, etc., puede saturar el contexto de un agente de manera muy rápida, además de que su continua actualización requeriría modificar también el contenido de la skill.

Si extraemos dicha documentación a archivos independientes y aislados, podemos realizar una carga selectiva de los mismos únicamente cuando sea necesario.

Por ejemplo:

  # Error Handling & Edge Cases

  If a compilation error occurs due to typing differences, do not attempt to guess the syntax. Read the internal reference document [Type Definition Manual](./references/code_style_guide.md) before attempting a second patch rewrite.

🧐 Buenas (✅) y malas (❌) prácticas a seguir a la hora de definir una skill

A nivel de cabecera

✅ Sincronizar el nombre y la carpeta: Mantén el campo name escrito en kebab-case (minúsculas con guiones) y asegúrate de que coincida exactamente con el nombre de la carpeta contenedora para evitar fallos de indexación.
✅ Acotar las descripciones semánticas: Redacta el campo description utilizando verbos de acción y palabras clave de activación específicas (ej. "Use when the user requests an API optimization"). Esto optimiza el enrutado y evita activaciones accidentales.
✅ Aplicar el Principio de Menor Privilegio: Declara exclusivamente en allowed-tools las herramientas que la skill necesita estrictamente para cumplir su objetivo, bloqueando el acceso a comandos peligrosos del sistema si no son requeridos.
✅ Forzar la aprobación humana en tareas críticas: Configura disable-model-invocation: true en skills destructivos o de producción (como despliegues o purgas de bases de datos) para obligar a que la skill sólo se active mediante un comando de barra (/) escrito por una persona.
✅ Especificar las dependencias del entorno: Utiliza el campo compatibility para listar las versiones mínimas de los binarios del sistema (ej. python>=3.10, docker), para que el framework detenga la ejecución antes de generar un error de terminal.
✅ Aprovechar los metadatos para la gobernanza: Utiliza el bloque metadata de forma sistemática en entornos corporativos para registrar el equipo propietario, el centro de costos y los identificadores de cumplimiento (ej. compliance: SOC2).
❌ Duplicar nombres de skills: Usar el mismo campo name en diferentes archivos SKILL.md dentro del repositorio, lo que provoca colisiones y hace que el orquestador ignore componentes de forma aleatoria.
❌ Crear descripciones genéricas o ambiguas: Escribir descripciones del tipo description: "An AI assistant to help you write code". Esto causa que el LLM active la skill constantemente para tareas comunes, saturando la ventana de contexto.
❌ Otorgar permisos universales por pereza: Declarar comodines en las herramientas o incluir herramientas de ejecución de terminal (execute_terminal_command) en skills que sólo requieren lectura de datos.
❌ Ignorar el control de versiones: Dejar el campo version estático en 1.0.0 indefinidamente, impidiendo que las canalizaciones de CI/CD verifiquen si los agentes en producción ejecutan el comportamiento validado más reciente.
❌ Confundir el rol de context: fork: Configurar un skill como context: inline cuando requiere procesar miles de líneas de registros de servidores, provocando que el chat principal se llene de ruido y se agote el presupuesto de tokens.
❌ Omitir el campo license en skills compartidos: Dejar el campo de licencia vacío en repositorios internos compartidos, lo que expone a los equipos de desarrollo a problemas de cumplimiento de propiedad intelectual.

A nivel de cuerpo

✅ Adoptar la estructura estándar T-I-P-O: Organiza siempre el cuerpo del documento utilizando los bloques # Target, # Inputs, # Procedure y # Outputs para guiar al modelo a través de un flujo determinista.
✅ Escribir procedimientos imperativos y numerados: Utiliza listas numeradas (1., 2., 3.) en la sección del procedimiento para forzar un razonamiento secuencial paso a paso (Chain-of-Thought).
✅ Estandarizar las viñetas no ordenadas con guiones: Utiliza exclusivamente guiones (-) para listas de restricciones, entradas o herramientas. Deja los asteriscos (*) únicamente para negritas (**) o itálicas (*), facilitando la lectura de los analizadores de sintaxis.
✅ Externalizar los manuales densos mediante notas al pie: Aplica la carga perezosa (lazy loading) moviendo las rutas de manuales o guías secundarias al pie de la página ([Reference 1]: ./references/guide.md), manteniendo el flujo principal limpio de texto de relleno.
✅ Definir contratos de salida estrictos: En la sección # Outputs, especifica el formato exacto de respuesta (ej. un esquema JSON válido o una tabla Markdown), y prohíbe explícitamente los preámbulos conversacionales como "Sure, here is your summary".
✅ Declarar restricciones negativas de forma asertiva: Dedica una sección independiente a las restricciones de seguridad (# Guardrails & Safety Constraints) y redacta las prohibiciones en mayúsculas e imperativo (ej. "NEVER run recursive deletes").
❌ Mezclar estilos de viñetas en un mismo bloque: Combinar guiones (-) y asteriscos (*) de forma aleatoria dentro de una misma lista, lo que puede romper la segmentación del contexto en ciertos motores de análisis.
❌ Escribir instrucciones en prosa narrativa de formato libre: Redactar el procedimiento como un párrafo largo en lugar de una lista estructurada. Los modelos tienden a omitir instrucciones secundarias cuando están ocultas en bloques densos de texto.
❌ Incrustar código fuente extenso dentro de las instrucciones: Pegar scripts completos de Python o Bash en el cuerpo del prompt. Esto degrada drásticamente la atención del modelo y dispara los costos de ejecución.
❌ Asumir que el agente conoce el entorno actual: Escribir procedimientos sin definir previamente la sección # Inputs, causando que el agente intente adivinar rutas de archivos, nombres de variables o entornos de bases de datos.
❌ Utilizar lenguaje ambiguo o condicional: Usar frases como "Please try to optimize the query if you think it is a good idea". Los agentes de producción requieren instrucciones directas y deterministas (ej. "Analyze query latency using the EXPLAIN tool").
❌ Saturar la skill con demasiados objetivos secundarios: Intentar que un solo archivo SKILL.md realice análisis de código, despliegues en la nube y optimización de bases de datos simultáneamente. Si el alcance crece, divídelo en skills independientes.

A nivel de robustez, manejo de errores y escalabilidad

✅ Diseñar rutas de escape claras para errores de herramientas: Dedica una sección a # Error Handling donde indiques detalladamente qué debe hacer el agente si una herramienta devuelve un error, se agota el tiempo de espera (timeout) o devuelve datos vacíos.
✅ Delegar el procesamiento numérico y algorítmico a scripts: En lugar de pedirle al modelo que analice una matriz o un JSON gigante mediante prompts, escribe un script nativo en /scripts y haz que el agente lo ejecute y procese únicamente el resumen de salida.
✅ Implementar Few-Shot Examples modulares: Almacena los ejemplos complejos de interacciones en archivos independientes dentro de un directorio /examples y enlázalos bajo demanda, evitando saturar el contexto inicial del agente.
✅ Verificar la integridad de los enlaces relativos mediante CI/CD: Implementa un script automatizado en tu flujo de integración que valide que todas las referencias a ./assets/, ./scripts/ o ./references/ dentro de tus skills existan físicamente y no estén rotas.
✅ Establecer límites de detención (Halt Conditions): Instruye explícitamente al agente para que detenga la ejecución de inmediato y solicite la intervención de un supervisor humano si encuentra problemas de permisos críticos (p.e.: 403 Unauthorized), o fallos de red persistentes.
✅ Mantener el core de la skill por debajo de los 100 tokens de configuración: Diseña el SKILL.md principal como un director de orquesta ligero y minimalista que delega en recursos externos, garantizando arranques ultra rápidos y un consumo óptimo de memoria.
✅ Definir skills a nivel de proyecto según las necesidades de éste: Cuando una skill es usada en proyectos de manera aislada, no es recomendable extraerlas para que sean consumidas de manera global, dado que cualquier agente la cargará independientemente de que la necesite para el repositorio en cuestión, o no. Sólo crearemos skills globales o promocionaremos una skill local a global, cuando tengamos un 100% de certeza de que dicha skill va a ser empleada por todos los proyectos.
❌ Permitir bucles infinitos de reintentos: Omitir instrucciones de contingencia ante fallos, lo que causa que el agente intente ejecutar la misma herramienta defectuosa una y otra vez en un ciclo infinito que consume tu presupuesto de API.
❌ Ocultar mensajes de error del sistema: Instruir al modelo para que ignore los fallos del terminal (p.e.: 2> /dev/null). Si el agente enmascara los errores, diagnosticar comportamientos anómalos en entornos de producción se vuelve imposible.
❌ Hardcodear credenciales, rutas absolutas o secretos: Escribir contraseñas, tokens de API o rutas absolutas como /Users/username/project en el cuerpo de la skill. Esto rompe la portabilidad del agente entre diferentes sistemas y genera una vulnerabilidad crítica de seguridad.
❌ Confiar ciegamente en la memoria de contexto a largo plazo: Diseñar un procedimiento que dependa de que el agente recuerde un dato proporcionado al inicio del chat general, especialmente cuando opera en configuraciones context: inline.
❌ Validar cambios utilizando el propio entorno de producción: Permitir que una skill de refactorización de código aplique modificaciones directas sobre la rama principal (main) sin forzar la ejecución previa de la suite de pruebas unitarias locales en una rama aislada.
❌ Actualizar scripts externos sin actualizar el manual de la skill: Modificar los parámetros de entrada de un script de automatización en ./scripts/ pero olvidar actualizar las reglas de llamada a herramientas correspondientes en el cuerpo del archivo SKILL.md, provocando que el agente invoque comandos con sintaxis obsoleta.

👋 Conclusiones finales

Está claro que si hay algo que no ha cambiado con la llegada de la IA al mundo del desarrollo, es que las buenas prácticas son más necesarias ahora que nunca y como muestra de ello, es el especial mimo que debemos poner a la hora de definir nuestras skills.

Espero que este contenido te haya sido útil. Si tienes cualquier pregunta, siéntete totalmente libre de contactar conmigo. Aquí están mis perfiles de X, LinkedIn y Github.

🙏 Reconocimientos y agradecimientos

Por supuesto a @mouredev por destinar tiempo a preparar y difundir el taller que ha sido el origen de todo el texto que, si has llegado hasta aquí, has leído.

Definiendo nuestras infraestructuras para desarrollo y testing con Docker

Dailos Rafael Díaz Lara — Mon, 28 Dec 2020 16:39:44 +0000

🇬🇧 English version

🎯 Objetivo

Cuando estamos creando una nueva aplicación o funcionalidad, normalmente necesitamos enviar peticiones a recursos independientes como pueden ser una base de datos o servicios con comportamiento controlado pero obviamente, realizar estas tareas contra servidores en la nube tiene un coste.

En este tipo de situaciones es cuando el aislamiento de sistemas que nos proporcionan los contenedores de Docker, es realmente útil.

En este artículo vamos a ver cómo podemos usar Docker para levantar una infraestructura mínima que nos permita ejecutar las tareas de desarrollo y/o testing, localmente.

El principal objetivo de este texto es mostrar cómo utilizar un único archivo docker-compose.yml para ambos entornos, empleando diferentes archivos .env para personalizar cada contenedor específico tanto para desarrollo como para testing.

Además, nos centraremos en cómo arrancar un nuevo contenedor para testing, ejecutar los tests que sean pertinentes y finalmente, apagar dicho contenedor.

💻 Configuración del sistema

Si vamos a hablar sobre Docker, es obvio que necesitamos tenerlo instalado en nuestro sistema. Si aún no lo tienes, puedes seguir las indicaciones dadas en la documentación oficial, para el sistema operativo que corresponda.

Otro elemento que vamos a necesitar tener instalado en nuestro sistema es docker-compose. De nuevo, si aún no lo tienes instalado, puedes seguir las indicaciones de la documentación oficial.

Por último, dado que este ejemplo está orientado a aplicaciones basadas en JavaScript/TypeScript, necesitamos tener instalado NodeJS (documentación oficial).

🏗 Inicialización del proyecto

🔥 Si ya tienes inicializando tu propio proyecto basado en NodeJS, puedes saltarte esta sección 🔥

Vamos a inicializar nuestro proyecto NodeJS abriendo una consola de comandos, en el directorio donde queramos trabajar, y escribimos el siguiente comando:

npm init -y

Esta acción nos creará una único archivo package.json en la raíz de nuestro proyecto, con el siguiente contenido:

Ahora podemos instalar Jest ejecutando la siguiente instrucción en nuestra consola de comandos, para incluir esta librería en nuestro proyecto:

npm i -D jest

El siguiente paso es crear la estructura más básica de directorios para el proyecto.

/
|-- /docker # <= Nuevo directorio.
|-- /node_modules
|-- /src # <= Nuevo directorio.
|-- package-lock.json
|-- package.json

🐳 Definiendo la configuración de Docker

Vamos a tener dos entornos principales (development y test) y la idea es tener un único archivo docker-compose.yml para gestionar los contenedores de ambos entornos.

📄 Definición del archivo `docker-compose.yml`

Para conseguir nuestro objetivo, dentro del directorio /docker vamos a crear un único archivo llamado docker-compose.yml, el cual contendrá el siguiente código:

Como podemos apreciar, hay varias líneas marcadas como coupling smell. Esto significa que, con la configuración actual, podemos ejecutar un único contenedor de Docker destinado principalmente para tareas de desarrollo. Por lo tanto, está altamente acoplado a su entorno de ejecución.

¿No sería genial si fuésemos capaces de reemplazar esas configuraciones definidas directamente en el código, por referencias las cuales vinieran establecidas por algún tipo de archivo de configuración?

⚙ Archivos `.env` para contenedores Docker

!Sí! Podemos usar archivos .env de la misma manera que ya los usamos para nuestras aplicaciones, pero para configurar contenedores de Docker.

Lo primero que necesitamos hacer es modificar el archivo docker-compose.yml que acabamos de crear para usar plantillas basadas en llaves, para definir nombres de constantes que reemplazaremos con los valores indicados en nuestros archivos .env. De este modo, el contenido del archivo docker-compose.yml quedará de la siguiente manera:

Como podemos ver, hemos reemplazado los valores directamente escritos en el código por referencias del tipo ${CONSTANT_NAME}. El nombre de las variables escrito entre llaves será el nombre de los valores definidos en nuestros archivos .env. De esta manera, cuando arranquemos el comando docker-compose usando una opción específica de la línea de comandos que veremos más adelante, el contenido del archivo .env será reemplazado en nuestro archivo docker-compose.yml antes de que se cree el contenedor de Docker.

Ahora es el momento de definir nuestros entornos así que modificamos el contenido del directorio /docker para que quede tal que así:

/
|-- /docker
|   |-- /dev # <= Nuevo directorio y archivo.
|   |   |-- .docker.dev.env
|   |-- /test # <= Nuevo directorio y archivo.
|   |   |-- .docker.test.env
|   |-- docker-compose.yml
|-- /node_modules
|-- /src
|-- package-lock.json
|-- package.json

Por cada entorno hemos creado un único subdirectorio: dev y test.

Dentro de cada subdirectorio de entorno hemos creado un archivo .env específico: .docker.dev.env y .docker.test.env.

🙋❓ ¿Sería posible nombrar los archivos de entorno sólo como .env?

Sí, es posible y además, no habría ningún problema en ello pero... un nombre de archivo tan descriptivo es una ayuda para nuestro rol como profesionales del desarrollo. Dado que en un mismo proyecto es muy probable que haya múltiples archivos de configuración, es útil ser capaz de diferenciarlos cuando tenemos varios de ellos abiertos, en el editor de código, al mismo tiempo. Esta es la razón por la que los archivos .env tienen uno nombres tan descriptivos.

Ahora pasaremos a definir el contenido de nuestros archivos de entornos, para que queden de la siguiente manera:

y...

Hay cuatro propiedades a las que debemos prestar atención a la hora de diferenciar entre los dos archivos:

CONTAINER_NAME
EXTERNAL_PORT
VOLUME_NAME
CONFIGURATION_PATH

La propiedad CONTAINER_NAME nos permite definir el nombre del contenedor que veremos después de que éste ha sido creado y además, cuando ejecutamos el comando docker ps -a para listar todos los contenedores presentes en nuestro sistema.

EXTERNAL_PORT es una propiedad realmente sensible ya que nos permite definir el puerto que el contenedor tendrán publicado y a través del cual, nuestra aplicación podrá conectarse con él. Es realmente importante tener cuidado con este parámetro porque algunas veces nos interesará tener levantados ambos entornos al mismo tiempo (development y test), pero si hemos definido el mismo puerto de acceso para ambos contenedores, el sistema nos lanzará un error al lanzar el segundo contenedor, ya que el puerto estará ocupado.

La propiedad VOLUME_NAME definirá el nombre del almacenamiento de datos en nuestro sistema.

Finalmente, en caso de que hayamos definido cualquier tipo de conjunto de datos para inicializar nuestra base de datos antes de usarla, la propiedad CONFIGURATION_PATH nos permitirá definir dónde está ubicado ese conjunto de datos.

🙋‍♀️❓ Oye pero, ¿qué pasa con la propiedad COMPOSE_PROJECT_NAME?

Esa es una magnífica pregunta.

Nuestro primer objetivo es crear un contenedor específico por cada entorno, basándonos en el mismo archivo docker-compose.yml.

Ahora mismo, si ejecutamos nuestro docker-compose para development, por ejemplo, crearemos el contenedor con esa definición de entorno y el archivo docker-compose.yml quedará enlazado a dicho contenedor.

De este modo, si intentamos ahora arrancar el mismo archivo pero utilizando la configuración para testing, el resultado final será que hemos actualizado el contenedor previo de development, sin la configuración para el entorno de testing. ¿Por qué? Pues porque el archivo de composición está enlazado al contenedor que arrancamos inicialmente.

Para conseguir nuestro objetivo satisfactoriamente, empleamos la propiedad COMPOSE_PROJECT_NAME dentro de cada archivo .env y le asignamos valores diferentes dependiendo del entorno al que pertenezca.

De esta manera, cada vez que ejecutemos el archivo de composición, dado que el nombre de proyecto es diferente para cada archivo .env, las modificaciones que se apliquen sólo afectarán al contenedor que corresponda con dicho nombre de proyecto.

🙋❓ Vale, bien, pero hemos usado la propiedad COMPOSE_PROJECT_NAME sólo dentro de nuestros archivos .env y no en el archivo docker-compose.yml. ¿Cómo es posible que afecte al resultado final?

Es posible porque esa propiedad es leída directamente por el comando docker-compose y no es necesario que esté incluida dentro del archivo docker-compose.yml.

En este enlace puedes encontrar toda la documentación oficial about COMPOSE_PROJECT_NAME.

🤹‍♂️ Inicializando la base de datos

🔥 Advertencia: El proceso que se expone a continuación está dirigido a inicializar el contenido de una base de datos MongoDB. Si quieres usar un motor diferente, necesitarás adaptar este proceso así como la configuración del docker-compose.yml para ello. 🔥

El concepto más básico que debemos saber, si es que no lo sabemos ya, es que cuando un contenedor basado en MongoDB se ejecuta por primera vez, todos los archivos con extensión .sh o .js ubicados en el directorio /docker-entrypoint-initdb.d dentro del propio contenedor, son ejecutados.

Esto nos proporciona una manera para inicializar nuestra base de datos.

Si quieres profundizar en esta propiedad, puedes consultar la documentación de la imagen oficial de MongoDB en Docker.

🧪 Configuración del entorno de testing

Para ver cómo podemos hacer esto, vamos a empezar por el entorno de testing así que antes de nada, tenemos que crear la siguiente estructura de archivos dentro del directorio /docker/test de nuestro proyecto:

/
|-- /docker
|   |-- /dev
|   |   |-- .docker.dev.env
|   |-- /test
|   |   |-- /configureDatabase # <= Nuevo directorio y archivo.
|   |   |   |-- initDatabase.js
|   |   |-- .docker.test.env
|   |-- docker-compose.yml
|-- /node_modules
|-- /src
|-- package-lock.json
|-- package.json

El contenido del archivo initDatabase.js será el siguiente:

Este script está dividido en tres elementos diferentes.

La constante apiDatabases contiene todas las definiciones de bases de datos que queremos crear para nuestro contenedor.

Cada definición de base de datos contendrá su nombre (dbName), un array de usuarios (dbUsers) los cuales estarán autorizados para operar con la base de datos (incluyendo la definición de sus privilegios de acceso) y el conjunto de datos con los que inicializaremos la base de datos.

La función createDatabaseUser está destinada a gestionar la información contenida en cada bloque del apiDatabases, procesar los datos de usuarios y crearlos dentro de la base de datos indicada.

Finalmente, el bloque try/catch contiene la magia porque en este bloque iteramos sobre la constante apiDatabase, conmutamos entre bases de datos y procesamos la información.

Una vez que hemos analizado este código, si recordamos el contenido de nuestro archivo docker-compose.yml, dentro de la sección volumes definimos la siguiente línea:

- ${CONFIGURATION_PATH}:/docker-entrypoint-initdb.d:rw

Además, para el entorno de testing, dentro del archivo .docker.test.env, configuramos lo siguiente:

CONFIGURATION_PATH="./test/configureDatabase"

Con esta acción, el proceso docker-compose está copiando el contenido de la ruta indicada por CONFIGURATION_PATH dentro del directorio del contenedor /docker-entrypoint-initdb.d:rw antes de que éste se arranque por primera vez. Así es como estamos definiendo el script de configuración de nuestra base de datos, para que sea ejecutado al iniciarse el contenedor.

🙋‍♀️❓ Para esta configuración no estás usando ningún conjunto de datos iniciales. ¿Por qué?

Porque esta será la base de datos de testing y la intención es que se almacenen y eliminen datos ad-hoc en base a los tests que estén ejecutándose en un momento concreto. Por esta razón no tiene sentido que inicialicemos la base de datos con información que vamos a crear/editar/eliminar dinámicamente.

🛠 Configuración del entorno de desarrollo

Esta configuración es muy similar a la de testing.

Lo primero que tenemos que hacer es modificar el subdirectorio /docker/dev de nuestro proyecto, para que quede tal que así:

/
|-- /docker
|   |-- /dev
|   |   |-- /configureDatabase # <= Nuevo directorio y archivos.
|   |   |   |-- initDatabase.js
|   |   |   |-- postsDataToBePersisted.js
|   |   |   |-- usersDataToBePersisted.js
|   |   |-- .docker.dev.env
|   |-- /test
|   |   |-- /configureDatabase
|   |   |   |-- initDatabase.js
|   |   |-- .docker.test.env
|   |-- docker-compose.yml
|-- /node_modules
|-- /src
|-- package-lock.json
|-- package.json

Los archivos postsDataToBePersisted.js y usersDataToBePersisted.js sólo contienen información estática definida dentro de constantes independientes. Esta información será almacenad en la base de datos indicada, dentro de la colección especificada.

La estructura de dichos contenidos será la siguiente:

Por otro lado, el contenido del archivo initDatabase.js es bastante similar al del entorno de testing pero un poco más complejo ya que ahora tenemos que gestionar colecciones y datos. De este modo, el resultado final es este:

En este script hay varias partes que necesitamos analizar.

En la cabecera tenemos un bloque compuesto por dos llamadas a la función load() encaminadas a importar los datos preparados y almacenados en las constantes que declaramos en los otros archivos JavaScript.

🔥 Hay que prestar atención a que la ruta indicada para hacer referencia a los archivos de datos, es relativa al interior de la estructura de ficheros del contenedor de Docker y no a la de nuestro sistema. 🔥

ℹ️ Si quieres aprender más acerca de cómo ejecutar MongoDB archivos JavaScript en su consola de comandos, echa un vistazo a su documentación oficial.

Después de "importar" las definiciones de las constantes usersToBePersisted y postsToBePersisted mediante el uso de la función load(), estas están disponibles globalmente dentro del contexto de nuestro script de inicialización.

El siguiente bloque a analizar es el de la constante apiDatabases donde, además de los campos dbName y dbUsers que ya vimos en la configuración de testing, en este caso el array dbData es un poco más complejo.

Cada objeto declarado dentro del array dbData define el nombre de la colección así como el conjunto de datos que debe ser almacenado en dicha colección.

Ahora nos encontramos con la definición de la constante collections. Es la definición de un mapa de funciones el cual contiene las acciones que se deben ejecutar por cada colección definida en el bloque apiDatabases.dbData.

Como podemos ver, en estas funciones estamos invocando directamente instrucciones nativas de MongoDB.

La siguiente función que nos encontramos es createDatabaseUsers la cual no tiene diferencias con la que definimos para el entorno de testing.

Justo antes de terminar el archivo, encontramos la función populateDatabase.

En esta función es donde vamos a través de las colecciones de bases de datos, insertando los datos asignados y aquí es donde invocamos al mapa de funciones collections.

Finalmente tenemos el bloque try/catch donde ejecutamos las mismas acciones que para el entorno testing pero hemos incluido la llamada a la función populateDatabase.

De esta manera es como hemos podido configurar el script de inicialización para nuestra base de datos del entorno de desarrollo.

🧩 Comando de Docker Compose

Una vez que hemos definido el archivo de composición así como el conjunto de datos que inicializará nuestra base de datos, tenemos que definir los campos mediante los cuales, operaremos nuestros contenedores.

🔥 Hay que prestar especial atención al hecho de que las rutas empleadas están referenciadas a la raíz de nuestro proyecto. 🔥

🌟 Configurando los últimos detalles para NodeJS

El último paso es definir los scripts necesarios dentro de nuestro archivo package.json.

Para proporcionar una mejor modularización de los scripts, es muy recomendable que se dividan en diferentes scripts atómicos y luego, crear otros scripts diferentes para agrupar aquellos que sean más específicos.

Por ejemplo, en este código hemos definido los scripts dev_infra:up, dev_infra:down, test:run, test_infra:up and test_infra:down que son atómicos porque definen una acción simple y serán los encargados de arrancar y para los contenedores para cada entorno, así como de ejecutar la suite de test.

Por el contrario tenemos los scripts build:dev y test que son compuestos ya que cada uno involucra varios scripts atómicos.

🤔 FAQ

❓ ¿Qué pasa si la suite de testing se para repentinamente porque alguno de los tests ha fallado?

No hay que preocuparse por esto porque es verdad que la infraestructura de testing continuará ejecutándose pero tenemos dos opciones:

Mantener en ejecución el contenedor ya que la próxima vez que ejecutemos la suite de tests, el comando docker-compose actualizará el contenido del contenedor.
Ejecutar manualmente el script de apagado del contenedor de testing.

❓ ¿Qué sucede si en lugar de una base de datos, necesitamos ejecutar algún servicio más complejo como una API?

Sólo necesitamos configurar los contenedores/servicios necesarios dentro del archivo docker-compose.yml, prestando especial atención a la configuración .env para cada entorno.

No importa lo que queramos incluir en nuestros contenedores. Lo importante aquí es que vamos a ser capaces de arrancarlos y detenerlos cuando nuestro proyecto lo necesite.

👋 Conclusiones finales

Con esta configuración podemos incluir la gestión de la infraestructura necesaria para nuestros proyectos con NodeJS.

Este tipo de configuraciones nos proporciona un nivel de desacoplamiento que aumenta nuestra independencia durante la fase de desarrollo, ya que vamos a tratar elementos externos a nuestro código como una caja negra con la cual interactuar.

Otro punto interesante de esta estrategia es que cada vez que arrancamos el contenedor mediante el comando docker-compose, éste es totalmente renovado lo que nos permite asegurar que nuestras suites de tests van a ejecutarse sobre sistemas completamente limpios.

Además, mantendremos limpio nuestro propio sistema ya que no necesitaremos instalar ningún tipo de aplicación auxiliar porque todas ellas, estarán incluidas en diferentes contenedores que compondrán nuestras infraestructura de pruebas.

Sólo una advertencia a este respecto, trata de mantener el contenido de dichos contenedores lo más actualizado posible para, de ese modo, hacer las pruebas contra un entorno lo más parecido posible al que podemos encontrarnos en producción.

Espero que este contenido te sea útil. Si tienes cualquier pregunta, siéntete totalmente libre de contactar conmigo. Aquí están mis perfiles de Twitter, LinkedIn y Github.

🙏 Reconocimientos y agradecimientos

Jonatan Ramos por darme la pista del COMPOSE_PROJECT_NAME para crear archivos docker-compose.yml único que se comparten entre diferentes entornos.

Mocking our development and testing infrastructures with Docker

Dailos Rafael Díaz Lara — Mon, 28 Dec 2020 16:39:18 +0000

🇪🇸 Versión en español

🎯 Context

When we are creating a new application or feature, we usually need to send requests to independent resources such as databases or mocked services, but it's obvious that running these kind of actions against deployed servers have a cost.

On these kind of situations is where the isolation of systems provided by Docker containers becomes really useful.

In this post we are going to see how to use Docker for getting up the minimum infrastructure which allows us to run the development and/or testing tasks... locally.

The main target of this text is to show how to user a single docker-compose.yml file for both environments, using different .env files to customize the specific container for every one, development and testing.

In addition, we will focus on how to start up the new container for testing purposes, execute the tests and then, shut down the container.

💻 System configuration

If we are going to be talking about Docker, it's obvious that we need to have it already installed in our system. If you don't have it yet, you can follow the official documentation instruction for your specific operative system.

Another element that we are going to need is docker-compose. Once again, if you have not installed it yet, you can follow the official documentation.

Finally, due to this example is aimed to applications development based on JavaScript/TypeScript, we need to have installed NodeJS (official documentation).

🏗 Project initialization

🔥 If you have already started your NodeJS project, you can skip this section 🔥

We are going to initialize our NodeJS project opening a CLI, in the folder where we want to work, and typing the next command:

npm init -y

This action will create a single package.json file in the root of our project, with the next content:

Now we can install Jest running the next command in our CLI, in order to include this library in the project:

npm i -D jest

The next step is to create the most basic folder structure for the project.

/
|-- /docker # <= New subfolder.
|-- /node_modules
|-- /src # <= New subfolder.
|-- package-lock.json
|-- package.json

🐳 Setting up the Docker configuration

We are going to have two main environments (development and test) and the main idea is to have a single docker-compose.yml file in order to manage both environment containers.

📄 `docker-compose.yml` file definition

In order to reach that goal, inside the /docker folder we are going to create our single docker-compose.yml file which will contains the next code:

As we can see, there are several lines marked as coupling smell. It means that, with the current configuration, we can only run a single Docker container mainly aimed for development tasks. So we are strongly coupled to this environment.

Wouldn't it be fine whether we were able to replace those hardcoded configurations by references and that those references are defined by any kind of configuration file?

⚙ `.env` files for Docker containers

Yes!!! We can use .env files in the same way we do that for our applications, but for configuring Docker containers.

First at all, we need to edit the docker-compose.yml file we created recently in order to use curly-braces templates to define the constant names which will be replaced with the value defined in our .env files. This way, the docker-compose.yml file content will be defined this way:

As we can see, we have replaced the hardcoded values by ${CONSTANT_NAME} references. The name typed between curly braces will be the name of the values defined into our .env files. This way, when we run the docker-compose command, using some special CLI options that we will see later, the .env file content will be replaced into our docker-compose.yml file before creating the Docker container.

Now it's time to define our environments so we are edit the /docker folder content this way:

/
|-- /docker
|   |-- /dev
|   |   |-- .docker.dev.env
|   |-- /test
|   |   |-- .docker.test.env
|   |-- docker-compose.yml
|-- /node_modules
|-- /src
|-- package-lock.json
|-- package.json

For every environment, we have created a single subfolder: dev and test.

Into every environment subfolder we have created a specific .env file: .docker.dev.env and .docker.test.env.

🙋❓ Could it be possible just naming the environment files as .env?

Yes, it could and besides, there wouldn't be any issue with it but... a so descriptive file name is a kindly help for us as developers. Due to in the same project it's really likely there are multiple configuration files, it's useful to be able to differentiate between then when we have several ones open, at the same time, in the code editor. That is the reason why the .env files have a so descriptive names.

Now it's time to define the content of our environment files this way:

and...

There are four properties which you must pay attention in order to differentiate both files:

CONTAINER_NAME
EXTERNAL_PORT
VOLUME_NAME
CONFIGURATION_PATH

The CONTAINER_NAME property will define the name that we will see after the container is created and we run the command docker ps -a in order to list the whole containers in our system.

EXTERNAL_PORT is a really sensitive property due to it will define the connection port published by the container through which our application will connect with it. It's really important to be careful with this parameter because some times we will want to run the testing suite at the same time we have up the application in development mode, so if we define the same port for both containers, the system will throw an error because the selected port is already in use.

The VOLUME_NAME property will define the data storage name in our system.

Finally, in case we have defined any kind of data to prepopulate the database before using it, the CONFIGURATION_PATH property will allow us to define where that set of data is located.

🙋‍♀️❓ Hey but, what about the COMPOSE_PROJECT_NAME property?

That's a great question.

Our main goal is to create a specific container per environment, based on the same docker-compose.yml file.

Right now, if we run our docker-compose for development, for instance, we will create the container with that environment definition and the docker-compose.yml file will be bound with that container.

This way, if we try to run the same file but setting the testing configuration, the final result will be an update of the previous development container, without the defined testing configuration. Why? Because the compose file is bound to the first started container.

In order to reach our target successfully, we use the COMPOSE_PROJECT_NAME property into every .env file and we set a different value depending on the environment.

This way, every time we run the compose file, due to the project name is different for every .env file, the modifications will only affect to the containers bound with every project name.

🙋❓ That's fine but we are using COMPOSE_PROJECT_NAME only into our .env files and not in the docker-compose.yml one. How is possible that it affect to the final result?

It's possible because that property is read directly by docker-compose command and it's not needed to be included into the docker-compose.yml file.

In this link you have the whole official documentation about COMPOSE_PROJECT_NAME.

🤹‍♂️ Populating the database

🔥 Caveat: The next explained process is aimed to populate a MongoDB database. If you want to use a different engine, you have to adapt this process and the docker-compose.yml configuration for it. 🔥

The most basic concept we must know, if we already don't, is that when a MongoDB based on container starts first time, the whole files with extension .sh or .js located into the container folder /docker-entrypoint-initdb.d are executed.

This situation provides us a way to initialize our database.

If you want to get deeper about it, you can find the whole information about it in this link of the MongoDB Docker image documentation.

🧪 Testing environment configuration

In order to see how we can do that, we are going to start by the testing environment so first at all, we have to create the next file structure into the /docker/test folder of our project:

/
|-- /docker
|   |-- /dev
|   |   |-- .docker.dev.env
|   |-- /test
|   |   |-- /configureDatabase # <= New subfolder and file.
|   |   |   |-- initDatabase.js
|   |   |-- .docker.test.env
|   |-- docker-compose.yml
|-- /node_modules
|-- /src
|-- package-lock.json
|-- package.json

The content of the initDatabase.js file will be the next one:

This script is divided in three different elements.

The apiDatabases constant contains the whole databases definitions that we want to create for this container.

Every database definition will contain its name (dbName), an array of users (dbUsers) whose will be allowed to operate with the database (including their accessing privilege definitions) and the dataset which we will populate the database.

The createDatabaseUser function is focused on handle the information contained into every apiDatabases block, process the users data and create them into the specified database.

Finally the try/catch block contains the magic because in this block we iterate over the apiDatabases constant, switch between databases and process the information.

Once we have checked this code, if we remember our docker-compose.yml file content, into the volumes section we defined the next line:

- ${CONFIGURATION_PATH}:/docker-entrypoint-initdb.d:rw

In addition, for the testing environment, into the .docker.test.env file we set this configuration:

CONFIGURATION_PATH="./test/configureDatabase"

With this action, the docker-compose process is copying the content of the path defined by CONFIGURATION_PATH into the container /docker-entrypoint-initdb.d:rw before it's run first time. So we are setting our database configuration script to be executed in the container start up.

🙋‍♀️❓ For this configuration you are not setting any initial data. Why?

Because it will be the testing database so the intention is to persist and remove data ad-hoc based on the tests that are running in a specific moment. By this reason, it has not sense to populate this database with mocked information once we are going to create/edit/delete it dynamically.

🛠 Development environment configuration

This configuration is pretty similar to the testing one.

First at all, we have to modify the /docker/dev subfolder content in our project, in order to get this result:

/
|-- /docker
|   |-- /dev
|   |   |-- /configureDatabase # <= New subfolder and files.
|   |   |   |-- initDatabase.js
|   |   |   |-- postsDataToBePersisted.js
|   |   |   |-- usersDataToBePersisted.js
|   |   |-- .docker.dev.env
|   |-- /test
|   |   |-- /configureDatabase
|   |   |   |-- initDatabase.js
|   |   |-- .docker.test.env
|   |-- docker-compose.yml
|-- /node_modules
|-- /src
|-- package-lock.json
|-- package.json

The postsDataToBePersisted.js and usersDataToBePersisted.js files only contain static data defined into independent constants. That information will be stored in the defined database, into the specified collection.

The structure for the content included into these files is like that:

In the other hand, the content of initDatabase.js file is pretty similar to the testing environment definition but a little bit complex due to we have to manage collections and data. So the final result is this one:

At this script there are several parts that we need to analyze.

The header block composed by two load() function calls which are used in order to import the mocked data constants declarations that we did in the other JavaScript files.

🔥 Pay attention to the full data location path is referenced to the inner Docker container file structure, not to our system. 🔥

ℹ️ If you want to learn more about how MongoDB executes JavaScript files in its console, take a look to the official documentation.

After "importing" the usersToBePersisted and postsToBePersisted constants definitions via load() function, they are globally available into the context of our initialization script.

The next block to be analyzed is the apiDatabases constant definition where besides the dbName and dbUsers that we covered in the testing configuration, in this case the dbData array is a little bit more complex.

Every object declared into the dbData array defines the collection name as well as the dataset that must be persisted in that collection.

Now we find the collections constant definition. It's a set of mapped functions (or object lookup) which contains the actions to execute for every collection defined into the apiDatabases.dbData block.

As we can see, in these functions we are directly invoking native MongoDB instructions.

The next function is createDatabaseUsers which has not differences with the defined for the testing environment.

Just before ending the script file we can find the populateDatabase function.

In this function we go through the database collections inserting the assigned data and here is where we invoke the collections mapped functions object.

Finally we have the try/catch block where we run the same actions that we did for the testing environment but we have included the populateDatabase function call.

This way is how we can configure the initialization script for our development environment database.

🧩 Docker Compose commands

Once we have defined the composing file as well as the dataset that will initialize our databases, we have to define the commands which will run our containers.

🔥 Pay attention to the used paths are referenced to our project root. 🔥

🌟 Setting the final NodeJS commands

The final step is to define the needed scripts into our package.json file.

In order to provide a better modularization of scripts, it's strongly recommended to divide the different scripts in atomic ones and then, create new ones which group the more specific ones.

For instance, in this code we have defined the dev_infra:up, dev_infra:down, test:run, test_infra:up and test_infra:down scripts which are atomic because define a single action to do and will be in charge to start and turning off the containers for every environment as well as to run the testing suite.

In opposite we have the build:dev and test scripts which are composed due to they include several atomic actions.

🤔 FAQ

❓ What happen if the testing suite suddenly stops because any test fails?

Don't worry about that because it's true that the testing infrastructure will keep running but we have two options:

To keep it running so the next time we run the testing suite, the docker-compose command will update the current container.
To run manually the shutting down script for the testing container.

❓ What happen whether instead of a database we need to run a more complex service like an API?

We just need to configure the needed containers/services into the docker-compose.yml file, paying special attention to the .env configurations for every environment.

It doesn't matter what we wrap and/or include in our container/s. The important point here is that we are going to be able to start and turning off them when our project needs it.

👋 Final words

With this configuration, we can include infrastructure management to our NodeJS based on project.

This kind of configuration provides us a decoupling level that will increase our independency during the development period, because we are going to treat the external elements to our code as a black box which we interact.

Another interesting point for this strategy is that every time we start up the container via docker-compose, it's totally renewed so we can be sure that our testing suites are going to be run in a completely clean system.

In addition, we will keep clean our system due to we don't need to install any auxiliar application on it because all of them will be included into the different containers that compose our mocked infrastructure.

Just a caveat, try to keep the content of the containers up-to-date in order to work with the closest production environment conditions as it's possible.

I hope this tip is useful for you. If you have any question, feel free to contact me. Here there are my Twitter, LinkedIn and Github profiles.

🙏 Credits and thanks

Jonatan Ramos for providing the clue of COMPOSE_PROJECT_NAME to create a single docker-compose.yml file shared between different environments.

De if/switch a mapped functions (a.k.a. object lookup)

Dailos Rafael Díaz Lara — Mon, 14 Dec 2020 22:12:23 +0000

🇬🇧 English version

🎯 Objetivo

Este texto está orientado a proporcionar una alternativa para aquellas situaciones donde nuestro código debe estructurarse para ejecutar una u otra función, dependiendo de un conjunto definido de posibles condiciones.

En ningún momento es mi intención criticar el uso de if/else o de switch/case. Mi único objetivo es proporcionar una propuesta diferente con que mejorar el mantenimiento y la escalabilidad de nuestro código.

Una vez dicho esto... empecemos!!!

📚 Instrucción if/else

Desde que empezamos a aprender a programar, el primer control de flujo de información que aprendemos es el if/else (MDN if/else documentation). De este modo, cuando ya lo hemos aprendido, es realmente fácil utilizarlo.

Incluso cuando la cantidad de posibles opciones se incrementa, podemos encadenar multiples if/else.

Además, cuando tenemos varias opciones que deben tratarse de la misma manera, es decir que comparten la misma lógica de negocio, podemos usar operadores booleanos (el OR en este caso), para agrupar todas esas opciones bajo el mismo bloque de código.

Todo esto está genial pero cuando los posibles casos superan las dos o tres opciones, el código empieza a parece un poco sucio.

Pros (✅) y contras (👎)

✅ Es la manera más fácil de controlar el flujo de información.
✅ Es relativamente fácil de aprender.
✅ discriminar entre dos posibles opciones es realmente cómodo.

👎 Cuando gestionamos más de tres opciones, el código empieza a parece un poco sucio..
👎 Encadenar múltiples opciones disminuye la legibilidad y el mantenimiento de nuestro código.
👎 Agrupar opciones empleando operadores booleanos puede hacer más complicadas las reglas de comparación en cada situación.
👎 Para una cantidad relativamente grande de casos posibles, es más lento ya que cada condición deber ser comprobada hasta alcanzar aquella que coincida con el valor de referencia proporcionado.

🤓 Instrucción switch/case

Cuando queremos mejorar la legibilidad y mantenimiento de nuestro código debido a que tenemos múltiples opciones que gestionar, es cuando aprendemos la alternativa al if/else, es decir, el switch/case (MDN switch/case documentation).

De la misma manera que hacíamos con el if/else, con el switch/case también podremos agrupar opciones pero en este caso, no necesitamos utilizar ningún operador booleano. Sólo necesitamos mantener unidos los diferentes casos a agrupar.

Como ya sabrás, esto es posible gracias a que la ejecución del switch/case es un proceso secuencial, donde cada posible caso definido en el conjunto de opciones, es comparado con la referencia proporcionada.

Si ambos valores coincide, el bloque de código incluido en ese caso se ejecuta y, si no hay una instrucción break o return al final de dicho bloque de código, el siguiente caso será comprobado hasta encontrar la próxima coincidencia o hasta llegar al bloque default.

Basándonos en esto, para agrupar múltiples opciones las cuales van a ser gestionadas por el mismo bloque de código, sólo necesitamos definir el caso para el valor deseado, sin ningún tipo de lógica de negocio. De este modo seremos capaces de encadenar múltiples opciones para el mismo resultado.

Pros (✅) y contras (👎)

✅ Proporciona una mejor estructura del código que al usar instrucciones if/else.
✅ Es posible crear agrupamiento de casos de una manera más clara que con instrucciones if/else.
✅ Es realmente sencillo discriminar entre más de dos opciones.

👎 Tenemos que estar pendiente de completar todos los bloques de código con una instrucción break o return. Si nos olvidamos de hacerlo, nos podemos meter en un buen lío.
👎 Para cantidades relativamente grandes de casos, es lento dado que cada condición debe ser comprobada hasta llegar a aquella que coincide con la referencia que le hemos proporcionado.

🔥 Mapped functions

Esta es una estrategia poco conocida (también llamada object lookup) y está destinada a mejorar determinados aspectos del uso de instrucciones if/else y switch/case.

La idea es aprovechar el comportamiento de los objetos de JavaScript para usar sus claves como mapa de referencias y acceder directamente a lógica de negocio específica.

Antes de nada, necesitamos tener definidos los posibles casos que van a ser gestionados.

Cada caso individual será asociado a una clave del objeto literal.

Una vez hemos creado nuestro objeto, usaremos el estilo de acceso array para ejecutar el código de cada caso individual.

Pros (✅) y contras (👎)

✅ Proporciona una estructuración del código mejor que la que obtenemos al usar instrucciones if/else y switch/case.
✅ No hay agrupamiento de posibles casos dado que cada uno de ellos tiene definida su propia lógica de negocio.
✅ Es extremadamente fácil diferenciar entre múltiples opciones de ejecución.
✅ Puede ser reutilizado en varias partes de nuestra aplicación (via exportación de módulo).
✅ Es más rápido que if/else y switch/case dado que accedemos a la condición específica que queremos ejecutar, sin necesitar verificar cada uno de los casos secuencialmente, hasta encontrar el correcto.

👎 Esta estrategia rara vez aparece en las formaciones más habituales.
👎 Si el objeto no se define en el lugar indicado de la aplicación, puede consumir un poco más de memoria de la necesaria.

🤔 FAQ

❓ ¿Qué sucede si proporcionamos una opción que no están entre las claves del objeto?

La respuesta corta es que se disparará una excepción ya que no es posible ejecutar una función de undefined.

No obstante, podemos prevenir esto definiendo un caso default, de la misma manera que hacemos en la instrucción switch/case.

Para ser capaces de acceder a este nuevo caso, comprobaremos si la opción proporcionada existe dentro del objeto y si no existe, entonces ejecutaremos la opción default.

Para estos casos, operador condicional (ternario) será nuestro aliado.

❓ ¿Qué puedo o debo devolver en el caso `default`?

Esto va a depender del caso de uso que estemos definiendo pero básicamente, vamos a tener tres opciones principales:

1 - Devolver el mismo valor que hemos proporcionado:

2 - Devolver null o undefined:

En este caso, podemos incluso aprovechar el optional chaining y dejar más limpio nuestro código:

Debemos prestar atención porque in este caso, si no hay coincidencia en las opciones disponibles, vamos a devolver undefined.

3 - Definir una lógica de negocio específica:

Aquí debemos tener cuidado si nuestro código, como se muestra en el ejemplo, va a disparar un error. Tenemos que gestionar dicho error para evitar un error total que bloquee nuestra aplicación.

Obviamente el código que implementa el error puede ser reemplazado por cualquier otra lógica de negocio que se adecue mejor al comportamiento de nuestra aplicación.

❓ ¿Necesito definir una función anónima para cada caso?

No, en absoluto.

Si tenemos perfectamente definida la función que debe ser ejecutada para cada caso y además, dicha función recibe únicamente un argumento que coincide con el que estamos proporcionando cuando invocamos al mapa, podemos usar esta sintaxis:

Incluso si queremos devolver undefined cuando la opción proporcionada no está incluida dentro del mapa, podemos usar esta otra sintaxis extremadamente simplificada (Advertencia ‼️: todas las funciones usadas para crear las claves del mapa, han de estar definidas previamente):

❓ ¿Es posible que el nombre de una propiedad entre en conflicto con el de un objeto?

Rotundamente sí.

Es totalmente posible, pero para evitar esto tenemos que prestar atención a los nombres que estamos usando, de la misma manera que nunca utilizaríamos una palabra reservada del lenguaje como nombre de variable, función u objeto.

❓ ¿Esto podría formar una nueva convención de nombres?

Sí, claro.

Pero para este tipo de situaciones tenemos el apoyo y las guías proporcionadas por el Clean Code.

Cada código que creemos requerirá una convención de nombres. En algunos casos cuando seamos la única persona que ha iniciado el proyecto, podremos definir dicha convención (pet-projects principalmente). En otras situaciones, será el equipo de desarrollo el responsable de cualquier acuerdo alcanzado a tal efecto.

❓ ¿Requerirá un uso de memoria adicional mientras que el `if/else` y el `switch/case` no lo hacen?

Sí, lo hará.

Sin embargo, basándonos en los tipos de dispositivos que ejecutan nuestras aplicaciones JavaScript hoy en día así como en sus características, el incremento de memoria es prácticamente insignificante en comparación con el resto de la aplicación.

❓ ¿Sería esta opción más lenta que el `if/else` o el `switch/case` dependiendo del motor de JavaScript que se use?

Esto va a depender de cómo definamos el objeto en sí.

Por ejemplo, si definimos el objeto de mapeado de funciones dentro de una función, la cual va a ser invocada cada vez que queramos hacer uso del mapa, obviamente esta solución va a ser más lenta que las otras opciones, porque el objeto debe ser creado cada vez.

En este código podemos ver la situación donde la función mappedFunction tiene definido el objeto dentro de ella:

Codepen 👉 Speed race Switch 🐇 vs Object Lookup 🐢 v1

Aquí no importa qué motor de JavaScript estemos usando para ejecutar el código (AppleWebKit para Safari, SpiderMonkey para Firefox o V8 para Google Chrome y/o NodeJS), porque el mapeado de funciones será siempre más lento (incluso si operamos los primeros casos), debido a que el objeto se está creando ad-hoc en cada ejecución de la función.

Sin embargo, si definimos el mapeado de funciones de manera global (al módulo o a la aplicación), el objeto se cargará cuando el módulo o la aplicación lo usen. De este modo, el acceso a las funciones mapeadas será siempre más rápido que las otras dos opciones.

En este código hemos definido el mapa fuera de la función mappedFunction:

Codepen 👉 Speed race Switch 🐢 vs Object Lookup 🐇 v2

❓ ¿Qué pasa con el recolector de basura?

Hoy en día el recolector de basura es algo a lo que quienes desarrollamos con JavaScript no le prestamos mucha atención, debido a que está ampliamente cubierto por las especificaciones del lenguaje así que, una vez el mapa de funciones ya no está en uso en el proceso de ejecución actual, el objeto será gestionado por el recolector de basura automáticamente.

Para más información respecto a este tema, recomiendo echar un vistazo a esta documentación de la MDN relativa a la gestión de la memoria.

Recursos adicionales:

Garbage collection por javascript.info (2020)

👋 Conclusiones finales

Como ya he dicho al principio de este post, no es mi intención criticar de ningún modo el uso de if/else o switch/case, sino que únicamente pretendo proporcionar otra manera de realizar dichas operaciones.

Resumiendo, cuando tengamos que discriminar entre dos simples opciones, es obvio que la alternativa más sencilla es usar if/else. Además recomiendo encarecidamente que intentes usar el operador ternario allí donde sea posible.

Para aquellos casos donde tengamos que diferenciar entre tres o más opciones, sinceramente recomiendo el uso de funciones mapeadas para proporcionar una mejor legibilidad, mantenimiento y reutilización de nuestro código.

Espero que este contenido te sea útil. Si tienes cualquier pregunta, siéntete totalmente libre de contactar conmigo. Aquí están mis perfiles de Twitter, Linkedin y Github.

🙏 Reconocimientos y agradecimientos

A Lissette Luis, Adrián Ferrera e Iván Bacallado por formar parte de un equipo fantástico donde se comparte el conocimiento y especialmente, por sus propuestas sobre el tema abordado en este texto.
A Simon Høiberg por iniciar este interesantísimo hilo de Twitter que ha originado la creación de este post.
A Kenan Yildiz y Thomas Luzat por compartir una opción más simplificada de la implementación del mapa de funciones.

From if/switch to mapped functions (a.k.a. object lookup)

Dailos Rafael Díaz Lara — Mon, 14 Dec 2020 13:53:43 +0000

🇪🇸 Versión en español

🎯 Context

This text is aimed to provide an alternative to these situations where our code must be structured in order to run one or another function, depending on a bunch of possible conditions.

I don't want to criticize the use of if/else or switch/case sentences far from it. My only goal is to provide a different approach which can improve the maintenance and scalability of our code.

So... engage!!!

📚 if/else sentences

Since all of us start learning to code, the first flow control sentence that we learn is the if/else one (MDN if/else documentation). So once we have got it, it's really easy to use.

Even when the amount of possible options increases, we can chain multiple if/else.

In addition, when we have several options which must be treated in the same way (it means with the same business logic), we can use boolean operators (the OR one in this case), in order to group all these options under the same block.

That's fine but when the possible cases are upper than two or three options, the code starts to look like a little bit messy.

Pros (✅) and cons (👎)

✅ It's the easier way to control data flow.
✅ It's relatively easy to learn.
✅ It's really comfortable to discriminate between two options.

👎 For handling more than three options, the code starts to look like a little bit messy.
👎 To chain multiple options reduce the readability and maintenance of our code.
👎 To group options using boolean operators could turn on complex assertion rules for every situation.
👎 For a relatively huge amount of cases, it's slow due to every condition must be checked until getting the only one that matches.

🤓 switch/case sentence

When we want to improve the readability and maintenance of our code due to we have multiple options to be handled, is when we learn the if/else alternative, it means, the switch/case sentence (MDN switch/case documentation).

In the same way we did with the if/else sentence, with switch/case we can also group options but now, we don't need to use any boolean operator. We just need to keep joined the different cases.

As you already know, that's possible due to the switch/case execution is a sequential process, where every possible case defined in the block of options, is compared with the provided value.

If both values match, the code block included into that case is executed and, if there is not a break or return instruction at the end of the code block, the next case will be checked until the next matching or the default option is reached.

Based on that, in order to group several options which are going to be handled by the same code block, we just need to define the case for the wished value, with no business logic. This way we're able to chain multiple options for the same result.

Pros (✅) and cons (👎)

✅ It provides a better code structuring than if/else sentences.
✅ It's possible to create clearest cases grouping than if/else sentences.
✅ It's really easy to discriminate between more than two options.

👎 You have to be aware about completing all your code blocks with a break or a return instruction. If you forget it, you'll have a real nightmare.
👎 For a relatively huge amount of cases, it's slow due to every condition must be checked until getting the only one that matches.

🔥 Mapped functions

This is a little known strategy (a.k.a. object lookup) aimed to improve several aspects of if/else and switch/case sentences.

The idea is to take advantage of a JavaScript object behavior in order to use its keys as map references to access to specific business logic.

First at all, we need to have defined the possible cases which must be handled.

Every single case will be bound to a key in the literal object.

Once we have created our object, we'll use array-access style to run the code for every single case.

Pros (✅) and cons (👎)

✅ It provides a better code structuring than if/else and switch/case sentences.
✅ There is no cases grouping due to every single case has its own business logic.
✅ It's extremely easy to differentiate between multiple options.
✅ Can be reused in several parts of our application (via module export).
✅ It's faster than if/else and switch/case due to we access to the specific condition without need to check every defined case sequentially until the correct one is located.

👎 This strategy rarely appears in common trainings.
👎 If the object is not defined in the right place, it can consume a little bit more memory that it really needs.

🤔 FAQ

❓ What happen if the provided option is not defined as object key?

The short answer is that an exception will be throw due to it's not possible to run a function from undefined.

However, we can prevent it defining a default case, in the same way we do in switch/case sentences.

In order to be able to access this new case, we will check if the provided one already exists into the object and if it doesn't, we run the default option.

For these cases, the conditional (ternary) operator will be our allied.

❓ What can/must I return in the `default` case?

It'll depend on the use case we are defining but basically, we have three main options:

1 - To return the same value that you have provided:

2 - To return null or undefined:

In this case, we can even take advantage of the optional chaining and clean up the code this way:

We have to pay attention because in this last case, if there are no matching options, we are going to be returning undefined.

3 - To define a specific business logic:

We must be careful if our code, like in this example, is going to throw an error. We need to handle it in order to avoid a full blocking error.

Obviously the code that implements the error can be replaced for any other business logic which suites better with our application behavior.

❓ Do I need to define an anonymous function for every case?

No, you don't.

If we have perfectly defined the function that must be run for every case and in addition, that function receives only a single argument which matches with the provided one when you invoke the map, we can use this syntax:

Even if we want to return undefined when the provided option is not included into the map, we can use this extremely simplified syntax (Caveat ‼️: the whole functions used in order to create the mapped object keys must be defined previously):

❓ It could be possible that property name clashes with an object one?

Absolutely yes.

It's possible at all, but in order to avoid that we have to pay attention what names are we using, in the same way we never use a language reserved word as variable, function or object name.

❓ It could force a naming convention?

Yes, it could.

But for these situation we have the support and guidances of Clean Code.

Every code we create requires naming convention. Some cases when we are the only person who has started the project, we can define that convention (pet-projects mainly). In other situations, the development team will be the responsible of any agreement about that.

❓ Is it going to require additional memory meanwhile `if/else` and `switch/case` does not do it?

Yes, it will.

However, based on the kind of devices that run our JavaScript applications nowadays and its characteristics, the increment of used memory is insignificant compared with the rest of the application.

❓ Should it be slower that `if/else` or `switch/case` depending on the JavaScript engine?

It depends on where we define the object.

For instance, if we define the mapped functions object into a function which is going to be called every time we want to use the map, obviously this solution is going to be slower that the other options because the object must be created every time.

In this code we can see that situation where the mappedFunction has defined the object lookup inside:

Codepen 👉 Speed race Switch 🐇 vs Object Lookup 🐢 v1

It doesn't matter which JavaScript engine you use to run this code (AppleWebKit for Safari, SpiderMonkey for Firefox or V8 for Google Chrome and/or NodeJS), because the mapped function will be always slower (even with the first cases) due to the object is created ad-hoc for every function run.

Nevertheless, if we define the mapped functions globally (to the module or to the application), the object will be loaded just once when the module or the application is used so, this way, the mapped function access is always faster than the other two options.

In this another code we have defined the object lookup outside the mappedFunction:

Codepen 👉 Speed race Switch 🐢 vs Object Lookup 🐇 v2

❓ What about the garbage collector?

Nowadays the garbage collector is something that the JavaScript developers don't pay too much attention due to it's widely covered by the language specifications so, once the mapped functions object is not used any more by the current runtime, it will be managed by the garbage collector automatically.

For further information about that, I recommend you to take a look to this documentation of the MDN about memory management.

Additional resources:

Garbage collection by javascript.info (2020)

👋 Final words

As I said at the beginning of this post, it's not my intention to criticize the use of if/else or switch/case, but I only want to provide another way to do these operations.

Summarizing, when we've to discriminate between two single options, it's obvious that the easier alternative is to use if/else sentence. Moreover I strongly recommend you to try to use the ternary operator when it's possible.

For cases where you have to differentiate between three or more options, I sincerely recommend you to use mapped functions in order to provide a better readability, maintenance and code reuse.

I hope this tip is useful for you. If you have any question, feel free to contact me. Here there are my Twitter, Linkedin and Github profiles.

🙏 Credits and thanks

Lissette Luis, Adrián Ferrera and Iván Bacallado for being part of an awesome knowledge sharing team and specially, for their proposals about the subject covered on this post.
Simon Høiberg for starting this interesting Twitter thread that originated the creation of this post.
Kenan Yildiz and Thomas Luzat for sharing a shorter way to implement the object lookup.

Jest with global Dotenv configuration

Dailos Rafael Díaz Lara — Sat, 01 Aug 2020 18:44:34 +0000

🎯 Target

I want to have several .env files in order to define different conditions depending on the environment where my code is running. Based on that, in my testing process I want to load a global configuration once for the whole testing suites.

😅 Overview

There are some options to load environment variables in my tests, using Dotenv.

node -r dotenv/config node_modules/.bin/jest

That is one of the most usual approaches but I don't like it because this way, Dotenv literally needs a .env file defined at the root of the project so I cannot set a custom configuration file.
require(dotenv).config({ path: 'path/to/env_file' });

This option requires to type this command in every testing file where I'm going to use environment variables. It could be a solution but I don't like it at all because I have to pay attention to the relative path for the environment file location in every testing file.
setupFiles Jest configuration property.

That is fine but as the official documentation suggests, the environment is processed once per testing file. This conditions will dealy a little my tests execution and in addition, I don't want it. I want a global configuration at the very begining of the testing process.

😎 My best matching

After diving a little in the Jest documentation, I found this configuration property: globalSetup.

In order to use this property, I created the dotenv-test.js file into dotenv folder (located at the root of the project).

// dotenv-test.js file content.

const path = require('path');
const dotenv = require('dotenv');

module.exports = async () => {
    dotenv.config({ path: path.resolve(__dirname, '../env/.env.test') });
};

Following the property documentation guidelines, this file must export an asynchronous function that will be executed before the whole testing files.

When the testing framework runs at the first time, this file is executed, loading the selected environment variables and setting them globally, for the whole testing files and just once. That's all.

Finally, I have just to introduce this property into the Jest configuration file (jest.config.json) and provide the location of the Dotenv file.

{
    ...
    "globalSetup": "<rootDir>/dotenv/dotenv-test.js",
    ...
}

👋 Final words

I hope this tip is useful for you. If you have any question, feel free to contact me. Here there are my Twitter, Linkedin and Github profiles.

💾 Resources

Example code repository https://github.com/ddialar/testing.jest.global.dotenv
Jest configuration docs https://jestjs.io/docs/en/configuration.html

DEV Community: Dailos Rafael Díaz Lara

AI - Foundations and best practices creating skills

🤓 Introduction

💻 Creating Skills

📍 Skill location

🎩 Skill header

🛢 Body of a skill (the T-I-P-O pattern)

🗃 More complex skills

🧐 Good (✅) and bad (❌) practices to follow when defining a skill

At the header level

At the body level

At the level of robustness, error handling, and scalability

👋 Final conclusions

🙏 Acknowledgments

IA - Fundamentos y buenas prácticas en la creación de Skills

🤓 Introducción

💻 Creación de Skills

📍 Ubicación de las skills

🎩 Encabezado de una skill

🛢 Cuerpo de una skill (patrón T-I-P-O)

🗃 Skills más complejas

🧐 Buenas (✅) y malas (❌) prácticas a seguir a la hora de definir una skill

A nivel de cabecera

A nivel de cuerpo

A nivel de robustez, manejo de errores y escalabilidad

👋 Conclusiones finales

🙏 Reconocimientos y agradecimientos

Definiendo nuestras infraestructuras para desarrollo y testing con Docker

🎯 Objetivo

💻 Configuración del sistema

🏗 Inicialización del proyecto

🐳 Definiendo la configuración de Docker

📄 Definición del archivo docker-compose.yml

⚙ Archivos .env para contenedores Docker

🤹‍♂️ Inicializando la base de datos

🧪 Configuración del entorno de testing

🛠 Configuración del entorno de desarrollo

🧩 Comando de Docker Compose

🌟 Configurando los últimos detalles para NodeJS

🤔 FAQ

👋 Conclusiones finales

🙏 Reconocimientos y agradecimientos

Mocking our development and testing infrastructures with Docker

🎯 Context

💻 System configuration

🏗 Project initialization

🐳 Setting up the Docker configuration

📄 docker-compose.yml file definition

⚙ .env files for Docker containers

🤹‍♂️ Populating the database

🧪 Testing environment configuration

🛠 Development environment configuration

🧩 Docker Compose commands

🌟 Setting the final NodeJS commands

🤔 FAQ

👋 Final words

🙏 Credits and thanks

De if/switch a mapped functions (a.k.a. object lookup)

🎯 Objetivo

📚 Instrucción if/else

Pros (✅) y contras (👎)

🤓 Instrucción switch/case

Pros (✅) y contras (👎)

🔥 Mapped functions

Pros (✅) y contras (👎)

🤔 FAQ

❓ ¿Qué sucede si proporcionamos una opción que no están entre las claves del objeto?

❓ ¿Qué puedo o debo devolver en el caso default?

❓ ¿Necesito definir una función anónima para cada caso?

❓ ¿Es posible que el nombre de una propiedad entre en conflicto con el de un objeto?

❓ ¿Esto podría formar una nueva convención de nombres?

❓ ¿Requerirá un uso de memoria adicional mientras que el if/else y el switch/case no lo hacen?

❓ ¿Sería esta opción más lenta que el if/else o el switch/case dependiendo del motor de JavaScript que se use?

❓ ¿Qué pasa con el recolector de basura?

👋 Conclusiones finales

🙏 Reconocimientos y agradecimientos

From if/switch to mapped functions (a.k.a. object lookup)

🎯 Context

📚 if/else sentences

Pros (✅) and cons (👎)

🛢 Body of a skill (the `T-I-P-O` pattern)

🛢 Cuerpo de una skill (patrón `T-I-P-O`)

📄 Definición del archivo `docker-compose.yml`

⚙ Archivos `.env` para contenedores Docker

📄 `docker-compose.yml` file definition

⚙ `.env` files for Docker containers

❓ ¿Qué puedo o debo devolver en el caso `default`?

❓ ¿Requerirá un uso de memoria adicional mientras que el `if/else` y el `switch/case` no lo hacen?

❓ ¿Sería esta opción más lenta que el `if/else` o el `switch/case` dependiendo del motor de JavaScript que se use?

❓ What can/must I return in the `default` case?

❓ Is it going to require additional memory meanwhile `if/else` and `switch/case` does not do it?

❓ Should it be slower that `if/else` or `switch/case` depending on the JavaScript engine?