mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-27 02:44:50 +01:00
Harold KimandPaperclip
98df214917
When reusing a Codex sandbox, the workspace-restore step now performs an auth-merge check before adopting the sandbox's auth.json. The merge fails closed when: - host or sandbox Codex auth is unusable (missing token or account) - the subscription payload shapes differ between host and sandbox - subscription account identities do not match Additional hardening: node absence on PATH during the embedded decision script now exits non-zero instead of silently falling through. Co-change comments link parseAuth (the embedded script) to hasUsableAuthPayload (codex-home.ts) so a future auth-format change cannot silently diverge between the two implementations. Co-Authored-By: Paperclip <noreply@paperclip.ing>
2.2 KiB
2.2 KiB
title, summary
| title | summary |
|---|---|
| Writing a Skill | SKILL.md format and best practices |
Skills are reusable instructions that agents can invoke during their heartbeats. They're markdown files that teach agents how to perform specific tasks.
Skill Structure
A skill is a directory containing a SKILL.md file with YAML frontmatter:
skills/
└── my-skill/
├── SKILL.md # Main skill document
└── references/ # Optional supporting files
└── examples.md
SKILL.md Format
---
name: my-skill
description: >
Short description of what this skill does and when to use it.
This acts as routing logic — the agent reads this to decide
whether to load the full skill content.
---
# My Skill
Detailed instructions for the agent...
Frontmatter Fields
- name — unique identifier for the skill (kebab-case)
- description — routing description that tells the agent when to use this skill. Write it as decision logic, not marketing copy.
How Skills Work at Runtime
- Agent sees skill metadata (name + description) in its context
- Agent decides whether the skill is relevant to its current task
- If relevant, agent loads the full SKILL.md content
- Agent follows the instructions in the skill
This keeps the base prompt small — full skill content is only loaded on demand.
Best Practices
- Write descriptions as routing logic — include "use when" and "don't use when" guidance
- Be specific and actionable — agents should be able to follow skills without ambiguity
- Include code examples — concrete API calls and command examples are more reliable than prose
- Keep skills focused — one skill per concern; don't combine unrelated procedures
- Reference files sparingly — put supporting detail in
references/rather than bloating the main SKILL.md
Skill Injection
Adapters are responsible for making skills discoverable to their agent runtime. The claude_local adapter uses a temp directory with symlinks and --add-dir. The codex_local adapter uses the global skills directory. See the Creating an Adapter guide for details.