Creating and Maintaining Skills

Guide for creating and maintaining agent skills in the Arda workspace. Skills provide on-demand procedural knowledge and conventions that agents load when performing specific tasks.

Architecture

Skills follow a dual-content pattern:

1. Documentation site (documentation/src/content/docs/) --- the human-readable reference content. Written for a dual audience (engineers and agents), published on the Starlight site, versioned with the documentation repository.

2. Skill stub (workspace/instructions/claude/skills/<name>/SKILL.md) --- a thin loader that resolves the documentation page at runtime and adds any agent-only procedural instructions that do not belong in published docs.

This separation ensures:

• No content duplication --- the documentation page is the single source of truth for reference material.
• Dual audience --- engineers read the documentation site; agents load it via the skill stub.
• Agent procedures stay private --- workflow steps, tool invocations, and interaction patterns that are only relevant to agents remain in the stub.

Creating a New Skill

Step 1: Write the Documentation Page

Create a Markdown file in the documentation site at the appropriate location (usually process/craft/<topic>.md).

Frontmatter:

---
title: "<Page Title>"
tags: [process, craft, <topic>]
domain: process
maturity: published
author: "Arda Systems"
---

Content guidelines:

• Write for a dual audience: engineers who read it on the site AND agents who load it as skill content.
• Use concrete examples, code snippets, and tables.
• Avoid agent-specific language (“you should ask the user…”, “run this MCP tool…”). Write in the second person addressing the practitioner.
• Follow the conventions in the Authoring Guide.

Step 2: Add the Page to the Sidebar

In documentation/astro.config.mjs, add a { slug: '<slug>' } entry in the appropriate sidebar section. The Engineering Craft section uses a manual items array with explicit slug entries.

Step 3: Create the Skill Stub

Create workspace/instructions/claude/skills/<name>/SKILL.md with this structure:

---
name: <skill-name>
description: >
  <One-line description for skill discovery.>
user-invocable: false
---

The body contains:

1. A Loading section that runs resolve-doc-page.sh to find the documentation page (see The Resolver Script).
2. An optional Agent-Specific Notes section for agent-only procedures.

Step 4: Add Agent-Specific Notes (if needed)

If the skill requires agent-only procedures that should not appear in the published documentation, add them after the Loading section.

What belongs in Agent-Specific Notes vs. the documentation page:

Agent-Specific Notes	Documentation Page
”Play the attention sound before running op run”	Environment tables, endpoint URLs, header formats
”Wait for user confirmation before proceeding”	Workflow phases, decision criteria, templates
”Load the release-lifecycle skill for Phase 5”	Cross-references to related guides
”Validate diagrams via PlantUML MCP tool”	Diagram conventions and syntax rules
”Redirect output to scratch/”	Command examples and patterns
Script execution commands with absolute paths	General command patterns

Step 5: Verify

1. Run the resolver to confirm it finds the documentation page:

   bash workspace/instructions/claude/scripts/resolve-doc-page.sh <slug>

2. Build the documentation site to verify the page compiles:

   cd documentation && npm run build

The Resolver Script

workspace/instructions/claude/scripts/resolve-doc-page.sh resolves a documentation page slug to a local file path or GitHub coordinates.

Resolution order:

1. Local checkout --- checks for a documentation sibling directory at the workspace root, then looks for <slug>.md or <slug>/index.md under src/content/docs/.
2. GitHub fallback --- if no local checkout exists, outputs GitHub coordinates for retrieval via the GitHub API.

Output format:

Prefix	Meaning	Action
local:<path>	File found locally	Read the file at the given path
github:<path>	No local checkout	Fetch from Arda-cards/documentation on GitHub
error:<message>	Resolution failed	Alert the user

Converting an Existing Skill

When converting a skill that currently has inline content:

1. Identify which content is reference material (conventions, patterns, templates) vs. agent procedures (workflow steps, tool calls, interaction patterns).
2. Verify the reference content exists in the documentation site (or create the page if it doesn’t).
3. Replace the skill body with the loader stub.
4. Preserve agent-specific procedures in an Agent-Specific Notes section.
5. Test the resolver and verify the documentation page builds.

Naming Conventions

Element	Convention	Example
Skill directory	kebab-case matching the topic	kotlin-coding/
Skill file	Always SKILL.md	SKILL.md
Documentation slug	process/craft/<topic> for craft guides	process/craft/kotlin-coding
Frontmatter name	Same as directory name	kotlin-coding

---

Copyright: (c) Arda Systems 2025-2026, All rights reserved