ultanio/cobot

Fork 4

feat: skill system #207

New issue

Open

opened 2026-03-06 09:06:58 +00:00 by David · 0 comments

David commented

2026-03-06 09:06:58 +00:00

Contributor

stepsCompleted

classification

inputDocuments

documentCounts

workflowType

step-01-init

step-02-discovery

step-02b-vision

step-02c-executive-summary

step-03-success

step-04-journeys

step-05-domain

step-06-innovation

step-07-project-type

step-08-scoping

step-09-functional

step-10-nonfunctional

step-11-polish

projectType	domain	complexity	projectContext
cli_tool / developer_tool	decentralized_agent_infrastructure	medium	brownfield

_bmad-output/product-brief-Cobot-2026-03-02.md

_bmad-output/project-context.md

docs/index.md

docs/project-overview.md

docs/architecture.md

docs/development-guide.md

docs/for-agents.md

docs/source-tree-analysis.md

docs/RELEASE-PLAN.md

docs/quickstart.md

docs/plugin-design-guide.md

docs/architecture/session-plugin.md

docs/dev/conventions.md

briefs	research	brainstorming	projectDocs
1	0	0	11

prd

Product Requirements Document: Cobot Skill System

Author: David
Date: 2026-03-06

Executive Summary

Cobot is a minimal self-sovereign AI agent runtime (~6K lines of Python) built around the insight that agents need trust infrastructure before they can meaningfully cooperate. Today, Cobot has 20+ plugins covering identity (Nostr), communication (FileDrop, Telegram, Nostr DMs), economic capability (Lightning wallet), and LLM inference — but an agent's capabilities are fixed at deployment time.

This PRD defines a skill system that makes agent capabilities dynamic. Skills are markdown-based instruction files — portable, ecosystem-compatible (OpenClaw, Vercel agent-skills, Claude Code), and composable with Cobot's existing tools and plugins. The LLM discovers available skills from its system prompt and loads them on demand to execute workflows it couldn't perform before.

The skill system targets two horizons: v1 delivers discovery, loading, and execution of skills authored by developers, with lightweight provenance via Nostr npub in skill metadata. Future iterations unlock agent-to-agent skill sharing via FileDrop and self-improving agents that create their own skills — the point where Cobot agents become learning entities.

What Makes This Special

Skills sit at the top of Cobot's stack — pure context/instructions for the LLM. They automatically inherit whatever trust, security, and capability layers exist below. Because every identity in Cobot is a Nostr npub, skill authorship comes with cryptographic provenance without needing a separate trust mechanism. An agent evaluating whether to install a skill asks the same question it asks about any interaction: "do I trust this npub?" This reuses existing infrastructure (pairing today, WoT tomorrow) rather than creating skill-specific auth.

Format compatibility with the emerging agent skills standard means instant access to a growing ecosystem of community-authored skills. Identity-aware provenance means Cobot agents can evaluate skills by who wrote them — a natural defense against compromised skill registries that no other agent runtime can offer because no other runtime has identity infrastructure.

Project Classification

Project Type: CLI tool / developer tool (agent runtime with plugin SDK)
Domain: Decentralized agent infrastructure (Nostr identity, Lightning payments, Web of Trust)
Complexity: Medium (well-bounded feature — new plugin + system prompt integration + file discovery, building on proven patterns)
Project Context: Brownfield (adding to existing ~6K LOC codebase with 20+ plugins, v0.2.0 released)

Success Criteria

User Success

Developer (skill consumer):

Adds a community skill in under 1 minute: cobot skill add <github-repo> --skill <name>, available on next run
Drops a local skill file into skills/ — agent gains new capability with zero code changes
Lists installed skills and understands what each does: cobot skill list

Agent (autonomous skill user):

Receives a React UI coding task, recognizes the react-best-practices skill from its system prompt, loads it via load_skill, and follows the skill's guidelines without human prompting
The aha moment: an agent autonomously loads the right skill for the right task

Business Success

Cobot agents leverage the existing skill ecosystem (Vercel agent-skills, Claude Code skills, community skills) without format translation
Skills become the primary mechanism for extending agent capabilities beyond what plugins provide
Foundation laid for future agent-to-agent skill sharing and self-authored skills

Technical Success

Implemented as a single plugin following all existing architecture patterns (PluginMeta, extension points, capability interfaces)
Minimal footprint consistent with Cobot's ~6K LOC philosophy
No existing plugins modified ("adding a plugin never requires editing another plugin")
Skills injected via context.system_prompt integrate with existing trust plugin (role: system, automatically treated as authoritative)

Measurable Outcomes

Metric	Target
Time to install a remote skill	< 60 seconds
Time to use a local skill file	0 (drop file, restart)
New plugins required	1 (`skills`)
Existing plugins modified	0
Skill format compatibility	OpenClaw / Vercel agent-skills / Claude Code

Product Scope

MVP Strategy

Approach: Problem-solving MVP — the minimum that makes skills work end-to-end. A developer installs a skill, the agent discovers it at startup, recognizes when to use it, and loads it on demand.

Resource Requirements: Single developer. One new plugin (skills), one new tool (load_skill), CLI subcommands. No changes to existing plugins.

MVP Feature Set (Phase 1)

Core Journeys Supported:

Install a community skill (CLI skill add from GitHub/Forgejo/local path)
Agent autonomously discovers and uses a skill (system prompt + load_skill)
Author a custom skill (drop SKILL.md into skills/, restart)
Evaluate and manage skills (skill list, skill show, skill remove)

Must-Have Capabilities:

Capability	Description
Skills plugin	Discovers SKILL.md files from configured paths, implements `context.system_prompt`
System prompt injection	Compact `<available_skills>` XML block (name, description, location)
`load_skill` tool	LLM tool to read and format skill content, resolves relative paths within skill folder
`cobot skill add`	Install from GitHub/Forgejo/local path via `git clone` + copy
`cobot skill list`	Display installed skills with name, description, source, author
`cobot skill show`	Display single skill metadata and content summary
`cobot skill remove`	Uninstall by name
Skill format	SKILL.md with YAML frontmatter (name, description, author npub). Only SKILL.md required at root; all other structure is author's choice
Config integration	`skills.paths` and `skills.disabled` in `cobot.yml`
Provenance display	Show author npub, flag as "unverified" if not in `trusted` contacts

Phase 2: Growth (Post-MVP)

Skills watcher / hot reload (detect new/changed skills without restart)
cobot skill search for community registries
Skill gating via metadata (required tools, env vars, config — following OpenClaw pattern)
Skill validation/linting on install
Trust-gated installation: check author npub against pairing/WoT before installing

Phase 3: Vision (Future)

Agent-to-agent skill sharing via FileDrop
Self-authored skills: agent creates SKILL.md from learned workflows
WoT-rated skill authors: community trust scores on skill publishers
Skill versioning and update notifications
Skill composition: skills referencing other skills as dependencies
Skill store integration (ClawHub-style registry)

Risk Mitigation

Technical Risks:

System prompt bloat with many skills: mitigated by compact XML format (~97 chars + field lengths per skill, deterministic token cost)
Malicious skill content: skills are role: system and trusted by the LLM; mitigation is provenance checks at install time (npub verification) and quick removal (skill remove)
Git dependency for skill add: git is expected on developer machines; local path install works as fallback

Market Risks:

Skill ecosystem adoption: mitigated by format compatibility with OpenClaw/Vercel/Claude Code; existing skills work without modification
Skill quality variance: mitigated by provenance display; future WoT ratings add community signal

Resource Risks:

Single plugin implementation; if time is tight, CLI install (skill add) could be deferred (manual file placement works), but core plugin + system prompt + load_skill tool are non-negotiable MVP

User Journeys

Journey 1: David installs a community skill (Developer - Success Path)

David is building a Cobot agent that helps with frontend development. He's heard about the Vercel react-best-practices skill and wants his agent to use it. He runs cobot skill add vercel-labs/agent-skills --skill react-best-practices. The CLI clones the skill into ~/.cobot/skills/react-best-practices/, validates the SKILL.md frontmatter, and confirms: "Installed react-best-practices (v1.0.0) by vercel". On next cobot run, the skill appears in the agent's system prompt. David messages his agent "refactor this component for performance" and the agent loads the skill, follows its guidelines, and delivers optimized code. David realizes he never has to re-explain React best practices to his agent again.

Journey 2: Alpha autonomously uses a skill (Agent - Success Path)

Alpha is running with three installed skills: react-best-practices, git-workflow, and code-review. A human asks Alpha to "build a React dashboard with charts." Alpha's system prompt lists available skills with trigger descriptions. It recognizes "React" matches react-best-practices, calls load_skill to read the full SKILL.md, and discovers multiple topic areas. As it builds components, it follows references in the SKILL.md to load relevant sub-files on demand — reading guidance on server vs client components when making that decision, loading bundle optimization advice when adding chart libraries. The sub-file structure is whatever the skill author chose; the LLM simply follows the references in SKILL.md. The human gets performant code without knowing a skill was involved.

Journey 3: David creates a custom skill (Developer - Authoring)

David has a set of Cobot-specific conventions he keeps explaining to his agent. He creates skills/cobot-plugin-dev/SKILL.md with frontmatter: name: cobot-plugin-dev, description: "Guidelines for developing Cobot plugins following architecture patterns". The body references supporting files he organizes however he sees fit — the only requirement is that SKILL.md is at the root. On restart, the skill appears in the agent's available skills. Next time he asks his agent to create a plugin, it loads the skill and follows all conventions — PluginMeta vocabulary, priority bands, co-located tests, factory functions. No more correcting the agent on architecture patterns.

Journey 4: David troubleshoots a skill issue (Developer - Edge Case)

David installs a skill from an unknown GitHub author. He runs cobot skill add someuser/ai-skills --skill prompt-engineering. The install succeeds but shows a notice: "Author npub: npub1abc... (unknown identity — not in your trust network)". David runs cobot skill list and sees the skill flagged as "unverified author." He inspects the SKILL.md manually, decides it looks fine, and keeps it. Later, when the skill produces unexpected guidance, he can cobot skill remove prompt-engineering in seconds. The provenance warning gave him the information to make an informed decision.

Journey Requirements Summary

Journey	Capabilities Revealed
Install community skill	CLI `skill add` with GitHub/Forgejo integration, frontmatter validation, skill directory management
Agent uses skill autonomously	System prompt injection, `load_skill` tool, relative path resolution for sub-files referenced in SKILL.md
Author custom skill	Skill format spec (only SKILL.md required at root, all other structure is author's choice), usable on restart
Troubleshoot/evaluate skill	`skill list` with provenance display, `skill remove`, npub author verification notice

CLI/Developer Tool Specific Requirements

Command Structure

cobot skill add <source> --skill <name1> [name2...]   # Install from GitHub/Forgejo/local path
cobot skill list                                       # List installed skills
cobot skill show <name>                                # Show skill metadata
cobot skill remove <name>                              # Uninstall a skill

Source detection:

Local path: ./path, /absolute/path, ~/home/path
Git URL: https://forgejo.tail593e12.ts.net/ultanio/skills, https://github.com/user/repo
Shorthand: user/repo (resolves to GitHub by default)

Configuration Schema

# cobot.yml
skills:
  paths:                    # Skill discovery directories
    - ./skills              # Workspace skills
    - ~/.cobot/skills       # User-wide skills
  disabled:                 # Skills to skip loading
    - some-skill-name

# Existing section - no changes needed
trusted:                    # Used for skill author verification
  - npub: "npub1..."
    name: "Vercel"
    role: "skill-author"

Implementation Considerations

Skills plugin registers CLI commands via cli.commands extension point (same pattern as pairing, subagent)
git clone for remote sources — forge-agnostic (GitHub, Forgejo, GitLab)
paths.skills already exists in cobot.yml.example — skills plugin reads from this
Author npub checked against existing trusted contacts list — no new trust infrastructure
Skill discovery follows same priority as plugin discovery: workspace first, then user directory

Functional Requirements

Skill Discovery & Loading

FR1: The skills plugin can discover SKILL.md files from configured directory paths at startup
FR2: The skills plugin can resolve skill precedence when the same skill name exists in multiple paths (workspace wins over user directory)
FR3: The skills plugin can parse YAML frontmatter from SKILL.md files to extract metadata (name, description, author npub, version)
FR4: The skills plugin can inject a compact available skills list into the system prompt via the context.system_prompt extension point
FR5: The skills plugin can omit the skills section from the system prompt when no skills are installed
FR6: The skills plugin can exclude disabled skills (listed in skills.disabled config) from discovery

Skill Execution

FR7: The agent can recognize when an incoming task matches an available skill based on the skill's description and trigger context in the system prompt
FR8: The agent can load a skill's full SKILL.md content on demand via the load_skill tool
FR9: The load_skill tool can resolve relative file paths referenced in SKILL.md against the skill's root directory
FR10: The agent can use existing tools (read_file) to load sub-files referenced within a loaded skill

Skill Installation (CLI)

FR11: A developer can install skills from a GitHub repository via cobot skill add <user/repo> --skill <name>
FR12: A developer can install skills from any git-compatible URL (Forgejo, GitLab) via cobot skill add <url> --skill <name>
FR13: A developer can install skills from a local path via cobot skill add <path>
FR14: The CLI can auto-detect whether the source argument is a local path, a full URL, or a GitHub shorthand
FR15: A developer can install multiple skills from a single source in one command via --skill <name1> <name2>
FR16: The CLI can validate that a SKILL.md exists with required frontmatter fields before completing installation

Skill Management (CLI)

FR17: A developer can list all installed skills with cobot skill list, showing name, description, source, and author
FR18: A developer can view detailed metadata for a single skill with cobot skill show <name>
FR19: A developer can uninstall a skill by name with cobot skill remove <name>

Skill Authoring

FR20: A developer can create a skill by placing a SKILL.md file (with frontmatter) in any configured skill path
FR21: A skill author can organize supporting files in any directory structure within the skill folder — only SKILL.md at root is required
FR22: A skill author can reference sub-files from SKILL.md using relative paths that the LLM resolves at load time

Skill Format & Compatibility

FR23: The skill format supports YAML frontmatter with fields: name (required), description (required), author (optional npub), version (optional)
FR24: The skill format is compatible with the AgentSkills spec (OpenClaw, Vercel agent-skills, Claude Code)
FR25: Skills authored for other platforms (OpenClaw, Vercel) work in Cobot without modification

Provenance & Trust

FR26: The skills plugin can display the author npub from skill frontmatter
FR27: The skills plugin can check the author npub against the existing trusted contacts list in cobot.yml
FR28: The CLI flags skills from unverified authors (npub not in trusted list or missing) during installation and listing
FR29: Provenance checks use the same identity infrastructure as all other Cobot identity lookups — no skill-specific trust mechanism

Configuration

FR30: A developer can configure skill discovery paths via skills.paths in cobot.yml
FR31: A developer can disable specific skills via skills.disabled in cobot.yml

Non-Functional Requirements

Performance

NFR1: Skill discovery at startup adds < 100ms to agent boot time for up to 50 installed skills
NFR2: System prompt skill injection adds < 200 tokens overhead per installed skill (compact XML format)
NFR3: load_skill tool returns skill content within the same latency as read_file for equivalent file sizes
NFR4: cobot skill add from a remote git source completes within network latency + 5 seconds for post-processing (clone, validate, copy)

Security

NFR5: Skill content is injected as part of the system prompt (role: system) — the existing trust plugin's trust model applies without modification
NFR6: Skills cannot override or modify the core system prompt (SOUL.md) — they are additive context only
NFR7: The load_skill tool restricts file reads to within the skill's own directory — no path traversal outside the skill root
NFR8: Author npub verification provides informational trust signals — it does not block installation (user decides)

Compatibility

NFR9: Skills following the AgentSkills spec (SKILL.md with name and description frontmatter) work without Cobot-specific modifications
NFR10: Cobot-specific frontmatter extensions (e.g., author npub) are ignored by other platforms — no breaking changes to the spec
NFR11: Skills plugin follows all Cobot architecture patterns: PluginMeta declarations, extension point integration, factory function, co-located tests

Maintainability

NFR12: Skills plugin total LOC stays consistent with Cobot's minimalism — target comparable to existing plugins of similar scope (e.g., subagent at ~380 LOC)
NFR13: Zero modifications to existing plugins required — the skill system integrates purely through declared capabilities and extension points

--- stepsCompleted: - step-01-init - step-02-discovery - step-02b-vision - step-02c-executive-summary - step-03-success - step-04-journeys - step-05-domain - step-06-innovation - step-07-project-type - step-08-scoping - step-09-functional - step-10-nonfunctional - step-11-polish classification: projectType: cli_tool / developer_tool domain: decentralized_agent_infrastructure complexity: medium projectContext: brownfield inputDocuments: - _bmad-output/product-brief-Cobot-2026-03-02.md - _bmad-output/project-context.md - docs/index.md - docs/project-overview.md - docs/architecture.md - docs/development-guide.md - docs/for-agents.md - docs/source-tree-analysis.md - docs/RELEASE-PLAN.md - docs/quickstart.md - docs/plugin-design-guide.md - docs/architecture/session-plugin.md - docs/dev/conventions.md documentCounts: briefs: 1 research: 0 brainstorming: 0 projectDocs: 11 workflowType: 'prd' --- # Product Requirements Document: Cobot Skill System **Author:** David **Date:** 2026-03-06 ## Executive Summary Cobot is a minimal self-sovereign AI agent runtime (~6K lines of Python) built around the insight that agents need trust infrastructure before they can meaningfully cooperate. Today, Cobot has 20+ plugins covering identity (Nostr), communication (FileDrop, Telegram, Nostr DMs), economic capability (Lightning wallet), and LLM inference — but an agent's capabilities are fixed at deployment time. This PRD defines a **skill system** that makes agent capabilities dynamic. Skills are markdown-based instruction files — portable, ecosystem-compatible (OpenClaw, Vercel agent-skills, Claude Code), and composable with Cobot's existing tools and plugins. The LLM discovers available skills from its system prompt and loads them on demand to execute workflows it couldn't perform before. The skill system targets two horizons: **v1** delivers discovery, loading, and execution of skills authored by developers, with lightweight provenance via Nostr npub in skill metadata. **Future iterations** unlock agent-to-agent skill sharing via FileDrop and self-improving agents that create their own skills — the point where Cobot agents become learning entities. ### What Makes This Special Skills sit at the top of Cobot's stack — pure context/instructions for the LLM. They automatically inherit whatever trust, security, and capability layers exist below. Because every identity in Cobot is a Nostr npub, skill authorship comes with cryptographic provenance without needing a separate trust mechanism. An agent evaluating whether to install a skill asks the same question it asks about any interaction: "do I trust this npub?" This reuses existing infrastructure (pairing today, WoT tomorrow) rather than creating skill-specific auth. Format compatibility with the emerging agent skills standard means instant access to a growing ecosystem of community-authored skills. Identity-aware provenance means Cobot agents can evaluate skills by who wrote them — a natural defense against compromised skill registries that no other agent runtime can offer because no other runtime has identity infrastructure. ## Project Classification - **Project Type:** CLI tool / developer tool (agent runtime with plugin SDK) - **Domain:** Decentralized agent infrastructure (Nostr identity, Lightning payments, Web of Trust) - **Complexity:** Medium (well-bounded feature — new plugin + system prompt integration + file discovery, building on proven patterns) - **Project Context:** Brownfield (adding to existing ~6K LOC codebase with 20+ plugins, v0.2.0 released) ## Success Criteria ### User Success **Developer (skill consumer):** - Adds a community skill in under 1 minute: `cobot skill add <github-repo> --skill <name>`, available on next run - Drops a local skill file into `skills/` — agent gains new capability with zero code changes - Lists installed skills and understands what each does: `cobot skill list` **Agent (autonomous skill user):** - Receives a React UI coding task, recognizes the `react-best-practices` skill from its system prompt, loads it via `load_skill`, and follows the skill's guidelines without human prompting - The aha moment: an agent autonomously loads the right skill for the right task ### Business Success - Cobot agents leverage the existing skill ecosystem (Vercel agent-skills, Claude Code skills, community skills) without format translation - Skills become the primary mechanism for extending agent capabilities beyond what plugins provide - Foundation laid for future agent-to-agent skill sharing and self-authored skills ### Technical Success - Implemented as a single plugin following all existing architecture patterns (PluginMeta, extension points, capability interfaces) - Minimal footprint consistent with Cobot's ~6K LOC philosophy - No existing plugins modified ("adding a plugin never requires editing another plugin") - Skills injected via `context.system_prompt` integrate with existing trust plugin (`role: system`, automatically treated as authoritative) ### Measurable Outcomes | Metric | Target | |--------|--------| | Time to install a remote skill | < 60 seconds | | Time to use a local skill file | 0 (drop file, restart) | | New plugins required | 1 (`skills`) | | Existing plugins modified | 0 | | Skill format compatibility | OpenClaw / Vercel agent-skills / Claude Code | ## Product Scope ### MVP Strategy **Approach:** Problem-solving MVP — the minimum that makes skills work end-to-end. A developer installs a skill, the agent discovers it at startup, recognizes when to use it, and loads it on demand. **Resource Requirements:** Single developer. One new plugin (`skills`), one new tool (`load_skill`), CLI subcommands. No changes to existing plugins. ### MVP Feature Set (Phase 1) **Core Journeys Supported:** - Install a community skill (CLI `skill add` from GitHub/Forgejo/local path) - Agent autonomously discovers and uses a skill (system prompt + `load_skill`) - Author a custom skill (drop SKILL.md into `skills/`, restart) - Evaluate and manage skills (`skill list`, `skill show`, `skill remove`) **Must-Have Capabilities:** | Capability | Description | |-----------|-------------| | Skills plugin | Discovers SKILL.md files from configured paths, implements `context.system_prompt` | | System prompt injection | Compact `<available_skills>` XML block (name, description, location) | | `load_skill` tool | LLM tool to read and format skill content, resolves relative paths within skill folder | | `cobot skill add` | Install from GitHub/Forgejo/local path via `git clone` + copy | | `cobot skill list` | Display installed skills with name, description, source, author | | `cobot skill show` | Display single skill metadata and content summary | | `cobot skill remove` | Uninstall by name | | Skill format | SKILL.md with YAML frontmatter (name, description, author npub). Only SKILL.md required at root; all other structure is author's choice | | Config integration | `skills.paths` and `skills.disabled` in `cobot.yml` | | Provenance display | Show author npub, flag as "unverified" if not in `trusted` contacts | ### Phase 2: Growth (Post-MVP) - Skills watcher / hot reload (detect new/changed skills without restart) - `cobot skill search` for community registries - Skill gating via metadata (required tools, env vars, config — following OpenClaw pattern) - Skill validation/linting on install - Trust-gated installation: check author npub against pairing/WoT before installing ### Phase 3: Vision (Future) - Agent-to-agent skill sharing via FileDrop - Self-authored skills: agent creates SKILL.md from learned workflows - WoT-rated skill authors: community trust scores on skill publishers - Skill versioning and update notifications - Skill composition: skills referencing other skills as dependencies - Skill store integration (ClawHub-style registry) ### Risk Mitigation **Technical Risks:** - System prompt bloat with many skills: mitigated by compact XML format (~97 chars + field lengths per skill, deterministic token cost) - Malicious skill content: skills are `role: system` and trusted by the LLM; mitigation is provenance checks at install time (npub verification) and quick removal (`skill remove`) - Git dependency for `skill add`: `git` is expected on developer machines; local path install works as fallback **Market Risks:** - Skill ecosystem adoption: mitigated by format compatibility with OpenClaw/Vercel/Claude Code; existing skills work without modification - Skill quality variance: mitigated by provenance display; future WoT ratings add community signal **Resource Risks:** - Single plugin implementation; if time is tight, CLI install (`skill add`) could be deferred (manual file placement works), but core plugin + system prompt + `load_skill` tool are non-negotiable MVP ## User Journeys ### Journey 1: David installs a community skill (Developer - Success Path) David is building a Cobot agent that helps with frontend development. He's heard about the Vercel react-best-practices skill and wants his agent to use it. He runs `cobot skill add vercel-labs/agent-skills --skill react-best-practices`. The CLI clones the skill into `~/.cobot/skills/react-best-practices/`, validates the SKILL.md frontmatter, and confirms: "Installed react-best-practices (v1.0.0) by vercel". On next `cobot run`, the skill appears in the agent's system prompt. David messages his agent "refactor this component for performance" and the agent loads the skill, follows its guidelines, and delivers optimized code. David realizes he never has to re-explain React best practices to his agent again. ### Journey 2: Alpha autonomously uses a skill (Agent - Success Path) Alpha is running with three installed skills: `react-best-practices`, `git-workflow`, and `code-review`. A human asks Alpha to "build a React dashboard with charts." Alpha's system prompt lists available skills with trigger descriptions. It recognizes "React" matches `react-best-practices`, calls `load_skill` to read the full SKILL.md, and discovers multiple topic areas. As it builds components, it follows references in the SKILL.md to load relevant sub-files on demand — reading guidance on server vs client components when making that decision, loading bundle optimization advice when adding chart libraries. The sub-file structure is whatever the skill author chose; the LLM simply follows the references in SKILL.md. The human gets performant code without knowing a skill was involved. ### Journey 3: David creates a custom skill (Developer - Authoring) David has a set of Cobot-specific conventions he keeps explaining to his agent. He creates `skills/cobot-plugin-dev/SKILL.md` with frontmatter: `name: cobot-plugin-dev`, `description: "Guidelines for developing Cobot plugins following architecture patterns"`. The body references supporting files he organizes however he sees fit — the only requirement is that SKILL.md is at the root. On restart, the skill appears in the agent's available skills. Next time he asks his agent to create a plugin, it loads the skill and follows all conventions — PluginMeta vocabulary, priority bands, co-located tests, factory functions. No more correcting the agent on architecture patterns. ### Journey 4: David troubleshoots a skill issue (Developer - Edge Case) David installs a skill from an unknown GitHub author. He runs `cobot skill add someuser/ai-skills --skill prompt-engineering`. The install succeeds but shows a notice: "Author npub: npub1abc... (unknown identity — not in your trust network)". David runs `cobot skill list` and sees the skill flagged as "unverified author." He inspects the SKILL.md manually, decides it looks fine, and keeps it. Later, when the skill produces unexpected guidance, he can `cobot skill remove prompt-engineering` in seconds. The provenance warning gave him the information to make an informed decision. ### Journey Requirements Summary | Journey | Capabilities Revealed | |---------|----------------------| | Install community skill | CLI `skill add` with GitHub/Forgejo integration, frontmatter validation, skill directory management | | Agent uses skill autonomously | System prompt injection, `load_skill` tool, relative path resolution for sub-files referenced in SKILL.md | | Author custom skill | Skill format spec (only SKILL.md required at root, all other structure is author's choice), usable on restart | | Troubleshoot/evaluate skill | `skill list` with provenance display, `skill remove`, npub author verification notice | ## CLI/Developer Tool Specific Requirements ### Command Structure ``` cobot skill add <source> --skill <name1> [name2...] # Install from GitHub/Forgejo/local path cobot skill list # List installed skills cobot skill show <name> # Show skill metadata cobot skill remove <name> # Uninstall a skill ``` Source detection: - Local path: `./path`, `/absolute/path`, `~/home/path` - Git URL: `https://forgejo.tail593e12.ts.net/ultanio/skills`, `https://github.com/user/repo` - Shorthand: `user/repo` (resolves to GitHub by default) ### Configuration Schema ```yaml # cobot.yml skills: paths: # Skill discovery directories - ./skills # Workspace skills - ~/.cobot/skills # User-wide skills disabled: # Skills to skip loading - some-skill-name # Existing section - no changes needed trusted: # Used for skill author verification - npub: "npub1..." name: "Vercel" role: "skill-author" ``` ### Implementation Considerations - Skills plugin registers CLI commands via `cli.commands` extension point (same pattern as pairing, subagent) - `git clone` for remote sources — forge-agnostic (GitHub, Forgejo, GitLab) - `paths.skills` already exists in `cobot.yml.example` — skills plugin reads from this - Author npub checked against existing `trusted` contacts list — no new trust infrastructure - Skill discovery follows same priority as plugin discovery: workspace first, then user directory ## Functional Requirements ### Skill Discovery & Loading - **FR1:** The skills plugin can discover SKILL.md files from configured directory paths at startup - **FR2:** The skills plugin can resolve skill precedence when the same skill name exists in multiple paths (workspace wins over user directory) - **FR3:** The skills plugin can parse YAML frontmatter from SKILL.md files to extract metadata (name, description, author npub, version) - **FR4:** The skills plugin can inject a compact available skills list into the system prompt via the `context.system_prompt` extension point - **FR5:** The skills plugin can omit the skills section from the system prompt when no skills are installed - **FR6:** The skills plugin can exclude disabled skills (listed in `skills.disabled` config) from discovery ### Skill Execution - **FR7:** The agent can recognize when an incoming task matches an available skill based on the skill's description and trigger context in the system prompt - **FR8:** The agent can load a skill's full SKILL.md content on demand via the `load_skill` tool - **FR9:** The `load_skill` tool can resolve relative file paths referenced in SKILL.md against the skill's root directory - **FR10:** The agent can use existing tools (`read_file`) to load sub-files referenced within a loaded skill ### Skill Installation (CLI) - **FR11:** A developer can install skills from a GitHub repository via `cobot skill add <user/repo> --skill <name>` - **FR12:** A developer can install skills from any git-compatible URL (Forgejo, GitLab) via `cobot skill add <url> --skill <name>` - **FR13:** A developer can install skills from a local path via `cobot skill add <path>` - **FR14:** The CLI can auto-detect whether the source argument is a local path, a full URL, or a GitHub shorthand - **FR15:** A developer can install multiple skills from a single source in one command via `--skill <name1> <name2>` - **FR16:** The CLI can validate that a SKILL.md exists with required frontmatter fields before completing installation ### Skill Management (CLI) - **FR17:** A developer can list all installed skills with `cobot skill list`, showing name, description, source, and author - **FR18:** A developer can view detailed metadata for a single skill with `cobot skill show <name>` - **FR19:** A developer can uninstall a skill by name with `cobot skill remove <name>` ### Skill Authoring - **FR20:** A developer can create a skill by placing a SKILL.md file (with frontmatter) in any configured skill path - **FR21:** A skill author can organize supporting files in any directory structure within the skill folder — only SKILL.md at root is required - **FR22:** A skill author can reference sub-files from SKILL.md using relative paths that the LLM resolves at load time ### Skill Format & Compatibility - **FR23:** The skill format supports YAML frontmatter with fields: `name` (required), `description` (required), `author` (optional npub), `version` (optional) - **FR24:** The skill format is compatible with the AgentSkills spec (OpenClaw, Vercel agent-skills, Claude Code) - **FR25:** Skills authored for other platforms (OpenClaw, Vercel) work in Cobot without modification ### Provenance & Trust - **FR26:** The skills plugin can display the author npub from skill frontmatter - **FR27:** The skills plugin can check the author npub against the existing `trusted` contacts list in `cobot.yml` - **FR28:** The CLI flags skills from unverified authors (npub not in `trusted` list or missing) during installation and listing - **FR29:** Provenance checks use the same identity infrastructure as all other Cobot identity lookups — no skill-specific trust mechanism ### Configuration - **FR30:** A developer can configure skill discovery paths via `skills.paths` in `cobot.yml` - **FR31:** A developer can disable specific skills via `skills.disabled` in `cobot.yml` ## Non-Functional Requirements ### Performance - **NFR1:** Skill discovery at startup adds < 100ms to agent boot time for up to 50 installed skills - **NFR2:** System prompt skill injection adds < 200 tokens overhead per installed skill (compact XML format) - **NFR3:** `load_skill` tool returns skill content within the same latency as `read_file` for equivalent file sizes - **NFR4:** `cobot skill add` from a remote git source completes within network latency + 5 seconds for post-processing (clone, validate, copy) ### Security - **NFR5:** Skill content is injected as part of the system prompt (`role: system`) — the existing trust plugin's trust model applies without modification - **NFR6:** Skills cannot override or modify the core system prompt (SOUL.md) — they are additive context only - **NFR7:** The `load_skill` tool restricts file reads to within the skill's own directory — no path traversal outside the skill root - **NFR8:** Author npub verification provides informational trust signals — it does not block installation (user decides) ### Compatibility - **NFR9:** Skills following the AgentSkills spec (SKILL.md with `name` and `description` frontmatter) work without Cobot-specific modifications - **NFR10:** Cobot-specific frontmatter extensions (e.g., `author` npub) are ignored by other platforms — no breaking changes to the spec - **NFR11:** Skills plugin follows all Cobot architecture patterns: PluginMeta declarations, extension point integration, factory function, co-located tests ### Maintainability - **NFR12:** Skills plugin total LOC stays consistent with Cobot's minimalism — target comparable to existing plugins of similar scope (e.g., subagent at ~380 LOC) - **NFR13:** Zero modifications to existing plugins required — the skill system integrates purely through declared capabilities and extension points