draft: example skills for proposed catalog restructuring

[marc0olo]

Context

This PR contains two draft SKILL.md files that demonstrate the proposed skill structure from the skills catalog restructuring analysis — see RFC Issue #52 for the full analysis and discussion.

These are not ready to merge into skills/ — the frontmatter uses the new Agent Skills spec-compliant format (metadata:, license, compatibility) which requires #45 to be resolved first.

What's included

_drafts/icp-cli/SKILL.md (273 lines)

• Tier 1 foundation skill for CLI tooling
• Covers: project creation, recipes, environments, canister operations, identity, cycles
• Uses icp-cli v0.2.0 command syntax

_drafts/canister-security/SKILL.md (366 lines)

• Tier 1 foundation skill for security patterns
• Covers: access control, inspect_message, anonymous caller rejection, async TOCTOU, freezing threshold, controller backup, root key handling (ic_env cookie, icp network status --json)
• Both Motoko and Rust implementations including system func inspect and #[inspect_message]

Key design decisions demonstrated

1. Spec-compliant frontmatter — custom fields under metadata:, license: Apache-2.0, compatibility replaces requires. Lean metadata: only title, category, version (dropped status, dependencies, endpoints, tags)
2. Self-contained skills — no cross-skill file links. Essential info is inlined where previously a link existed. Follows the same pattern as Anthropic's official skills
3. Under 500 lines — both skills stay within the recommended limit
4. "Use when... Do NOT use for..." — descriptions include agent routing trigger phrases
5. Pitfalls-first — the highest-value content is the "Mistakes That Break Your Build" section
6. Consistent prerequisite format — follows existing skill convention: tool >= version (install: \command`)`

Related

• RFC Analysis: RFC: Skills Catalog Restructuring — Analysis & Recommendations #52
• Frontmatter alignment: Align frontmatter with Agent Skills specification #45 (prerequisite for moving to skills/)
• Build simplification: refactor: remove redundant generated files from repo #50

[raymondk]

I'm not sure if this type of link is ok.
From the spec it sounds like the directory should be self contained: https://agentskills.io/specification

https://agentskills.io/specification#file-references

- icp-cli
  - SKILL.md
  - references
    - canister-security.md

[marc0olo]

Agreed — this cross-link violated the spec's self-contained directory requirement. It's been removed in 25cbe9f.

All cross-skill file links (../other-skill/SKILL.md) are now gone from both drafts. Where a link previously pointed to essential info (e.g., freezing threshold command, saga pattern), we inlined the key content directly. Where it was just a "see also" convenience, we dropped it.

Regarding the references/ subdirectory approach you suggested — that makes sense when a skill needs to progressively disclose its own detailed content (e.g., icp-cli/references/recipes.md). But we didn't go that route here because the referenced content (canister-security) is a separate skill with its own scope. Duplicating it as a reference file inside icp-cli/ would create content that drifts out of sync. Instead, the agent runtime handles the connection — when a user's task involves both CLI usage and security patterns, the agent loads both skills based on their description triggers.