Designing Agent Skills for TypeScript Production

Hello, friends. If you want to control more than just a single model in AI coding tools, you’re in the right place. Agent Skills do more than teach a coding tool something new. They define which workflow to follow and which checks the generated code has to pass. In this post, we’ll craete a skill folder for a TypeScript project and turn quality control into a release gate.

Skill folder

The most basic skill is a folder containing a SKILL.md file. At the top of this file, there is YAML frontmatter, followed by the Markdown instructions the agent will follow. The name and description fields are required in the frontmatter.

The name field must be between 1 and 64 characters and must match the skill folder name. The general Agent Skills specification asks for lowercase letters, numbers, and hyphens only. The description field must be between 1 and 1,024 characters and should clearly explain what the skill does as well as when to use it. The agent does not read every instruction at startup. It first sees the skill names and descriptions.

For example, you could create the following structure:

typescript-production/
├── SKILL.md
├── references/
│   ├── testing-patterns.md
│   └── security-checklist.md
├── assets/
│   └── prd-template.md
└── scripts/
    └── check-boundaries.mjs

In the SKILL.md file, explain which files the agent should open at each stage and which checks it should run. You can keep detailed testing examples under references/, a reusable PRD template under assets/, and short, deterministic operations under scripts/. You can learn more about Agent Skills here.

The frontmatter could look like this:

---
name: typescript-production
description: Runs a production workflow for TypeScript projects that plans goals, produces code in thin vertical slices, and does not ship until testing and security checks are complete.
---
# TypeScript Production

## Define

Before writing code, define the goals, project structure, commands to use,
code style, tests, and boundaries.

## Plan

Create small tasks with acceptance criteria and dependency order.

## Build

Implement each task in thin vertical slices.
Write the test first and verify that it fails.
Then write the implementation and complete the Red-Green-Refactor cycle.

## Verify

Run the test, lint, typecheck, and build commands defined by the project.
Skipping checks or silencing tests is forbidden.

## Review

Review the change across security, performance, maintainability,
functionality, and quality.

## Ship

Do not ship until all checks pass and a human has reviewed the change.

When writing this file, do not put long-term application code inside the skill. A skill packages the method the agent will follow and the resources it needs. Instead of carrying the project’s code, it is better for the skill to use the existing tools. You can turn fragile or repetitive operations into small scripts, but the scripts should remain short and deterministic.

Another important point is progressive disclosure. The agent first sees only the name and description. If a task matches the skill, SKILL.md is loaded. Reference files are read when the instructions actually need them. Scripts are not run automatically eiher. The agent can run them when the instructions call for it. Microsoft’s explanation shows this process in four stages.

A development workflow that defines quality

You cannot solve quality control by simply telling the model to “be more careful.” Instead, define an end-to-end workflow inside the skill. In my view, the DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP stages from the skill collection shared by Addy Osmani provide a good framework. You can review the workflow here.

We need to prepare a PRD before writing any code. Simply saying “add an endpoint” is not enough. Clearly document the commands, project structure, code style, how to run the tests, and what is out of scope. Then break the plan into small, verifiable tasks. Once every task has clear acceptance criteria and dependency order, the agent can work through smaller changes.

I also think it makes sense to implement the solution in thin vertical slices. First, confirm that the test is visible and that it genuinely fails. Then write the code. This keeps the Red-Green-Refactor cycle from becoming just a slogan and makes quality visible during development. You can also use the 80/15/5 pyramid for test distribution. Put most tests at the unit level, followed by integration tests, and finally end-to-end tests.

It is better to keep information that is specific to the project and changes frequently in project files such as Rules or CLAUDE.md, rather than in the skill. Code style, libraries and versions, responsibilities, and basic commands belong to the project context. The skill carries how that context should be used and the quality workflow. Cursor takes a similar approach: Rules contain persistent project instructions, while Skills contain workflows and domain knowledge that load when they are relevant. You can see the distinction between Rules and Skills here.

Safely limiting tools

Treating load_skill, read_skill_resource, and run_skill_script as a single permission is risky. The first operation loads the skill instructions. The second reads a reference or asset, and the third runs code. Authorize all three separately. Permission to read a skill is not the same as permission to run code.

By default, Microsoft Agent Framework asks for approval for all three operations. Use automatic approval rules only for trusted sources and skills you have reviewed. The important distinction is that this behavior is specific to Microsoft Agent Framework. Do not treat it as a universal security rule for the general Agent Skills format.

If you plan to run scripts, consider sandboxing for the production environment, as well as CPU and memory limits, timeouts, input validation, and an executable allow-list. You also need structured logging and an audit trail. If a script crashes or modifies the wrong file, you need to be able to trace what happened afterward.

It is also important to produce small, understandable errors:

import fs from "node:fs";

const target = process.argv[2];

if (!target) {
  console.error("Usage: node check-boundaries.mjs <folder>");
  process.exit(1);
}

if (!fs.existsSync(target)) {
  console.error(`Target folder not found: ${target}`);
  process.exit(1);
}

console.log(`Boundary check started: ${target}`);

This is not a real quality check, but it shows how scripts should be written. It is safer to give a script a short, single-purpose operation than to ask the agent to interpret a long piece of business logic. The agent should read the script output and correct the error.

Do not share source code, API keys, customer data, or intellectual property with external agents without explicit approval. Verifying code produced by AI also remains the developer’s responsibility. The Agentic Coding Principles page emphasizes this responsibility clearly.

Turning quality into a release gate

Do not leave quality thresholds as a few sentences embedded in the skill. Create a version-controlled file such as CONSTRAINTS.md and explain how tests, linting, typechecking, security, and performance checks will be evaluated. Checks must not be skpiped, and tests must not be silenced just to make them look green.

A security review can cover the OWASP Top 10, authentication patterns, secret management, dependency audits, and boundary validation. For performance, measure first. Set Core Web Vitals targets, run profiling, and perform bundle analysis. Optimize based on measurements, not intuition.

For code review, keeping changes around 100 lines usually makes them easier to read. Review the change across five axes with severity labels. AI-generated code should not enter the system until someone understands it and verifies it with comprehensive tests. Do not approve a diff just because “the tests pass.” Read it in terms of security, failure cases, and maintenance cost as well.

Note: There is a small difference among the sources regarding the 500-line limit. Microsoft’s documentation treats it as mandatory, while the general Agent Skills specification and best practices describe it as a recommendation. Similarly, the default approval behavior is not a required rule of the general format. It is the behavior of the Microsoft Agent Framework implementation. Keep this difference in mind if you want the skill to remain portable.

In practice, start by keeping the SKILL.md file small and defining the workflow end to end. Then add only the documents you genuinely need under references/. Finally, review script execution and automatic approval permissions separately. Instead of loading more into the AI, teach it what to do, when to do it, and where to stop with the right security boundaries. That is a healthier production approach.

That is all for setup and approach. Do not forget to review scripts and automatic approval permissions separately to keep the skill portable. I hope this helped, and I would be happy if it did :)

Sources

• addyosmani/agent-skills: Production-grade engineering skills for AI coding agents. (GitHub)

• Agent Skills Overview (Agent Skills)

• Agent Skills (learn.microsoft.com)

• Agent Skills (Claude Platform Docs)

• Specification (Agent Skills)

• GitHub - anthropics/skills: Public repository for Agent Skills (GitHub)

• Best Practices for Creating Agent Skills (GitHub)

• Agentic Coding Principles & Practices (agentic-coding)

• Best practices for coding with agents (Cursor)