Creating Agentic Skills: Best PracticesCreating Agentic Skills: Best Practices

It seems like agentic development is converging towards skillsOpen in a new tab, and it just makes sense.

Skills are files with instructions that add new capabilities to AI agents. In these files you describe how an agent should behave, giving it extended context and information when handling a task relevant to that skill.

Let me show you in this issue how you can create robust agentic skills so you use fewer tokens and get higher quality output.

I will also share my most valuable skills to date along this newsletter issue.

#What is the purpose of skills?

If we think about humans, everyone can specialize in different fields or tools. Specialization opens the door for higher quality deliveries. As Bruce Lee once said:

“

I fear not the man who has practiced 10,000 kicks once, but I fear the man who has practiced one kick 10,000 times.

”

And as humans, we can learn skills that others have as well.

For example, I really enjoy using the bullet journal method and I know many people who do too. It's a skill that I acquired over the years, I wasn't born with it.

Different skills can be taught to others. It takes time and effort to integrate that knowledge.

The same applies to AI. Teach it once, get the behavior forever:

• No repetition. Stop pasting the same instructions every session.
• Consistency. Given the same task, you should have the same output, across teammates, across time.
• Compounding leverage. Every skill you write makes the next task cheaper.
• Token savings. A precise skill beats a long prompt.

#What does a skill look like?

Agentic skills are based on an open specification created by AnthropicOpen in a new tab, so as long as you follow this simple format, all AI agents can interact with your skills.

Skills for AI agents are nothing more than markdown files, like the following:

---
name: remember
description: Capture and persist learnings to improve future sessions.
Use when the user says "remember this", a useful pattern emerges, or a project convention is established.
---

# Remember

Capture knowledge so future sessions benefit from it.

## Workflow

1. **Capture** — extract what was learned, why it matters, and an example.
2. **Route** — decide where it belongs (CLAUDE.md, an existing skill, or a new skill).
3. **Propose** — show the user the exact change before applying.
4. **Apply** — only after approval.

## Example

User: "Always use `??` instead of `||` for nullish defaults." → Add to CLAUDE.md under TypeScript conventions.

These files are placed in a directory that your AI system of choice will pick up. Since I'm using Claude Code, I create them under ./project/.claude/skills. They have the following structure:

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

#Where to place your skills

Skills live in one of two scopes:

Project skills win when names collide, so you can override a global skill in a single repo without touching the global version. Rule of thumb: if the skill encodes a decision only this codebase has made, scope it to the project. If it travels with you, scope it globally.

I strongly believe developers will perfect their skills toolkit. I've already started.

#Meta-information for skills

Skills are invoked by the agentic system depending on the meta-information we include in the frontmatter:

• Name: short, kebab-case identifier.
• Description: what the skill does and when to trigger it.

This is why naming is extremely important. Depending on the name and description, the skill might be triggered or not.

Using Claude Code, you can also trigger a skill directly with a slash command:

/remember

#Instructions of the skill

In the body of the skill you describe what the agent should do once it's triggered.

I've also found that skills work great as living documentation for your project. So I tend to spend quite a bit of time tweaking and improving them.

#Adding more context to agent skills

You can reference additional context that should only be loaded when needed. Remember the references folder in the structure? That's where conditional documentation lives.

The way to do it is to point the agent to those files from the body of SKILL.md:

---
name: create-domain-model
description: Generate pure domain layer code. Creates entities, value objects, and domain services with no framework dependencies.
---

# Domain Model Generator

Generate pure TypeScript domain code following layer boundaries.

## Workflow

1. Read the task file under `tasks/`.
2. Decide whether you need an entity, a value object, or a domain service.
   - For entities, follow `references/entities.md`.
   - For value objects, follow `references/value-objects.md`.
   - For test data, follow `references/mother-pattern.md`.
3. Generate code under `src/features/<feature>/domain/`.
4. Run `npm run test -- domain` and verify GREEN.

The agent will only load references/value-objects.md if the task actually requires a value object. That's progressive disclosure in action. It's huge for keeping the context window clean.

#Loading behaviours

#Best practices when creating robust skills

#1. Be concise

Good:

## Create a value object

Use a private constructor + static factory:

```ts
export class Email {
  private constructor(readonly value: string) {}

  static create(value: string): Email {
    if (!value.includes('@')) throw new Error('Invalid email')
    return new Email(value)
  }
}
```

Being concise yet precise is essential. Skills interact with the context window, which is the "memory" of the AI agent. The more we fill it, the more we'll see degradation.

“

The context windowOpen in a new tab is a public good.

”

Bad. Verbose and restates known facts:

## Create a value object

Value objects are a concept that comes from Domain Driven Design. They are
immutable objects that represent a concept in your domain. There are many ways
to implement them in TypeScript, but the most common one is to use a class with
a private constructor and a static factory method. First, you'll need to make
sure your constructor is private so consumers cannot instantiate the class
directly. Then you'll need to add a static method that validates the input...

#2. Set appropriate degrees of freedom

We can let our skills have more freedom or less freedom with the task at hand. Think of it as a spectrum:

I like using high freedom when I want the agent to decide what matters and is more context-dependant:

## Review

Review the diff for clarity, naming, and SOLID violations. Suggest improvements
where they add value.

Low freedom for tasks that have (and should have) one way to do it, like bump a package version.

## Bump version

1. Run `npm version <major|minor|patch>`.
2. Run `npm run build` and verify it passes.
3. Commit with message `chore: bump to vX.Y.Z`.
4. Run `git push --follow-tags`.

#3. Use workflows for complex tasks

A step-by-step checklist keeps the agent on rails for multi-step tasks:

## Workflow

- [ ] 1. Read all source documents under `tasks/`
- [ ] 2. Identify entities and value objects
- [ ] 3. Generate domain code under `src/features/<feature>/domain/`
- [ ] 4. Run `/architecture-guardrails`
- [ ] 5. Report the diff to the user before writing

#4. Feedback loops

Providing the agent a way to validate its own work is essential when creating robust skills.

Can you guess the most effective form of validation for coding tasks? Tests. That's why if you don't have tests in your application and want to use AI, you're wasting resources.

## Validation

After generating code, run:

1. `npm run typecheck` — must pass.
2. `npm test -- <feature>` — must pass.
3. `/architecture-guardrails` — no cross-layer imports.

If any step fails, fix the cause and re-run before reporting back.

#5. Give concrete examples

Abstract templates are not as useful as if we have concrete examples to teach. Show real input mapped to real output:

## Example

**Input** — user says: "Add an Email value object."

**Output** — generate `src/features/users/domain/email.ts`:

```ts
export class Email {
  private constructor(readonly value: string) {}

  static create(value: string): Email {
    if (!value.includes('@')) throw new Error('Invalid email')
    return new Email(value)
  }
}
```

And a matching Mother under `src/features/users/domain/email.mother.ts`:

```ts
export class EmailMother {
  static valid(): Email {
    return Email.create('jane@example.com')
  }
}
```

When the agent sees this, it has a pattern to imitate instead of a description to guess from.

#6. Use an AI agent to create skills

Now that we have all this knowledge about creating skills... what if we created a skill to create or update skills? That's right. Don't worry, I went ahead and uploaded mine to my site so you can use it directly.

#Checklist for effective skills

Before sharing a skill, verify:

Core quality

• Description is specific and includes key trigger phrases
• Description says both what the skill does and when to use it
• SKILL.md body is under 500 lines
• Additional details are in separate files when needed
• Consistent terminology throughout
• Examples are concrete, not abstract
• Progressive disclosure used appropriately
• Workflows have clear, ordered steps

#Conclusion

We are in an era where knowing — and expressing that knowledge in a concise and precise way — is paramount to our success as individuals and organizations. Skills are a perfect reflection of that. Thanks for reading, and as always, feel free to vote on the next issue!

P.S: I'm shortly opening my agenda for new projects as an AI Frontend Architect. Feel free to reply to this email if you feel like I can help you with your project.

P.S 2: I wrote this newsletter from a 300-inhabitant village in the Serranía of Málaga, in a coliving called RooralOpen in a new tab, where I'm spending the month among other digital nomads.