creating-linksoft-skills

Files (5)

• README.md
• SKILL.md
• evals.json · evals/
• descriptions-and-evals.md · references/
• scripts-and-structure.md · references/

SKILL.md (first lines)

## Purpose

Use this skill to create or revise a reusable Agent Skill in the standard Agent Skills format that is:

- narrowly scoped
- easy for agents to trigger correctly
- concise in `SKILL.md`
- structured with progressive disclosure
- documented and validated using this repository's conventions

## Workflow

### 1. Confirm the job the skill should do

Start from real expertise before creating files.

- Start from a real task completed with an agent, or from project artifacts such as runbooks, internal docs, style guides, API specs, schemas, issue trackers, review comments, and prior fixes.
- Extract the steps that actually worked, the corrections that were needed, the repeatable procedure, the project-specific constraints and gotchas, and the expected inputs and outputs.
- After drafting the skill, try it on real tasks and fold recurring mistakes, missing steps, or incorrect assumptions back into the instructions.
- If the request is vague, narrow it until you can state one clear unit of work and its scope boundary.

Good scope checks:

- Can you say what is in scope and out of scope in 1-2 sentences?
- Would one agent usually use this skill for one coherent task?
- If the skill starts to cover unrelated workflows, split it.

### 2. Choose a compliant name

The skill name must match the folder name and the spec:

- lowercase letters, numbers, and hyphens only
- no leading or trailing hyphen
- no consecutive hyphens
- concise and specific

Prefer names that describe the capability, not generic helper terms.

Examples:

- Good: `opening-in-ide`, `reviewing-skills`, `creating-linksoft-skills`
- Avoid: `skill-helper`, `misc-tools`, `data-handler`

### 3. Write the description for triggering

The description is the main trigger signal. Write it in imperative form around user intent.

Use this pattern:

```yaml
description: Use this skill when ...
```

Description guidance:

- say what the skill helps accomplish
- say when it should be used
- include likely user intents and domain terms
- stay specific enough to avoid false positives
- keep it concise and well below the 1024-character limit
- prefer roughly 1 sentence and usually no more than about 200 characters unless a slightly longer description is clearly necessary for trigger accuracy
- move procedural detail, caveats, and examples into `SKILL.md` instead of the description

Good example:

```yaml
description: Use this skill when creating or improving Agent Skills, including naming, description writing, progressive disclosure, scripts, evals, and repository compliance.
```

Avoid descriptions like `Helps with skills.` or descriptions that only explain implementation details.

Treat description length as a real constraint because descriptions are loaded into context during activation.

If the user asks for description tuning, use the process in `references/descriptions-and-evals.md`.

### 4. Keep `SKILL.md` lean

Put only the instructions the agent needs on nearly every activation into `SKILL.md`.

Include:

- purpose and activation context
- the core workflow
- critical defaults
- links to references, scripts, templates, or eval assets

Use progressive disclosure to spend context wisely. Do not overload `SKILL.md` with long background explanations, exhaustive examples, or large reference material. Keep the main body under about 5,000 tokens, keep it under 500 lines, and prefer much shorter when possible.

If the skill needs detailed supporting material, move it to `references/` and tell the agent exactly when to read each file.

### 5. Structure the skill directory

Start from the Agent Skills format, then apply LinkSoft repository requirements.

Agent Skills format minimum:

```text
<skill-name>/
`- SKILL.md
```

LinkSoft repository layout for this repo:

```text
skills/<skill-name>/
|- SKILL.md
|- README.md
|- assets/
|- references/
|- scripts/
`- evals/
```

Treat these as building blocks, not a mandatory checklist. Add only the files and directories that materially improve the skill.

- `assets/`: reusable templates, schemas, and other static resources the agent can load on demand
- `README.md`: required by this repository for human-facing overview, contents, usage notes, and validation notes
- `references/`: add when detailed instructions are only needed in some runs
- `scripts/`: add when reusable executable helpers are more reliable than repeated prose instructions

From Linksofteu/LinkSoft_Skills, MIT.

More from Linksofteu/LinkSoft_Skills