Lab 5.1: Author Two Personal Skills¶

Goal¶

Write two skills relevant to your stack, then test that the agent discovers them automatically based on natural questions.

What You'll Learn¶

Skill file anatomy (folder + frontmatter + markdown)
Writing descriptions that trigger skill discovery
Testing skill discovery with a real agent interaction

Prerequisites¶

You have OpenCode installed (from Week 2)
You have a project with a .opencode/ folder (or you'll create one)
You understand the skill/command/AGENTS.md decision from the lesson

Part 1: Choose Your Two Skills¶

Pick two tasks relevant to your work and stack. Here are examples:

Example 1: Web Developer (React + TypeScript)¶

Skill A: Component scaffold template (when user says "create a React component")
Skill B: TypeScript gotchas (when user mentions "TypeScript bug" or "type error")

Example 2: Data Scientist (Python + Pandas)¶

Skill A: DataFrame debugging checklist (when user says "debug my DataFrame")
Skill B: Plotting patterns (when user asks "how should I plot this data")

Example 3: DevOps/Backend (Node.js + Docker)¶

Skill A: Docker troubleshooting guide (when user says "Docker error" or "container won't start")
Skill B: API error handling patterns (when user asks to "fix an API endpoint" or "handle errors")

Your task: Pick one from your domain that you actually need, and invent one more.

Part 2: Create the Folder Structure¶

In your project root:

mkdir -p .opencode/skills/skill-name-1
mkdir -p .opencode/skills/skill-name-2

If .opencode/ doesn't exist yet, create it.

Names should be lowercase with hyphens, e.g., component-template, dataframe-debugging, docker-troubleshooting.

Part 3: Author Skill #1¶

Create .opencode/skills/SKILL-NAME-1/SKILL.md:

---
name: skill-name-1
description: Use when the user asks to [specific trigger phrase]. Includes [what the skill provides].
---

## [Section Title]

[Your content here. Make it concrete and actionable.]

### Example or Template

[Real example or template the agent will follow]

### Common Pitfalls

- [Thing developers get wrong]
- [Another mistake]

Writing Your Description¶

Your description must answer: When should an agent use this skill?

Good descriptions include: - The trigger word(s): "create a component," "debug a DataFrame," "Docker error" - The context: "for a React application," "in Python data analysis" - What the skill does: "provides a template," "lists common mistakes," "shows best practices"

Example:

description: Use when the user asks to create a React component or scaffold a new component.
Includes TypeScript types, prop patterns, and common gotchas.

Content Structure¶

After frontmatter, write actionable markdown:

Brief intro (1–2 sentences): What is this skill for?
Template or checklist (what the agent will use as a reference)
Real example (shows what good output looks like)
Tips or pitfalls (common mistakes to avoid)

Keep it 500–1000 words. If it's longer, you might want this in AGENTS.md instead.

Part 3.1: Full Example¶

Let's say you're a React developer and your Skill #1 is a component template:

---
name: react-component-template
description: Use when the user asks to create a React component, scaffold a new component,
or write component code. Provides TypeScript types and modern patterns.
---

## React Component Template

A well-structured React component should:
1. Define clear prop types
2. Handle loading and error states
3. Use hooks appropriately
4. Include JSDoc comments

## TypeScript Functional Component Template

```typescript
import React from 'react';

interface YourComponentProps {
  /** Description of prop */
  title: string;
  /** Optional prop */
  onClose?: () => void;
}

/**
 * Brief description of what this component does.
 * @param props - The component props
 * @returns The rendered component
 */
export const YourComponent: React.FC<YourComponentProps> = ({
  title,
  onClose,
}) => {
  const [isLoading, setIsLoading] = React.useState(false);
  const [error, setError] = React.useState<string | null>(null);

  const handleAction = async () => {
    setIsLoading(true);
    try {
      // Your logic here
    } catch (err) {
      setError(err instanceof Error ? err.message : 'Unknown error');
    } finally {
      setIsLoading(false);
    }
  };

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;

  return (
    <div className="component">
      <h2>{title}</h2>
      {onClose && <button onClick={onClose}>Close</button>}
    </div>
  );
};

export default YourComponent;

Common Mistakes¶

Forgetting prop types → Component is hard to use and test
No error handling → App crashes silently
Missing JSDoc → Future you doesn't remember what props do
Not exporting named export → Other code can't import it

When Not to Use This Template¶

You're using class components (use hooks instead)

You're building a simple presentational component (no state needed)

## Part 4: Author Skill #2

Repeat Part 3, but for your second skill. Make sure:

- Folder name matches the `name` field in frontmatter
- Description is specific and trigger-phrase-aware
- Content includes at least one template or checklist
- Total word count: 500–1000 words

## Part 5: Test Discovery

Now, test that the agent finds your skills.

### 5.1: Run OpenCode

In your project directory (where `.opencode/` is):

```bash
opencode

This launches the OpenCode TUI.

5.2: Ask a Natural Question¶

In the input box, type a question that should trigger one of your skills. For example:

If you wrote a "component template" skill, ask: "I need to create a new React component. What structure should I follow?"
If you wrote a "DataFrame debugging" skill, ask: "My DataFrame is showing weird values. How do I debug this?"

5.3: Watch the Agent¶

The agent should: 1. Read your question 2. Search available skills 3. Load your skill (you might see a log message like "Loaded skill: component-template") 4. Use it in the response

If it works: Your description is good. The agent found your skill.

If it doesn't work: Your description is too vague. Go back to Part 3.1 and rewrite it.

5.4: Test Skill #2¶

Ask a different question that should trigger Skill #2. Repeat the same check.

Part 6: Reflection (Write 3–5 bullets)¶

Answer these in your lab notes:

What phrasing triggered Skill #1? (e.g., "When I said 'create a component,' the agent loaded it.")
What would happen if someone asked the same thing without your skill? (e.g., "The agent would still help, but without your TypeScript pattern.")
Did the agent use your template verbatim, or adapt it? (This is normal either way.)
What would make this skill more discoverable? (Any tweaks to the description?)

Submission¶

Create a README in your lab project documenting:

# Lab 5.1: Two Skills

## Skill #1: [name]
- **File**: `.opencode/skills/[name]/SKILL.md`
- **Trigger phrase(s)**: [what the user says to trigger it]
- **Content**: [one-sentence summary]

## Skill #2: [name]
- **File**: `.opencode/skills/[name]/SKILL.md`
- **Trigger phrase(s)**: [what the user says to trigger it]
- **Content**: [one-sentence summary]

## Discovery Test Results

[Your reflection from Part 6]

Then take a screenshot of the agent using one of your skills and include it.

Checkpoints¶

[ ] Two skill folders created with correct naming
[ ] YAML frontmatter valid (no syntax errors)
[ ] Descriptions are specific and trigger-phrase-aware
[ ] Content includes templates/checklists
[ ] Agent successfully loads Skill #1 based on a natural question
[ ] Agent successfully loads Skill #2 based on a different natural question
[ ] README documents both skills and test results
[ ] One screenshot showing skill discovery in action