holocron/plugins/kyberforge/docs/agentskillsio/skill-authoring.md

topic, source_keys

topic	source_keys
agentskills-skill-authoring	agentskills-best-practices

Start from real expertise

A common pitfall: asking an LLM to generate a skill without domain-specific context. The result is vague, generic procedures rather than the specific API patterns, edge cases, and project conventions that make a skill valuable.

Extract from a hands-on task. Complete a real task in conversation with an agent, providing corrections and preferences along the way. Then extract the reusable pattern. Capture:

• Steps that worked — the sequence that led to success
• Corrections you made — "use library X not Y," "check for edge case Z"
• Input/output formats — what data looked like going in and out
• Context you provided — project-specific facts the agent didn't know

Synthesize from existing artifacts. Feed project-specific material into an LLM and ask it to synthesize a skill. Good sources: internal runbooks, API specs, code review comments, version control history (especially patches — reveals patterns through what actually changed), real-world failure cases.

Refine with real execution

Run the skill against real tasks. Feed results — all of them, not just failures — back into the creation process. Even a single execute-then-revise pass noticeably improves quality.

Read agent execution traces, not just final outputs. Common causes of wasted work in traces:

• Instructions too vague — agent tries multiple approaches
• Instructions that don't apply to the current task — agent follows them anyway
• Too many options without a clear default

Spending context wisely

Once a skill activates, its full SKILL.md body loads alongside conversation history, system context, and other active skills. Every token competes for the agent's attention.

Add what the agent lacks, omit what it knows. Focus on project-specific conventions, domain-specific procedures, non-obvious edge cases, and the particular tools to use. Don't explain what a PDF is or how HTTP works.

<!-- Too verbose — the agent already knows what PDFs are -->
PDF files contain text and images. To extract text, use pdfplumber...

<!-- Better — jumps to what the agent wouldn't know on its own -->
Use pdfplumber for text extraction. For scanned documents, fall back to
pdf2image with pytesseract.

Ask about each piece of content: "Would the agent get this wrong without this instruction?" If no, cut it.

Design coherent units. Skills scoped too narrowly force multiple skills to load for one task; skills scoped too broadly are hard to activate precisely. A skill for querying a database and formatting results is one coherent unit; a skill that also covers database administration is probably too broad.

Aim for moderate detail. Overly comprehensive skills hurt — the agent struggles to extract what's relevant and may pursue unproductive paths. Concise, stepwise guidance with a working example outperforms exhaustive documentation.

Calibrating control

Give the agent freedom when multiple approaches are valid. Explaining why is more effective than rigid directives — agents make better decisions when they understand the purpose.

Be prescriptive when operations are fragile, consistency matters, or a specific sequence must be followed:

## Database migration

Run exactly this sequence:

```bash
python scripts/migrate.py --verify --backup

Do not modify the command or add additional flags.

**Provide defaults, not menus.** When multiple tools could work, pick one and mention alternatives briefly:

```markdown
<!-- Too many options -->
You can use pypdf, pdfplumber, PyMuPDF, or pdf2image...

<!-- Clear default with escape hatch -->
Use pdfplumber for text extraction. For scanned PDFs requiring OCR,
use pdf2image with pytesseract instead.

Favor procedures over declarations. Teach the agent how to approach a class of problems, not what to produce for a specific instance. The approach should generalize even when individual details are specific.

Effective instruction patterns

Gotchas sections

The highest-value content in many skills is a list of gotchas — environment-specific facts that defy reasonable assumptions:

## Gotchas

- The `users` table uses soft deletes. Queries must include
  `WHERE deleted_at IS NULL` or results will include deactivated accounts.
- The user ID is `user_id` in the database, `uid` in the auth service,
  and `accountId` in the billing API. All three refer to the same value.
- The `/health` endpoint returns 200 even if the database is down.
  Use `/ready` to check full service health.

Keep gotchas in SKILL.md where the agent reads them before encountering the situation. When an agent makes a mistake you correct, add the correction to the gotchas section.

Templates for output format

Provide a template when the agent must produce a specific output format. Short templates live inline; longer ones go in assets/ and are referenced conditionally.

## Report structure

Use this template:

\`\`\`markdown
# [Analysis Title]

## Executive summary
[One-paragraph overview]

## Key findings
- Finding 1 with supporting data

## Recommendations
1. Specific actionable recommendation
\`\`\`

Checklists for multi-step workflows

## Workflow

Progress:
- [ ] Step 1: Analyze the form (run `scripts/analyze_form.py`)
- [ ] Step 2: Create field mapping (edit `fields.json`)
- [ ] Step 3: Validate mapping (run `scripts/validate_fields.py`)
- [ ] Step 4: Fill the form (run `scripts/fill_form.py`)

Validation loops

## Editing workflow

1. Make your edits
2. Run validation: `python scripts/validate.py output/`
3. If validation fails, fix and re-run
4. Only proceed when validation passes

Plan-validate-execute

For batch or destructive operations: create an intermediate plan in a structured format, validate it against a source of truth, then execute:

1. Extract form fields → `form_fields.json`
2. Create `field_values.json` mapping each field to its intended value
3. Validate: `python scripts/validate_fields.py form_fields.json field_values.json`
4. If validation fails, revise and re-validate
5. Fill the form: `python scripts/fill_form.py input.pdf field_values.json output.pdf`

Bundling reusable scripts

If execution traces show the agent independently reinventing the same logic across runs — building charts, parsing a format, validating output — write a tested script once and bundle it in scripts/. See the scripts reference.

Structure large skills with progressive disclosure

Keep SKILL.md under 500 lines and 5,000 tokens — the core instructions the agent needs every run. When a skill needs more content, move detail to references/ and tell the agent when to load each file:

If the API returns a non-200 status code, read `references/api-errors.md`.

"Read references/api-errors.md if X" is more useful than a generic "see references/ for details." The agent loads context on demand rather than up front.