From 85abca56ffe761d8ad06ad35a4d21e6711c19984 Mon Sep 17 00:00:00 2001 From: Geoff Johnson Date: Wed, 13 May 2026 10:05:49 -0700 Subject: [PATCH 1/2] docs: document the agent skills system From 05c145305a1f0455eb9215e5ea0588bd12ee366b Mon Sep 17 00:00:00 2001 From: Geoff Johnson Date: Wed, 13 May 2026 10:07:41 -0700 Subject: [PATCH 2/2] docs: document the agent skills system - Add docs/agent-skills.md with complete guide covering: - Overview and how skills work end-to-end - Skill file format (frontmatter, directory/flat layouts) - Discovery paths and priority order - Assigning skills to agents (specific list, 'all', default) - Materialization behavior (precedence, worktree agents) - CLI command reference (agent skill list/show) - Writing good skills (best practices) - Troubleshooting guide - API reference - Add example skills in .agentd/skills/: - git-spice/SKILL.md - branch stacking workflow - agent-memory/SKILL.md - memory service operations - example/SKILL.md - minimal template for authoring Closes #1215 --- .agentd/skills/agent-memory/SKILL.md | 49 ++++ .agentd/skills/example/SKILL.md | 33 +++ .agentd/skills/git-spice/SKILL.md | 44 ++++ docs/agent-skills.md | 323 +++++++++++++++++++++++++++ 4 files changed, 449 insertions(+) create mode 100644 .agentd/skills/agent-memory/SKILL.md create mode 100644 .agentd/skills/example/SKILL.md create mode 100644 .agentd/skills/git-spice/SKILL.md create mode 100644 docs/agent-skills.md diff --git a/.agentd/skills/agent-memory/SKILL.md b/.agentd/skills/agent-memory/SKILL.md new file mode 100644 index 00000000..bef7ad99 --- /dev/null +++ b/.agentd/skills/agent-memory/SKILL.md @@ -0,0 +1,49 @@ +--- +name: agent-memory +description: Store, search, and manage shared knowledge through the agentd memory service. Use for persisting information across agent sessions and inter-agent knowledge sharing. +--- + +# Agent Memory + +Skill for interacting with the agentd memory service — a vector-backed knowledge store for agents. + +## Storing Memories + +```bash +# Store a fact (default type: information, default visibility: public) +agent memory remember "The deployment key is in 1Password vault 'Infrastructure'" \ + --created-by worker --tags deploy,keys + +# Store a question +agent memory remember "Should we migrate to async Redis?" \ + --type question --tags redis,architecture + +# Store a request +agent memory remember "Need someone to review auth middleware rewrite" \ + --type request --tags review,auth +``` + +## Searching Memories + +```bash +# Basic semantic search +agent memory search "deployment procedures" --as-actor worker + +# Filter by tags +agent memory search "auth" --tags auth --type information --limit 5 + +# JSON output +agent memory search "redis" --json +``` + +## What to Remember + +- Architectural decisions and their rationale +- Patterns that worked or failed for specific areas +- Blockers or gotchas discovered during implementation +- Conventions not captured in CLAUDE.md + +## What NOT to Remember + +- Information already in code, comments, or git history +- Ephemeral task state (use conversation context for that) diff --git a/.agentd/skills/example/SKILL.md b/.agentd/skills/example/SKILL.md new file mode 100644 index 00000000..6932ac02 --- /dev/null +++ b/.agentd/skills/example/SKILL.md @@ -0,0 +1,33 @@ +--- +name: example +description: A minimal example skill demonstrating the skill file format. Copy and adapt this template to create your own skills. +--- + +# Example Skill + +This is a minimal example skill. Replace this content with instructions or +reference material for the agent. + +## What Skills Are For + +Skills are Markdown files that are injected into an agent's `.claude/skills/` +directory at spawn time. Claude Code discovers and can invoke them via the +`/skill` command. + +## Skill Format + +A skill file consists of: +1. An optional YAML frontmatter block (between `---` delimiters) +2. Markdown content with instructions, examples, or reference material + +### Frontmatter Fields + +- `name` — override the skill name (defaults to directory/filename stem) +- `description` — shown in `agent skill list` output + +## Tips + +- Write skills as instructions to the agent, not documentation for humans +- Use code blocks for commands the agent should run +- Keep skills focused on a single domain or tool +- Use `> [!IMPORTANT]` callouts for critical constraints diff --git a/.agentd/skills/git-spice/SKILL.md b/.agentd/skills/git-spice/SKILL.md new file mode 100644 index 00000000..787b2943 --- /dev/null +++ b/.agentd/skills/git-spice/SKILL.md @@ -0,0 +1,44 @@ +--- +name: git-spice +description: Branch stacking and PR management with git-spice. Use when creating stacked branches, submitting PRs, syncing with upstream, or navigating a branch stack. +--- + +# git-spice + +Reference skill for using git-spice (`git-spice`) in the agentd project. + +> [!IMPORTANT] +> **All agent usage MUST include `--no-prompt`** to prevent blocking on interactive input. + +## Common Workflows + +```bash +# Create a new stacked branch +git-spice branch create issue-NNN -m "feat: description" + +# Commit with auto-restack of dependents +git-spice commit create -m "feat(scope): description" + +# Submit a PR +git-spice branch submit --no-prompt --label review-agent \ + --title "feat: " \ + --body "<summary>\n\nCloses #N" + +# Sync with upstream +git-spice repo sync + +# Check stack state +git-spice log short +``` + +## Branch Naming + +- Implementation: `issue-NNN` +- Documentation: `docs/issue-NNN` +- Refactoring: `refactor/issue-NNN` + +## Notes + +- Never use raw `git checkout -b` — use `git-spice branch create` +- Never use `gh pr create` directly — use `git-spice branch submit` +- If TLS errors occur, fall back to `git push origin <branch>` + `gh pr create --base <base> --head <branch>` diff --git a/docs/agent-skills.md b/docs/agent-skills.md new file mode 100644 index 00000000..c2f7ab7d --- /dev/null +++ b/docs/agent-skills.md @@ -0,0 +1,323 @@ +# Agent Skills + +Agent skills are Markdown files that are automatically injected into an agent's +working directory at spawn time. They extend what Claude Code can do by making +pre-written instructions, workflows, and reference material available to the +agent via the `/skill` command. + +## Overview + +Skills bridge the gap between generic Claude Code capability and project-specific +or team-specific workflows. For example, a `git-spice` skill teaches an agent +exactly how the project uses git-spice for branch stacking, including naming +conventions, required flags, and TLS workarounds — without that context needing +to appear in every prompt. + +**How it works:** + +1. You write skill files in `.agentd/skills/` (checked into the repo) +2. Agent templates declare which skills to assign via the `skills` field +3. When `agent apply` spawns the agent, the orchestrator writes assigned skills + to `<working_dir>/.claude/skills/` before Claude Code starts +4. Claude Code discovers the skill files and makes them available via `/skill` + +## Skill File Format + +A skill file is a Markdown file with an optional YAML frontmatter block. + +### Directory layout (recommended) + +``` +.agentd/skills/ + git-spice/ + SKILL.md # <-- skill content here + agent-memory/ + SKILL.md +``` + +### Flat layout + +``` +.agentd/skills/ + git-spice.md # name derived from filename stem + agent-memory.md +``` + +Both layouts are supported. The directory layout is recommended because it +allows you to add supplementary files alongside the skill in the future. + +### Frontmatter + +```markdown +--- +name: git-spice +description: Branch stacking and PR management with git-spice. +--- + +# Git Spice + +Instructions for the agent... +``` + +**Supported frontmatter fields:** + +| Field | Required | Description | +|---|---|---| +| `name` | No | Override the skill name (defaults to directory or filename stem) | +| `description` | No | Short summary shown by `agent skill list` | + +## Discovery Paths + +agentd scans skill directories in priority order. When the same skill name +appears in multiple locations, the higher-priority source wins. + +| Priority | Path | Purpose | +|---|---|---| +| 1 (highest) | `.agentd/skills/` | Project-level skills (checked into the repo) | +| 2 | `~/.config/agentd/skills/` | User-level fallback (personal skills) | + +## Assigning Skills to Agents + +Skills are assigned in the agent YAML template using the `skills` field. + +### Specific skills + +```yaml +# .agentd/agents/worker.yml +name: worker +model: claude-sonnet-4-6 +skills: + - git-spice + - agent-memory + - service-ops +``` + +### All discovered skills + +```yaml +name: worker +model: claude-sonnet-4-6 +skills: all +``` + +Using `skills: all` expands to every skill discovered from `.agentd/skills/` +and `~/.config/agentd/skills/` at apply time. + +### No skills (default) + +```yaml +name: worker +model: claude-sonnet-4-6 +# skills field omitted — no agentd-managed skills +``` + +Omitting the `skills` field or setting `skills: []` assigns no skills. + +## Materialization + +When an agent is spawned, the orchestrator writes assigned skills to: + +``` +<working_dir>/.claude/skills/<name>/SKILL.md +``` + +**Important behavior:** + +- **Existing files are not overwritten.** If the agent's working directory + already has a `.claude/skills/<name>/SKILL.md`, the agentd-managed version is + skipped. This means the agent's own local skills always take precedence. +- **Missing skills produce warnings, not errors.** If a skill listed in the + template is not found in the discovered skill set, the agent still launches + but a warning is logged. +- **Directory structure is created automatically.** The `.claude/skills/<name>/` + directory is created if it does not exist. + +### Worktree agents + +When `worktree: true`, Claude Code creates a temporary git worktree for the +agent. Because `.claude/` is typically in `.gitignore`, the worktree does not +inherit materialized skills from the main working directory. + +Skills are written to the source `working_dir` *before* launch. The agent's +`additional_dirs` configuration (already wired through `build_claude_command`) +points back at the project root, so Claude Code discovers the skills via the +parent directory mechanism. + +## CLI Commands + +### List available skills + +```bash +agent skill list +``` + +Output: + +``` +agentd Skills +============================================================ + agent-memory Store, search, and manage shared knowledge + example A minimal example skill + git-spice Branch stacking and PR management + +3 skills available +``` + +With `--json` for scripting: + +```bash +agent skill list --json +``` + +```json +[ + { + "name": "agent-memory", + "description": "Store, search, and manage shared knowledge", + "content": "---\nname: agent-memory\n..." + } +] +``` + +### Show a skill + +```bash +agent skill show git-spice +``` + +Prints the full Markdown content of the skill to stdout. + +```bash +agent skill show git-spice --json +``` + +Outputs the full `Skill` object as JSON. + +## Writing Good Skills + +### Agent-facing vs human-facing + +Skills are instructions *to the agent*, not documentation for humans. Write +them as you would write a system prompt or a concise reference guide: + +- Use imperative voice ("Run X", "Always include Y") +- Use code blocks for commands the agent should execute +- Highlight constraints with `> [!IMPORTANT]` callouts +- Keep each skill focused on a single domain or tool + +### Minimal skill example + +```markdown +--- +name: my-tool +description: How to use my-tool in this project. +--- + +# my-tool + +Run `my-tool --help` to see available subcommands. + +## Common Commands + +\`\`\`bash +my-tool list +my-tool run <task-name> +\`\`\` + +> [!IMPORTANT] +> Always use `--dry-run` first when running in production. +``` + +### Testing a skill before assigning it + +1. Place the skill file in `.agentd/skills/<name>/SKILL.md` +2. Run `agent skill list` to verify it is discovered +3. Run `agent skill show <name>` to verify the content +4. Assign it to an agent template and run `agent apply .agentd/` +5. Verify the file was materialized: `ls <working_dir>/.claude/skills/<name>/` + +## Troubleshooting + +### Skill not found during `agent apply` + +``` +Agent 'worker' references unknown skill(s): my-skill. +Run 'agent skill list' to see available skills. +``` + +**Cause:** The skill name in the `skills:` list does not match any discovered +skill. + +**Fix:** Check the skill name by running `agent skill list`. Ensure the skill +file exists in `.agentd/skills/` with the correct directory name or frontmatter +`name` field. + +### Skill not appearing in `agent skill list` + +1. Check the path: `.agentd/skills/<name>/SKILL.md` or `.agentd/skills/<name>.md` +2. Check that the file has a `.md` extension (other extensions are ignored) +3. Check that the directory contains a `SKILL.md` file (not `skill.md` — the + filename is case-sensitive on Linux) +4. Run from the project root directory (`.agentd/skills/` is resolved relative + to the orchestrator's CWD) + +### Skill not loading in agent + +1. Verify materialization: `ls <working_dir>/.claude/skills/` +2. Check orchestrator logs for `materialized skills` or `skill materialization + failed` messages +3. If the file already exists, the agentd copy was skipped (agent-local takes + precedence) — check the existing file at `.claude/skills/<name>/SKILL.md` +4. For worktree agents, skills are in the source working directory, not the + worktree + +### Worktree agents and skills + +Skills are written to the source `working_dir` before launch. If the skill +does not appear available inside the worktree, ensure the project root is in +the agent's `additional_dirs` so Claude Code can discover skills from the +parent directory. + +## Reference + +### `Skill` struct + +```rust +pub struct Skill { + /// Skill identifier — from frontmatter `name` or directory/filename stem. + pub name: String, + /// Optional description from frontmatter. + pub description: Option<String>, + /// Full Markdown content including frontmatter. + pub content: String, +} +``` + +### `MaterializeResult` struct + +```rust +pub struct MaterializeResult { + /// Skills successfully written to .claude/skills/. + pub written: Vec<String>, + /// Skills skipped because the target file already existed. + pub skipped: Vec<String>, + /// Skills requested but not found in the discovered skill set. + pub not_found: Vec<String>, +} +``` + +### API endpoint + +``` +GET /skills +``` + +Returns a JSON array of all discovered skills (name + description only — +`source_path` is omitted from API responses): + +```json +[ + {"name": "git-spice", "description": "Branch stacking..."}, + {"name": "agent-memory", "description": "Memory service..."} +] +```