Writing Predictable Skills: The Developer's Guide

Where this fits

You've built an agent that calls a dozen skills, but half the time it picks the wrong one or misses it entirely. The root cause is often skill design: vague descriptions, unclear invocation rules, and inconsistent vocabulary. The writing-great-skills skill from the fastagent repo gives you a mental model and vocabulary to make your skills predictable — meaning the agent follows the same process every run, not that it produces identical outputs. It's a reference you can apply while defining any skill, whether you're working solo or in a team.

Why agents benefit

• Reliable autonomous triggering: Model-invoked skills with rich trigger phrasing ("Use when the user wants…, mentions…") let the agent fire the correct skill without manual intervention.
• Zero context load when needed: User-invoked skills strip the description from the agent's window, reducing per-turn token overhead and letting the model focus on the task.
• Clear separation of concerns: The two invocation modes force you to decide who should call a skill, preventing accidental auto-triggers in sensitive workflows.
• Shared vocabulary: The glossary (GLOSSARY.md) defines terms like context load and cognitive load, so your team and future agents interpret skill behavior uniformly.
• Predictable debugging: When a skill misbehaves, you can trace the cause to invocation design or description quality, not stochastic noise.

Practical scenarios

Building a multi-skill assistant with a sensitive internal tool

You have a skill that deletes user data. You don't want the agent to invoke it autonomously. By marking it user-invoked (disable-model-invocation: true), you ensure only a human typing its name can trigger it — zero risk of accidental deletion.

Debugging why an agent skipped a skill

Your agent never calls the format_report skill. You inspect the description and see it says "Use when the user wants a report." That's too generic. Following the skill's guidance, you rewrite it with trigger phrases like "Use when the user asks for a PDF, a formatted summary, or mentions a file extension." The next run, the agent picks it up.

Onboarding a new developer to your skill library

You share the repo with a colleague. Instead of explaining every convention, you point them to writing-great-skills. They read the glossary and invocation rules, then write a new skill that matches your team's style without a long meeting.

Add it to your agent workflow

Install the skill into your agent project with:

npx skills add fastagent-sh/fastagent --skill writing-great-skills

Once installed, open the README and GLOSSARY.md to internalize the principles. When you write a new skill, start by deciding its invocation type, then craft the description using the trigger-phrase patterns shown in the reference.

Compare before adopting

Before committing to this skill as your team's standard, compare it with alternatives like Anthropic's skill authoring guidelines or your own ad-hoc conventions. Look for:

• Quality signals: Does the glossary define terms precisely? Are examples concrete?
• Maintenance freshness: Is the repo actively updated? Check commit history and issues.
• Alternatives: Are there other skill-writing references with better fit for your stack?
• Workflow fit: Does the invocation model align with how your agent is deployed (e.g., autonomous vs. human-in-the-loop)?

Why it is worth tracking

This skill is part of the fastagent project (56 stars and climbing), which signals community interest in disciplined agent development. Its principles — predictability, explicit invocation, and a shared vocabulary — directly address one of the most common failure modes in agent engineering. Even if you don't adopt it wholesale, the mental model will improve your skill design. Evaluate it when you're starting a new skill library or refactoring an existing one. For a curated overview of similar skills and community context, see this skill on OpenAgentSkill.