What I learned building 12 custom skills for AI coding agents

The Fragmentation Problem

When we first rolled out Claude Code and Codex to the development team, everyone set up their own configuration. One developer used a custom prompt template he found on GitHub. Another relied on default settings. A third built his own workflows in a separate tool. The results were all over the place.

Some agents were helpful. Some were dangerous. Some were just weird - one colleague's agent kept trying to rewrite everything in Haskell because he had mentioned functional programming once in a Slack message.

I realized the problem was not the AI models. They were all capable. The problem was the configuration - the instructions, the tool definitions, the workflows that determined how the agent behaved. Without standardization, we had twelve different agents operating with twelve different rule sets. Some were amplifying our productivity. Others were creating more work.

I decided to build a shared configuration - a set of skills and workflows that every developer could install and use identically. What followed was six months of iteration, failure, learning, and eventually, adoption.

What a "Skill" Actually Is

In the AI agent world, a skill is a self-contained capability that the agent can invoke. It has an instruction set, input parameters, output expectations, and error handling. Think of it like a function in a programming language, but designed for natural language interaction.

A well-written skill does three things:

It defines scope. The skill knows exactly what it is supposed to do and what is out of bounds. A Jira integration skill does not try to also update Confluence. A code review skill does not rewrite entire files.

It documents assumptions. The skill's instruction set describes its expectations: "You will receive a Jira ticket key. You may assume the ticket exists and you have permission to read it." No vague expectations - clear contracts.

It handles failure. When the API fails, when the input is malformed, when the agent misunderstands - the skill has a recovery strategy. Retry. Escalate. Ask for clarification. Not just crash and return an error.

The Twelve Skills

I built twelve skills total. They fall into four categories: integrations, workflows, quality, and agility.

Integrations (4 skills)

Jira Integration. The cornerstone skill. It pulls ticket context - description, comments, attachments, linked issues - and understands the workflow. It knows what "in progress" means in our setup. It can create subtasks, add comments, transition tickets. Most importantly, it respects permissions and never exposes sensitive data in logs.

Bitbucket Integration. Pull requests, branch operations, commit conventions. The skill enforces our format: VSP-727 fix: Short description. It creates PRs with the right reviewers, labels, and target branches. It knows when a PR is ready to merge (all checks pass, approved) and when it needs revision.

Confluence Integration. Documentation lookup. When the agent needs context about architectural decisions, API contracts, or deployment procedures, it queries Confluence first. The skill is configured with the most relevant spaces and documents, so it does not waste time searching the entire knowledge base.

Outlook Calendar Integration. This one started as a joke -"can the AI schedule my meetings?" - but turned out to be surprisingly useful. The skill checks calendar availability, suggests meeting times, creates invites with appropriate attendees, and even drafts agendas based on ticket context.

Workflows (4 skills)

Laravel Workflow. The most complex skill. It orchestrates the entire Laravel development pipeline: branch creation with Jira ticket key, worktree setup via the dev orchestrator, composer install, npm install, asset compilation, testing, and PR creation. It knows the convention: VSP-727-ticket-description. It integrates with the parallel-manager agent so multiple workflows can run simultaneously without port conflicts.

Symfony Workflow. Similar to Laravel but with Symfony-specific tooling. Doctrine migrations instead of Laravel migrations. Twig templates instead of Blade. YAML configuration instead of.env.example. The skill abstracts these differences so developers using either framework get consistent experience.

PHP Testing Skill. Before any code leaves the developer's machine, this skill runs PHPUnit or Pest, checks code coverage, validates PHPStan rules, and ensures no debug code made it to the PR. It can run focused tests on changed files or full suite. It returns a detailed report that the workflow skill uses to determine if the PR is ready.

Cross-Session Memory Skill. Agents are stateless by default. This skill gives them continuity. It stores context across sessions: which tickets are being worked on, what decisions were made, what blockers were encountered. When an agent starts a new session, it loads the relevant context and picks up where it left off.

Quality (2 skills)

Laravel Simplifier Agent. This is a sub-agent, not a single skill. It takes incoming code - whether from a human developer or another agent - and looks for opportunities to simplify. It extracts long methods, replaces custom loops with collection pipelines, eliminates duplication, and improves naming. It never changes behavior - only structure. It operates as a reviewer in the PR pipeline, suggesting improvements before human review.

Code Explainer. When the agent encounters code it does not understand - third-party libraries, legacy patterns, clever but obscure algorithms - this skill generates a plain-English explanation. It is incredibly useful for onboarding new developers and for understanding vendor code. The explanations get stored in the memory skill for future reference.

Agility (2 skills)

Parallel Manager Agent. Another sub-agent, coordinating multiple worktrees and agents running simultaneously. It assigns ports, allocates database names, tracks which environments are active. When a developer starts two Jira tickets at once, this agent ensures the two workflows do not step on each other's toes.

Research Agent. Web search integrated into the agent workflow. When the agent needs documentation it cannot find internally, this skill queries Brave Search API, filters for authoritative sources, and summarizes the findings. It knows to avoid Stack Overflow for security-related questions and to prefer official documentation for framework features.

The Configuration Problem

Building the skills was only half the battle. Getting them to work together required a shared configuration. Every developer's agent needed the same skills, the same defaults, the same credentials. But hardcoding credentials is a security risk, and manual setup is error-prone.

I solved this with a configuration repository that everyone clones. The repo contains:

• Skill definitions in JSON/YAML
• Environment variable templates (never containing secrets)
• Setup scripts that pull credentials from the company password manager
• Documentation explaining what each skill does and when to use it

New developers run one script: ./setup.sh. It installs dependencies, prompts for their API keys, pulls credentials from the password manager, and configures their agents. An hour later, they have the same setup as someone who has been here for two years.

The Adoption Challenge

I announced the shared configuration in a Slack message. Response: crickets. A week later, I asked how many people had installed it. Two out of twelve.

I had built it. I documented it. I made it easy to install. Why wasn't anyone using it?

The answer was obvious in hindsight: I had not demonstrated value. I had told people "this is better." I had not shown them "this makes your specific problem go away."

So I changed tactics. Instead of announcing, I started using the configuration myself exclusively. When someone asked how I finished a ticket so quickly, I showed them my agent running the Laravel workflow. When someone complained about code quality, I showed them the Laravel Simplifier suggestions. When someone spent thirty minutes searching for documentation, I showed them the Confluence lookup.

Word spread faster than any announcement. Within a month, everyone was using it. Not because I mandated it, but because they saw it working.

What I Learned

Building this shared configuration taught me more about AI engineering than any model fine-tuning or prompt engineering ever could. Here is what stuck:

Standardization creates network effects. When everyone uses the same skills, improvements benefit everyone. When Developer A improves the Jira skill's error handling, Developer B gets that improvement automatically. There is no "my custom setup that only I understand."

Documentation is part of the skill. A skill without documentation is a trap. The moment someone does not understand what a skill does or why it exists, they will either misuse it or avoid it. Documentation lives alongside the skill definition - same repository, same versioning.

Skills should be composable. The Parallel Manager does not know about Laravel or Jira or Bitbucket. It only knows about worktrees and ports. The Laravel Workflow skill knows about Laravel and the orchestrator, and it composes the Parallel Manager skill. Each skill has a single responsibility. The intelligence emerges from composition, not from monolithic skills.

Credentials management cannot be an afterthought. I made the mistake of hardcoding some API keys in early versions (in a private repo, but still). Security review caught it. Now every credential is pulled from a password manager at runtime, with fallback to environment variables for local development. The setup script handles all of this automatically.

The Results

Six months after rollout, we have metrics:

• 100% of developers using the shared configuration (up from 2%)
• Average time from Jira ticket to PR: 2 hours (down from 8 hours)
• Code review comments per PR: 3.2 (down from 7.1) - the agents catch issues before human review
• Production incidents related to new code: zero in the last four months
• Developer satisfaction with AI tooling: 8.7/10 (up from 3.2/10)

These numbers matter. But the cultural shift matters more. AI is no longer a toy some developers play with. It is part of our standard workflow, as fundamental as Git and code review. And because everyone uses the same setup, we can improve it together.

What Comes Next

The configuration is not static. Every week someone suggests an improvement. Last month, we added a skill that generates API documentation from code comments. This month, we are building a skill that analyzes PR diffs and suggests test cases that should be added.

The goal is not to build the "perfect" configuration - that does not exist. The goal is to build a living system that gets better the more people use it. That is what I love about this approach: the intelligence is not just in the AI model. It is in the collective wisdom of the team, encoded in skills that everyone shares and improves.

The best AI configuration is the one that becomes part of the team's collective knowledge, not individual secret sauce.