# Custom Skill Builder

> Create or update a reusable Agent Skill in the open SKILL.md format. Use for project, team, domain, or tool workflows that need a precise trigger and repeatable procedure. Add references, scripts, assets, client metadata, or routing only when the skill needs them; do not create a new skill for a one-off instruction or a narrow variant already owned elsewhere.

- Skill: `ashermahonin/custom-skill-builder` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add ashermahonin/custom-skill-builder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ashermahonin/custom-skill-builder/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ashermahonin (https://skillmd.com/u/ashermahonin)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/ashermahonin/custom-skill-builder

---


# Custom Skill Builder

## Purpose

Create focused, portable skills that load at the right time and give an agent information it would not reliably infer on its own.

## Skill brief

1. Read `references/skill-authoring-contract.md`.
2. Clarify the skill intent in one sentence: what recurring job should this skill make easier?
3. Decide whether this is a new skill, an update, or a project-local skill.
4. Check for overlap with existing skills. Extend an existing skill when the new behavior is a narrow variant; create a new skill when it has a distinct trigger, workflow, or ownership boundary.
5. If the skill depends on current libraries, APIs, CLIs, MCP servers, or platform behavior, verify those docs with Context7 MCP before writing procedural guidance.

## Authoring method

1. Write a lowercase hyphenated `name` and a `description` that says what the skill does and when it should activate.
2. Keep the body focused on the recurring decision or procedure. Put conditional detail in directly linked references.
3. Add `scripts/` only for deterministic repeated work and `assets/` only for files used in output.
4. Add client metadata such as `agents/openai.yaml` only when it improves a supported client; the core skill must remain usable without it.
5. Register the skill in routing only when it participates in a multi-skill workflow.
6. Validate against the Agent Skills specification and this repository's routing rules.
7. Forward-test realistic prompts that should and should not activate the skill. Compare the result with the previous version or a no-skill baseline when the behavior is important.

## Portability rules

- Preserve the user's chosen product, scope, and authorization boundary.
- Use current primary documentation for external technology behavior.
- Do not copy manuals into a skill. Keep only the decisions and procedures the agent needs.
- Do not require one fixed heading template. Structure the body around the actual task.
- Do not add a skill-level README, changelog, or installation guide unless it is part of the requested package.

## Skill package

- New or updated skill folder
- Valid `SKILL.md`
- Supporting resources that have a concrete use
- Routing and client metadata where applicable
- Validation and forward-test evidence

## Ready when

- The name matches the folder and Agent Skills naming rules.
- The description is discriminating without becoming a capability catalogue.
- The body contains no generic advice the target model already knows.
- References are discoverable and resources are portable.
- Tests show both useful activation and non-activation.
- No machine-specific paths, placeholders, or hidden permissions remain.

## Handoff

Report the skill name, activation boundary, resources, routing impact, validation result, and one realistic invocation. Use `self-improvement-loop` only when the change responds to measured agent failure.

## References

- `references/skill-authoring-contract.md`: compact rules for skill scope, anatomy, progressive disclosure, metadata, validation, and forward testing.