Skillshilp Create

Skillshilp Create

Design Agent Skills as reusable software components, not large prompts.

Your objective is to produce Agent Skills that are discoverable, composable, maintainable, deterministic, and token-efficient.

Use this skill only for creating new skills. If the primary task is to modify, refactor, review, or improve an existing skill, use skillshilp-edit instead.

If official documentation is available, treat it as the source of truth. Otherwise, follow the provided specification.

Principles

Every file should have a clear purpose. Avoid introducing directories, files, or abstractions that do not meaningfully improve maintainability or reuse.

Prefer concise examples over broad explanations. Treat context as a scarce shared resource.

Workflow

1. Evaluate

Determine whether the request should become an Agent Skill.

An Agent Skill should represent a reusable capability that another agent can reliably discover and invoke.

If the request is better solved by a script, template, document, workflow, or one-off prompt, recommend that instead.

If the intended use is unclear, derive or ask for 2–3 realistic user requests before designing the skill. Use those examples to identify the repeatable workflow, activation criteria, required inputs, expected outputs, and reusable resources.

Define:

• responsibility
• intended users
• activation criteria
• inputs
• outputs
• constraints
• dependencies
• edge cases

If multiple unrelated capabilities are identified, split them into separate skills with clearly defined responsibilities.

2. Design

Design the architecture before writing any files.

Set the right degree of freedom:

• Use SKILL.md for flexible workflow guidance.
• Use references/ for detailed knowledge that is only sometimes needed.
• Use scripts/ for repeated, deterministic, or fragile operations.
• Use assets/ for reusable output materials.

Prefer minimal Bash for scripts. If Bash cannot express the operation safely, document the requirement and ask before choosing another runtime.

Map concrete examples to reusable artifacts:

• Repeated command sequence → scripts/
• Long domain/API/schema knowledge → references/
• Template, boilerplate, or sample input → assets/
• Core activation and workflow rules → SKILL.md

Create only the directories that add value.

Typical portable layout:

skill-name/
├── SKILL.md
├── references/
├── scripts/
└── assets/

Do not create README.md or other auxiliary documentation unless the user requests distribution-facing docs.

Decide where each piece of information belongs.

SKILL.md

Keep concise.

Include only:

• activation criteria
• workflow
• critical rules
• validation
• references to supporting files

references/

Store information intended to be read by the model, such as:

• technical documentation
• APIs
• algorithms
• schemas
• workflows
• FAQs
• design guidance

scripts/

Store executable logic only when it materially improves reliability or repeatability.

Scripts should be minimal Bash, validate inputs, document dependencies, fail predictably, and avoid embedding large prompts where executable code is more appropriate.

assets/

Store reusable resources, such as:

• templates
• configuration files
• diagrams
• sample data
• example documents

Do not add product-specific metadata, client configuration, or product-specific helper scripts when portability is the goal.

3. Implement

Generate:

• directory tree
• valid frontmatter
• concise SKILL.md
• supporting reference files
• scripts when appropriate
• assets when appropriate

Descriptions should clearly explain:

• what the skill does
• when another agent should activate it
• what makes it distinct from similar skills

Assume the description will be used for automatic discovery.

Use only portable Agent Skills frontmatter.

4. Validate

Before finalizing, verify that the skill is:

• specification compliant
• discoverable
• single responsibility
• modular
• composable
• maintainable
• progressively disclosed
• minimally duplicated
• token-efficient

When a skill directory exists on disk, run:

scripts/validate-skill.sh <skill-dir>

Validate against:

references/constraints.md

Review common architectural patterns:

references/patterns.md

Check for common design mistakes:

references/skill-smells.md

If any issue is found, revise the design before returning the skill.

For complex or fragile skills, forward-test with realistic user requests. Give validators the skill and raw task artifacts, not expected answers or your diagnosis.

Output

Prefer creating or modifying files directly when the environment allows it.

If files were written, provide:

1. Changed paths
2. Validation results
3. Brief design notes explaining important architectural decisions

If files cannot be written or the user asks for generated content, provide:

1. Complete directory tree
2. Complete contents of every generated file
3. Valid relative file references
4. Brief design notes

Do not dump full file contents for files already written unless explicitly requested.

Final Check

Before returning the skill, ask:

If this skill were published in a large public registry, would another agent reliably discover it, understand when to activate it, compose it with other skills, and successfully execute it without additional explanation?

If the answer is not an unqualified yes, continue refining the design.